Pix through a partner

Send, receive and return Pix through a partner interface, with one section per partner.

Send, receive and return Pix when a partner connects your institution to SPI.

This page suggests one way to read the BACEN manuals for Pix. The partner’s documentation and the manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See how to read the diagrams.

​

Pix through JD

---

​

Participants

• Your institution. Calls the Pix JD API and reads the result of each payment.
• Pix JD. Posts each Pix in Midaz and exchanges the orders with JD.
• Midaz. The ledger that holds the accounts of your customers.
• SPI. The BACEN instant payment system. It settles each Pix.
• JD. The partner that exchanges the Pix messages with SPI.

​

Before you start

• Pix JD is set up for your institution. See Setting up the rail.
• The account that sends, receives or returns the Pix exists in Midaz and has a holder.

​

Send a Pix through JD

#	From	To	Message	Lerian API	What happens
1	Your institution	Pix JD	Lerian API	GET /v1/entries/{entryId}/lookup	Optional. Look up the Pix key before you pay it. To pay a QR code, decode it with POST /v1/qrcodes/decode instead.
2	Pix JD	JD	JD API		Pix JD reads the key in DICT through JD.
3	Pix JD	Your institution	Lerian API	Response to step 1	Pix JD answers with the payee and an end-to-end ID.
4	Your institution	Pix JD	Lerian API	POST /v1/transactions	Send the paying account in accountId, the amount in centavos and the payee. Send the X-Idempotency header. After a lookup, also send its endToEndId and payee.key. After a decode, also send its qrCodeType, endToEndId and payee.key, and the txId of a dynamic QR code.
5	Pix JD	Midaz	Internal call		Pix JD reserves the amount with a pending transaction. It debits the paying account and credits the external account.
6	Pix JD	JD	JD API		Pix JD sends the payment order to JD.
7	Pix JD	Your institution	Lerian API	Response to step 4	Pix JD answers 201 with the payment in PENDING. Keep its id.
8	JD	SPI	Between other parties		JD sends the payment order to SPI.
9	SPI	JD	Between other parties		SPI settles or rejects the payment.
10	Pix JD	JD	JD API		Pix JD reads the status of the order from JD to learn the final result.
11	Pix JD	Midaz	Internal call		For a settled payment, Pix JD commits the pending transaction. For a rejected payment, it cancels the pending transaction and releases the amount.
12	Your institution	Pix JD	Lerian API	GET /v1/transactions/{transactionId}	Read the payment with the id from step 7.
13	Pix JD	Your institution	Lerian API	Response to step 12	The payment is EXECUTED when SPI settled it, and ERROR when it was rejected.

​

Receive a Pix through JD

#	From	To	Message	Lerian API	What happens
1	SPI	JD	Between other parties		A Pix to one of your accounts settles at SPI.
2	JD	Pix JD	Webhook		JD notifies Pix JD of the settled Pix.
3	Pix JD	Midaz	Internal call		Pix JD credits the receiving account. The transaction debits the external account.
4	Pix JD	JD	Response		Pix JD confirms to JD that the credit is booked.
5	Your institution	Pix JD	Lerian API	GET /v1/transactions	Find the received Pix by end_to_end_id or by account_id.
6	Pix JD	Your institution	Lerian API	Response to step 5	The received Pix is EXECUTED.

​

Return a received Pix through JD

#	From	To	Message	Lerian API	What happens
1	Your institution	Pix JD	Lerian API	POST /v1/refunds	Send the transactionId and the endToEndId of the received Pix, the accountId, the return code and the amount. Send the X-Idempotency header.
2	Pix JD	Midaz	Internal call		Pix JD reserves the amount with a pending transaction. It debits the account that received the Pix and credits the external account.
3	Pix JD	JD	JD API		Pix JD sends the return to JD.
4	Pix JD	Your institution	Lerian API	Response to step 1	Pix JD answers 201 with the return in PENDING. Keep its id.
5	JD	SPI	Between other parties		JD sends the return to SPI.
6	SPI	JD	Between other parties		SPI settles or rejects the return.
7	Pix JD	JD	JD API		Pix JD reads the status of the return from JD to learn the final result.
8	Pix JD	Midaz	Internal call		For a settled return, Pix JD commits the pending transaction. For a rejected return, it cancels the pending transaction and releases the amount.
9	Your institution	Pix JD	Lerian API	GET /v1/transactions/{transactionId}	Read the return with the id from step 4.
10	Pix JD	Your institution	Lerian API	Response to step 9	The return is EXECUTED when SPI settled it, and ERROR when it was rejected.

​

Rules for JD

​

Send a Pix

• The X-Idempotency header is required. A new key is a new payment.
• When the payee has an account at your institution, the payment does not go to SPI, and step 7 can answer EXECUTED.
• The reservation in Midaz is not the settlement. The payment is final only when it is EXECUTED or ERROR.

​

Receive a Pix

• When JD sends the same notice again, Pix JD does not credit the Pix again.

​

