Enviar e receber Pix

Envie um Pix de uma conta do Midaz pelo SPI e receba um Pix em uma conta, com o Pix Lerian e o Lerian SPI.

Envie um Pix de uma conta do Midaz e receba um Pix em uma conta do Midaz.

Este fluxo é uma leitura sugerida dos manuais do BACEN para o Pix. Os manuais prevalecem sobre esta página. Sua instituição, como participante, valida o fluxo e o implementa sobre as APIs da Lerian. Veja como ler os diagramas.

​

Participantes

---

• Sua instituição. O participante do Pix. Chama a API do Pix Lerian e recebe os eventos dele.
• Pix Lerian. Conecta o Midaz ao Lerian SPI. Lança o Pix no Midaz e entrega o pagamento ao Lerian SPI.
• Midaz. O ledger que guarda as contas dos seus clientes.
• Lerian SPI. Troca as mensagens do Pix com o SPI.
• SPI. O sistema de pagamentos instantâneos do BACEN. Liquida cada Pix.

​

Antes de começar

---

• A conta que envia ou recebe o Pix existe no Midaz, está ativa e tem um titular.
• Seus sistemas recebem os eventos do Pix Lerian. Veja Eventos do Pix Lerian.
• O ledger do Pix no Midaz tem overrides.allowFeeSkip ligado. Um Pix recebido nunca paga tarifa.

​

Diagrama

---

​

Enviar um Pix

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Pix Lerian	API da Lerian	POST /transfers/cashout/initiate	Inicie a transferência da conta de origem para uma chave Pix, um QR code estático ou os dados da conta de destino. Envie o cabeçalho X-Idempotency.
2	Pix Lerian	Midaz	Chamada interna		O Pix Lerian lê a conta de origem.
3	Pix Lerian	Pix Lerian	Passo interno		Para uma chave Pix ou um QR code estático, o Pix Lerian encontra a conta da chave.
4	Pix Lerian	Sua instituição	API da Lerian	Resposta ao passo 1	O Pix Lerian responde com a iniciação em PENDING e os dados do destino.
5	Sua instituição	Pix Lerian	API da Lerian	POST /transfers/cashout/process	Confirme a transferência com o valor. Envie o cabeçalho X-Idempotency.
6	Pix Lerian	Midaz	Chamada interna		O Pix Lerian debita a conta de origem. A transação credita @external/BRL, ou a conta de liquidação da configuração settlement_account_alias do SPI, e leva o ID end-to-end como código.
7	Pix Lerian	Lerian SPI	Chamada interna		O Pix Lerian envia o pagamento.
8	Lerian SPI	SPI	pacs.008		O Lerian SPI envia a ordem de pagamento ao SPI.
9	Pix Lerian	Sua instituição	API da Lerian	Resposta ao passo 5	O Pix Lerian responde 201 com a transferência em PROCESSING.
10	SPI	Lerian SPI	pacs.002		O SPI informa a liquidação ou a rejeição do pagamento.
11	Lerian SPI	Pix Lerian	Chamada interna		O Lerian SPI repassa o resultado ao Pix Lerian.
12	Pix Lerian	Midaz	Chamada interna		Só para um pagamento rejeitado: o Pix Lerian reverte o débito com uma nova transação reversa.
13	Pix Lerian	Sua instituição	API da Lerian	Evento outbound_transfer.completed	A transferência fica COMPLETED. Para um pagamento rejeitado, o evento é outbound_transfer.rejected, e a transferência fica REJECTED.

​

Receber um Pix

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	SPI	Lerian SPI	pacs.008		Chega um Pix para uma das suas contas.
2	Lerian SPI	Pix Lerian	Chamada interna		O Lerian SPI repassa o Pix que chegou ao Pix Lerian.
3	Pix Lerian	Midaz	Chamada interna		O Pix Lerian verifica a conta de destino e o titular dela.
4	Pix Lerian	Lerian SPI	Chamada interna		O Pix Lerian aceita o Pix ou o recusa.
5	Lerian SPI	SPI	pacs.002		O Lerian SPI envia o aceite ou a recusa ao SPI.
6	SPI	Lerian SPI	pacs.002		O SPI confirma a liquidação.
7	Lerian SPI	Pix Lerian	Chamada interna		O Lerian SPI repassa a liquidação ao Pix Lerian.
8	Pix Lerian	Midaz	Chamada interna		O Pix Lerian credita a conta de destino. A transação debita @external/BRL, ou a conta de liquidação, e leva o ID end-to-end como código. Quando o Midaz não confirma o crédito, o Pix Lerian o estaciona.
9	Pix Lerian	Sua instituição	API da Lerian	Evento inbound_transfer.completed	A transferência recebida fica COMPLETED. Liste as transferências recebidas com GET /transfers e direction=in.

​

Regras

---

​

Enviar um Pix

• A iniciação fica aberta por 5 minutos. Depois disso, o passo 5 responde 422 com PIX-0321.
• Um QR code estático com valor define o valor da transferência. No passo 5, omita o valor ou envie o mesmo valor.
• O débito no Midaz não é a liquidação. A transferência só é final no evento do passo 13.

​

Receber um Pix

• O Pix Lerian recusa um Pix para uma conta que ele não encontra ou que não está ativa. Também recusa um Pix quando o titular não confere. O Midaz não registra nada para um Pix recusado.
• O Pix Lerian credita a conta só depois que o SPI confirma a liquidação.
• Um crédito que o Midaz não confirma é estacionado, não descartado. O Pix Lerian publica inbound_transfer.credit_parked, e o back office da sua instituição credita o Pix com POST /transfers/{id}/credit.
• Quando o Pix Lerian não responde dentro do prazo do SPI, o Lerian SPI recusa o Pix.

​

Como saber que terminou

---

• Enviar um Pix. O Pix Lerian publica outbound_transfer.completed ou outbound_transfer.rejected. GET /transfers/{id} mostra o mesmo status.
• Receber um Pix. O Pix Lerian publica inbound_transfer.completed. Para um crédito estacionado, ele publica antes inbound_transfer.credit_parked, e inbound_transfer.completed depois que a chamada de crédito termina.

​

O que pode dar errado

---

Situação	O que você vê	O que fazer
A iniciação tem mais de 5 minutos.	422, código PIX-0321.	Nada se moveu. Inicie uma nova iniciação.
A conta de origem não tem saldo.	422, código PIX-0323.	Nada se moveu. Inicie uma nova iniciação. Adicione fundos antes, ou envie um valor menor no passo 5.
O pagamento não saiu depois do débito.	502, código PIX-0325.	Leia a transferência antes de enviar um novo pagamento.
A conta de liquidação não pode receber o cash-out imediato.	422, código PIX-0332.	Nada foi debitado. Financie a conta de liquidação e inicie uma nova iniciação.
Um Pix recebido continua estacionado.	Evento inbound_transfer.credit_parked.	Credite-o com a chamada de crédito; para ACCOUNT_BLOCKED ou LEDGER_REFUSED, corrija a causa primeiro. PIX-0474 significa que o ledger não consegue confirmar o crédito: concilie à mão.
A resposta a uma chamada não chega.	Nenhuma resposta, ou um timeout.	Envie a mesma chamada de novo com a mesma chave X-Idempotency.
O evento do passo 13 não chega.	A transferência continua PROCESSING.	O resultado ainda não é conhecido. Leia a transferência. Não envie um novo pagamento para a mesma compra.

A lista de erros do Pix Lerian descreve cada código.

​

Relacionados

---

• Devolver um Pix recebido
• Cobrar com um QR code dinâmico
• Usar o SPI com o Pix Lerian
• Como o Lerian SPI funciona