Skip to main content
POST
Initiate a payment

Authorizations

Authorization
string
header
required

JWT bearer token issued by the identity provider.

Headers

X-Organization-Id
string

Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025.

Idempotency-Key
string
required

Client-supplied idempotency key, a UUID. Required: a request without it, or with a value that is not a UUID, is refused with 400 PBP-0012.

Body

application/json
digitableLine
string
required

Bankslip or utilities digitable line, digits only.

Example:

"00190500954014481606906809350314337370000000100"

midazAccountId
string
required

Midaz account the payment settles from. Who PAYS is the registered owner of this account, read from the Midaz CRM — the request does not state a payer.

description
string

Free-text description carried on the payment.

ledgerId
string

Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.

Response

Created. The payment provider acknowledged the payment: it is in status CREATED and carries the provider's providerId. Its outcome arrives later; follow it with GET /v1/payments/{id}. A request under an Idempotency-Key that already names a payment the provider acknowledged is answered 201 too, with that payment as it stands, in whatever status it has reached. Compare the 202, where the outcome at the provider is not known.

amount
string
required
createdAt
string
required
digitableLine
string
required
id
string
required
ledgerId
string
required

Midaz ledger the payment was written with. Always present.

organizationId
string
required

Midaz organization the payment was written with. Always present.

status
string
required

The payment's status when this answer was produced. CREATED on a 201 for a new payment; UNCONFIRMED on a 202, while the outcome at the payment provider is unknown. A request already on record is answered with the payment's status at that moment, which may be any status a payment takes. A replay of the same Idempotency-Key serves the stored answer, whose status may since have changed: read the payment by id for its current state.

type
string
required
dueDate
string
providerId
string

Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED (the 202 answer): the provider has acknowledged nothing yet. Read the payment by id later to obtain it.

providerRequestId
string

Reference this API sent to the payment provider when it instructed the payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. Absent when the payment carries no such reference.