Create a PIX transaction

Creates an outbound PIX payment. What happens next depends on where the payee is, and the two branches answer with different statuses and different bodies — a client has to handle both.

An on-us payee (payee.ispb equal to this participant’s own ISPB, on a direct order) settles SYNCHRONOUSLY as an INTRA_PSP ledger transfer and answers 201 with the transaction already EXECUTED. Any other payee settles over SPI in TWO PHASES: the amount is first HELD on the paying position as a pending ledger debit, and only then is the order submitted to JDPI (§8.4.1), which is asynchronous by design — nothing has settled when the call returns. A direct order answers 201 with the transaction PENDING; an order routed through a registered indirect (indirectId in the body) answers 202 carrying JD’s own §8.4.1 acknowledgement byte-for-byte, whose idReqJdPi is the handle the outcome is read with. Either way, poll GET /v1/transactions/: a background reconciler consults JDPI §8.4.2 and then commits or cancels the hold, and the money is not settled until the status says so.

WHAT indirectId ACTUALLY MOVES, because it is more than a label. This participant may serve INDIRECT participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant’s ISPB. Naming one on an order changes THREE things at once: the amount is held on that institution’s @pi_{ispb} settlement position instead of on the payer’s own, the persisted order is stamped with that institution so it appears in GET /v1/indirects//transactions, and the response shape changes from 201-plus-plugin-body to 202-plus-JD-body. The identifier is ROUTING DATA, not a credential: this participant authenticates you, and guaranteeing that the order really belongs to that institution is your responsibility, not this API’s.

⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT’S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF. With the feature off the value is not parsed, not resolved and not refused: the order runs as a DIRECT one, holding the amount on the direct participant’s own position and answering 201. Nothing in the response says the routing was dropped. Confirm the feature is on before sending the first order for an institution — an unknown id answering 404 PIX-0095 is the evidence that it is.

When the order reaches its outcome, an indirect order may ALSO push a NOTICE to the endpoint that registration carries (delivery.endpointUrl), queued by the background reconciler once JD’s terminal outcome is known — an HTTPS POST forwarding JD’s own result body verbatim, carrying X-Lerian-Signature (‘sha256=’ followed by the hex HMAC-SHA256 of the exact body bytes under the registration’s shared secret) and X-Lerian-Timestamp. Do not build on the notice arriving. No notice is queued at all when this deployment has no outbound queue configured, and none is queued when the outcome carries no JD result body to forward — an order cancelled locally, without a JD answer, is exactly that case. Delivery of a notice that WAS queued is AT-LEAST-ONCE and can still fail permanently while the payment stands. So the institution must dedup on the end-to-end id and treat GET /v1/indirects//transactions, not the notice, as the record of truth: it is the only place an outcome whose notice was never queued becomes visible. A direct order pushes no notice at all.

End-to-end ids: send endToEndId only when you already hold one (from a key lookup or a QR decode), and then payee.key is mandatory with it. Omit it on a manually typed order and SPI mints one — the response carries the minted value. Idempotency: the optional clientRequestId is the only identifier that exists BEFORE the JD call, so it is what makes a retry safe on every branch, and it is the ONLY protection a manually typed order has (that order’s end-to-end id does not exist yet when the retry arrives). Amounts are integer centavos.

Every refusal below is decided before the hold is taken, so it moves ZERO money; when JDPI rejects the order after the hold exists, the hold is released and nothing is persisted. Refusals: 409 PIX-0029 when this endToEndId or clientRequestId was already used; 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0032 when the account’s period limit is exceeded; 422 PIX-0030 on a non-positive amount; 422 PIX-0037 when endToEndId arrives without payee.key; 422 PIX-0108 when the payer — or, on an indirect order, the indirect’s @pi — resolves in the CRM but is not bound to a ledger account; 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0102 when a payer.ispb is supplied on an indirect order and disagrees with that indirect’s own ISPB; 400 PIX-0061 when accountId is empty or an accountType is outside the PIX domain 0..4. On an indirect order a JD business rejection is passed back with JD’s own status and body instead of a problem+json.

POST /v1/transactions

Create a PIX transaction

cURL

curl --request POST \
  --url https://api.example.com/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "payee": {
    "accountDigit": "7",
    "accountNumber": "123456",
    "accountType": 0,
    "document": "12345678909",
    "ispb": "12345678",
    "branch": "0001",
    "key": "[e-mail]",
    "name": "Jane Doe"
  },
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "key": "[e-mail]",
  "priority": 1
}
'

201

{
  "amount": 10050,
  "id": "d1f9c0a2-...",
  "status": "PENDING",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "flow": 2,
  "jdpiRequestId": "REQ-123",
  "priority": 1
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

accountId · string · required

The CRM account id of the payer.

Example:

"acc-123"

amount · integer<int64> · required

Transaction amount in centavos (an integer, e.g. 10050 = R$ 100,50).

Example:

10050

payee · object · required

The recipient bank data.

Show child attributes

clientRequestId · string

Optional client idempotency token. A retry carrying the same value is rejected instead of moving money twice; it also seeds the Midaz hold key and the JDPI Chave-Idempotencia. Send it on a manually-typed order: that order has no endToEndId until SPI mints it, so this token is the only thing that can dedup a retry. Omit to opt out.

Example:

"req-2025-01-01-abc123"

description · string

Free-text payment description.

Example:

"Invoice 42"

endToEndId · string

SPI end-to-end id. Omit ONLY for a manually-typed payment order: per JDPI §8.4.1 the id does not exist yet and is generated by SPI on this call. If you obtained one from decode-QRCode (§8.3.3) or consultar-chave (§8.2.14) you MUST send it — omitting it makes SPI mint a DIFFERENT id, which will not match the payee's QR/txId conciliation.

Example:

"E1234567890"

indirectId · string<uuid>

Optional registered-indirect identifier (UUID) routing this outbound order through an indirect participant's PIX position. Omit for a direct order. Validated server-side before any money moves; unknown or inactive is rejected.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

key · string

The payer's PIX key, when paying from a key.

Example:

"[e-mail]"

priority · integer<int64>

Numeric eTransactionPriority (1=PRIMARY,2=SECONDARY).

Example:

1

Response

201

application/json

Created

amount · integer<int64> · required

Transaction amount in centavos.

Example:

10050

id · string · required

The created transaction id.

Example:

"d1f9c0a2-..."

status · string · required

eTransactionStatus name.

Example:

"PENDING"

description · string

Payment description.

Example:

"Invoice 42"

endToEndId · string

The SPI end-to-end id.

Example:

"E1234567890"

flow · integer<int64>

Numeric eTransactionFlow (2=CASH_OUT,3=INTRA_PSP).

Example:

2

jdpiRequestId · string

The JDPI request id (external CASH_OUT).

Example:

"REQ-123"

priority · integer<int64>

Numeric eTransactionPriority.

Example:

1