Return a received Pix

• The holder of accountId must be the payee of the Pix.
• The return code is BE08, FR01, MD06 or SL02.
• You can return parts of a Pix more than once. Together, the returns cannot pass the amount of the Pix.
• A return is a new transaction with its own id. The received Pix stays EXECUTED.

​

How you know it finished with JD

• Send a Pix. GET /v1/transactions/{transactionId} shows EXECUTED or ERROR.
• Receive a Pix. GET /v1/transactions shows the received Pix in EXECUTED.
• Return a received Pix. GET /v1/transactions/{transactionId} with the id of the return shows EXECUTED or ERROR.

Where event delivery is on for your deployment, Pix JD also publishes the result as an event: transaction.executed, transaction.refunded or transaction.failed. See Pix Direct via JD events.

​

What can go wrong with JD

Situation	What you see	What to do
The paying account does not have the balance.	409, code PIX-0076.	Before you send a new payment, read the payments with GET /v1/transactions. An earlier payment can hold the amount. If none does, add funds or pay a smaller amount.
The answer to a payment or a return does not arrive.	No answer, or a timeout.	Send the same call again with the same X-Idempotency key. A 409 with PIX-0029 means that Pix JD recorded it. Find it with GET /v1/transactions.
You send again a payment that JD refused.	409, code PIX-0133.	Nothing moved. Send a new payment with a new X-Idempotency key.
JD refuses the payment after step 5.	The answer carries the refusal.	Read the payment. ERROR means that Pix JD released the reserved amount.
The payment stays PENDING.	Step 13 answers PENDING.	The result is not final. Read the payment again later. Do not send a new payment for the same purchase.
The balance of the receiving account does not accept credits.	The received Pix is PENDING, with pendingReason BALANCE_NOT_RECEIVING.	When the balance accepts credits, credit the Pix with POST /v1/parked-credits/{transactionId}/credit. Or return it to the payer with POST /v1/parked-credits/{transactionId}/return.
Your Tracer refuses the credit of a received Pix, by a rule, a limit or a review.	The received Pix is PENDING, with pendingReason TRACER_DENIED.	When your Tracer lets the credit through, credit the Pix with POST /v1/parked-credits/{transactionId}/credit. Or return it to the payer with POST /v1/parked-credits/{transactionId}/return.
The return is more than the amount left to return.	409, code PIX-0075.	Nothing moved. Return a smaller amount.

The Pix JD error list describes each code.

​

Pix through BTG

---

​

Participants

• Your institution. Calls the Pix BTG API and receives its webhooks.
• Pix BTG. Posts each Pix in Midaz and sends the payments to BTG.
• Midaz. The ledger that holds the accounts of your customers.
• SPI. The BACEN instant payment system. It settles each Pix.
• BTG. The partner that exchanges the Pix messages with SPI.

​

Before you start

• The account that sends, receives or returns the Pix exists in Midaz, is active, and has a holder.
• Lerian sets your endpoint for the transfer and refund webhooks of Pix BTG. See Webhooks.

​

Send a Pix through BTG

#	From	To	Message	Lerian API	What happens
1	Your institution	Pix BTG	Lerian API	POST /v1/transfers/cashout/initiate	Send the source account in X-Account-Id and the initiationType. Add the key, the QR code in emv, or the account details in destination.
2	Pix BTG	Midaz	Internal call		Pix BTG reads the source account and its holder.
3	Pix BTG	BTG	BTG API		For a Pix key or a QR code, Pix BTG finds the destination account. It asks BTG when necessary.
4	Pix BTG	Your institution	Lerian API	Response to step 1	Pix BTG answers 201 with the initiation id, the destination and expiresAt.
5	Your institution	Pix BTG	Lerian API	POST /v1/transfers/cashout/process	Send the initiation id as initiationId and the amount. Send the same X-Account-Id.
6	Pix BTG	Midaz	Internal call		Pix BTG debits the source account at once. The transaction credits the external account. For an intra-PSP Pix, one transaction moves the money from the payer to the payee, and steps 7 and 9 to 12 do not happen.
7	Pix BTG	BTG	BTG API		Pix BTG sends the payment to BTG.
8	Pix BTG	Your institution	Lerian API	Response to step 5	Pix BTG answers 201 with the transfer in PROCESSING. When BTG does not take the payment at once, the transfer is PENDING. When the outcome of the debit in Midaz is unknown, the transfer is CREATED.
9	BTG	SPI	Between other parties		BTG sends the payment order to SPI.
10	SPI	BTG	Between other parties		SPI settles or rejects the payment.
11	BTG	Pix BTG	Webhook		BTG sends the final result of the payment to Pix BTG.
12	Pix BTG	Midaz	Internal call		Only for a rejected payment: Pix BTG reverts the debit with a new reverse transaction.
13	Pix BTG	Your institution	Webhook	Webhook transfer.cashout	The transfer is COMPLETED, or REJECTED for a rejected payment.

​

Receive a Pix through BTG

