Send and receive Pix

Send a Pix from a Midaz account through SPI, and receive a Pix into one, with Pix Lerian and Lerian SPI.

Send a Pix from a Midaz account, and receive a Pix into a Midaz account.

This flow is a suggested reading of the BACEN manuals for Pix. 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.

​

Participants

---

• Your institution. The Pix participant. It calls the Pix Lerian API and receives its events.
• Pix Lerian. Connects Midaz to Lerian SPI. It posts the Pix in Midaz and hands the payment to Lerian SPI.
• Midaz. The ledger that holds the accounts of your customers.
• Lerian SPI. Exchanges the Pix messages with SPI.
• SPI. The BACEN instant payment system. It settles each Pix.

​

Before you start

---

• The account that sends or receives the Pix exists in Midaz, is active, and has a holder.
• Your systems receive the Pix Lerian events. See Pix Lerian events.
• The Pix ledger in Midaz has overrides.allowFeeSkip on. A received Pix never pays a fee.

​

Diagram

---

​

Send a Pix

#	From	To	Message	Lerian API	What happens
1	Your institution	Pix Lerian	Lerian API	POST /transfers/cashout/initiate	Start the transfer from the source account to a Pix key, a static QR code, or the account details of the destination. Send the X-Idempotency header.
2	Pix Lerian	Midaz	Internal call		Pix Lerian reads the source account.
3	Pix Lerian	Pix Lerian	Internal step		For a Pix key or a static QR code, Pix Lerian finds the account of the key.
4	Pix Lerian	Your institution	Lerian API	Response to step 1	Pix Lerian answers with the initiation in PENDING and the destination data.
5	Your institution	Pix Lerian	Lerian API	POST /transfers/cashout/process	Confirm the transfer with the amount. Send the X-Idempotency header.
6	Pix Lerian	Midaz	Internal call		Pix Lerian debits the source account. The transaction credits @external/BRL, or the settlement account of the SPI setting settlement_account_alias, and carries the end-to-end ID as its code.
7	Pix Lerian	Lerian SPI	Internal call		Pix Lerian sends the payment.
8	Lerian SPI	SPI	pacs.008		Lerian SPI sends the payment order to SPI.
9	Pix Lerian	Your institution	Lerian API	Response to step 5	Pix Lerian answers 201 with the transfer in PROCESSING.
10	SPI	Lerian SPI	pacs.002		SPI reports the settlement or the rejection of the payment.
11	Lerian SPI	Pix Lerian	Internal call		Lerian SPI passes the result to Pix Lerian.
12	Pix Lerian	Midaz	Internal call		Only for a rejected payment: Pix Lerian reverts the debit with a new reverse transaction.
13	Pix Lerian	Your institution	Lerian API	Event outbound_transfer.completed	The transfer is COMPLETED. For a rejected payment, the event is outbound_transfer.rejected, and the transfer is REJECTED.

​

Receive a Pix

#	From	To	Message	Lerian API	What happens
1	SPI	Lerian SPI	pacs.008		A Pix to one of your accounts arrives.
2	Lerian SPI	Pix Lerian	Internal call		Lerian SPI passes the arriving Pix to Pix Lerian.
3	Pix Lerian	Midaz	Internal call		Pix Lerian checks the destination account and its holder.
4	Pix Lerian	Lerian SPI	Internal call		Pix Lerian accepts the Pix, or refuses it.
5	Lerian SPI	SPI	pacs.002		Lerian SPI sends the acceptance or the refusal to SPI.
6	SPI	Lerian SPI	pacs.002		SPI confirms the settlement.
7	Lerian SPI	Pix Lerian	Internal call		Lerian SPI passes the settlement to Pix Lerian.
8	Pix Lerian	Midaz	Internal call		Pix Lerian credits the destination account. The transaction debits @external/BRL, or the settlement account, and carries the end-to-end ID as its code. When Midaz does not confirm the credit, Pix Lerian parks it.
9	Pix Lerian	Your institution	Lerian API	Event inbound_transfer.completed	The received transfer is COMPLETED. List the received transfers with GET /transfers and direction=in.

​

Rules

---

​

Send a Pix

• The initiation stays open for 5 minutes. After that, step 5 answers 422 with PIX-0321.
• A static QR code with an amount sets the amount of the transfer. At step 5, leave out the amount, or send the same amount.
• The debit in Midaz is not the settlement. The transfer is final only at the event of step 13.

​

Receive a Pix

• Pix Lerian refuses a Pix to an account that it does not find or that is not active. It also refuses a Pix when the holder does not match. Midaz records nothing for a refused Pix.
• Pix Lerian credits the account only after SPI confirms the settlement.
• A credit that Midaz does not confirm is parked, not dropped. Pix Lerian publishes inbound_transfer.credit_parked, and your back office credits the Pix with POST /transfers/{id}/credit.
• When Pix Lerian does not answer within the SPI time limit, Lerian SPI refuses the Pix.

​

How you know it finished

---

• Send a Pix. Pix Lerian publishes outbound_transfer.completed or outbound_transfer.rejected. GET /transfers/{id} shows the same status.
• Receive a Pix. Pix Lerian publishes inbound_transfer.completed. For a parked credit, it publishes inbound_transfer.credit_parked first, and inbound_transfer.completed after the credit call completes.

​

What can go wrong

---

Situation	What you see	What to do
The initiation is older than 5 minutes.	422, code PIX-0321.	Nothing moved. Start a new initiation.
The source account does not have the balance.	422, code PIX-0323.	Nothing moved. Start a new initiation. Add funds first, or send a smaller amount at step 5.
The payment did not leave after the debit.	502, code PIX-0325.	Read the transfer before you send a new payment.
The settlement account cannot take the immediate cash-out.	422, code PIX-0332.	Nothing was debited. Fund the settlement account, then start a new initiation.
A received Pix stays parked.	Event inbound_transfer.credit_parked.	Credit it with the credit call; for ACCOUNT_BLOCKED or LEDGER_REFUSED, fix the cause first. PIX-0474 means the ledger cannot confirm the credit: reconcile it by hand.
The answer to a call does not arrive.	No answer, or a timeout.	Send the same call again with the same X-Idempotency key.
The event of step 13 does not arrive.	The transfer stays PROCESSING.	The result is not known yet. Read the transfer. Do not send a new payment for the same purchase.

The Pix Lerian error list describes each code.

​

Related

---

• Return a received Pix
• Charge with a dynamic QR code
• Use SPI with Pix Lerian
• How Lerian SPI works