#	From	To	Message	Lerian API	What happens
1	SPI	BTG	Between other parties		A Pix to one of your accounts arrives.
2	BTG	Pix BTG	Webhook		BTG asks Pix BTG to accept the Pix.
3	Pix BTG	Midaz	Internal call		Pix BTG finds the destination account and checks that it can receive the amount.
4	Pix BTG	BTG	Response		Pix BTG accepts the Pix, or refuses it.
5	BTG	SPI	Between other parties		BTG sends the acceptance or the refusal to SPI.
6	SPI	BTG	Between other parties		SPI confirms the settlement.
7	BTG	Pix BTG	Webhook		BTG sends the settlement to Pix BTG.
8	Pix BTG	Midaz	Internal call		Pix BTG credits the destination account with an inflow transaction.
9	Pix BTG	Your institution	Webhook	Webhook transfer.cashin	The received transfer is COMPLETED.

​

Return a received Pix through BTG

#	From	To	Message	Lerian API	What happens
1	Your institution	Pix BTG	Lerian API	POST /v1/transfers/{transfer_id}/refunds	Send the id of the received transfer in the path and the amount. Send the account in X-Account-Id and the return code in X-Reason. Send the X-Idempotency header.
2	Pix BTG	Midaz	Internal call		Pix BTG debits the account at once. The transaction credits the external account. For an intra-PSP return, one transaction moves the money to the original payer, and steps 3 and 5 to 8 do not happen.
3	Pix BTG	BTG	BTG API		Pix BTG sends the return to BTG.
4	Pix BTG	Your institution	Lerian API	Response to step 1	Pix BTG answers 201 with the return in PROCESSING. When the answer of BTG is not known, the return is PENDING. When the outcome of the debit in Midaz is unknown, the return is CREATED.
5	BTG	SPI	Between other parties		BTG sends the return to SPI.
6	SPI	BTG	Between other parties		SPI settles or rejects the return.
7	BTG	Pix BTG	Webhook		BTG sends the final result of the return to Pix BTG.
8	Pix BTG	Midaz	Internal call		Only for a rejected return: Pix BTG reverts the debit with a new reverse transaction.
9	Pix BTG	Your institution	Webhook	Webhook refund.cashout	The return is COMPLETED, or REJECTED for a rejected return.

​

Rules for BTG

​

Send a Pix

• Send the X-Idempotency header at steps 1 and 5.
• The initiation stays open for 5 minutes. After that, step 5 answers 422 with PIX-0411.
• When you process the same initiation again, Pix BTG returns the transfer that it created. It moves no money again.
• The debit in Midaz is not the settlement.
• When the receiver returns a Pix that you sent, Pix BTG credits the amount in Midaz. Then it sends the webhook refund.cashin.

​

Receive a Pix

• Pix BTG refuses a Pix when it does not find the account, or when the account cannot receive the amount. Midaz records nothing for a refused Pix.

​

Return a received Pix

• You can return only a received Pix. Together, the returns cannot pass the amount of the Pix.
• The return code in X-Reason is BE08, FR01, MD06 or SL02.
• The debit of step 2 is not the settlement.

​

How you know it finished with BTG

• Send a Pix. The webhook transfer.cashout gives the final status. GET /v1/transfers/{transfer_id} shows the same status.
• Receive a Pix. Pix BTG sends the webhook transfer.cashin with COMPLETED.
• Return a received Pix. The webhook refund.cashout gives the final status. GET /v1/refunds/{refund_id} shows the same status.

​

What can go wrong with BTG

Situation	What you see	What to do
The initiation is older than 5 minutes.	422, code PIX-0411.	Nothing moved. Start a new initiation.
The answer to step 1 or step 5 does not arrive.	No answer, or a timeout.	Send the same call again with the same X-Idempotency key.
The answer to a return does not arrive.	No answer, or a timeout.	Read the returns of the Pix with GET /v1/refunds filtered by end_to_end. Send the return again only when it is not there.
The webhook of step 13 does not arrive.	The transfer stays PENDING or PROCESSING.	Read the transfer. To ask BTG for its status, use POST /v1/transfers/{transfer_id}/unblock. Do not send a new payment for the same purchase.
The transfer or the return stays CREATED.	The status is CREATED.	For an inter-PSP Pix, unblock refuses it with 422. Open a support request with Lerian and give the transfer or return id.
The webhook of step 9 of a return does not arrive.	The return stays PENDING or PROCESSING.	Read the return. To ask BTG for its status, use POST /v1/refunds/{refund_id}/unblock.
Your endpoint did not accept a webhook.	The webhook is FAILED or DEAD_LETTER in GET /v1/webhooks/outbound.	Send it again with POST /v1/webhooks/outbound/{id}/retry.

The Pix BTG error list describes each code.

​

Related

---

• Send and receive Pix: the same journeys on the native Lerian SPI.
• Return a received Pix: the return on the native Lerian SPI.
• Pix via JD
• Transfers and cash-out
• Refund operations
• Webhooks