Pix por um parceiro

Envie, receba e devolva Pix por uma interface de parceiro, com uma seção por parceiro.

Envie, receba e devolva Pix quando um parceiro conecta sua instituição ao SPI.

Esta página sugere uma forma de ler os manuais do BACEN para o Pix. A documentação do parceiro e 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.

​

Pix pela JD

---

​

Participantes

• Sua instituição. Chama a API do Pix JD e lê o resultado de cada pagamento.
• Pix JD. Lança cada Pix no Midaz e troca as ordens com a JD.
• Midaz. O ledger que guarda as contas dos seus clientes.
• SPI. O sistema de pagamentos instantâneos do BACEN. Liquida cada Pix.
• JD. O parceiro que troca as mensagens do Pix com o SPI.

​

Antes de começar

• O Pix JD está configurado para sua instituição. Veja Configuração do trilho.
• A conta que envia, recebe ou devolve o Pix existe no Midaz e tem um titular.

​

Enviar um Pix pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Pix JD	API da Lerian	GET /v1/entries/{entryId}/lookup	Opcional. Consulte a chave Pix antes de pagar. Para pagar um QR code, decodifique-o com POST /v1/qrcodes/decode.
2	Pix JD	JD	API da JD		O Pix JD consulta a chave no DICT pela JD.
3	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 1	O Pix JD responde com o recebedor e um ID end-to-end.
4	Sua instituição	Pix JD	API da Lerian	POST /v1/transactions	Envie a conta pagadora em accountId, o amount em centavos e o payee. Envie o cabeçalho X-Idempotency. Depois de uma consulta, envie também o endToEndId e o payee.key dela. Depois de uma decodificação, envie também o qrCodeType, o endToEndId e o payee.key dela, e o txId de um QR code dinâmico.
5	Pix JD	Midaz	Chamada interna		O Pix JD reserva o valor com uma transação pendente. Ela debita a conta pagadora e credita a conta externa.
6	Pix JD	JD	API da JD		O Pix JD envia a ordem de pagamento à JD.
7	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 4	O Pix JD responde 201 com o pagamento em PENDING. Guarde o id dele.
8	JD	SPI	Entre outras partes		A JD envia a ordem de pagamento ao SPI.
9	SPI	JD	Entre outras partes		O SPI liquida ou rejeita o pagamento.
10	Pix JD	JD	API da JD		O Pix JD consulta o status da ordem na JD para saber o resultado final.
11	Pix JD	Midaz	Chamada interna		Para um pagamento liquidado, o Pix JD confirma a transação pendente. Para um pagamento rejeitado, ele cancela a transação pendente e libera o valor.
12	Sua instituição	Pix JD	API da Lerian	GET /v1/transactions/{transactionId}	Consulte o pagamento com o id do passo 7.
13	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 12	O pagamento fica EXECUTED quando o SPI o liquida, e ERROR quando é rejeitado.

​

Receber um Pix pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	SPI	JD	Entre outras partes		Um Pix para uma das suas contas é liquidado no SPI.
2	JD	Pix JD	Webhook		A JD avisa o Pix JD do Pix liquidado.
3	Pix JD	Midaz	Chamada interna		O Pix JD credita a conta recebedora. A transação debita a conta externa.
4	Pix JD	JD	Resposta		O Pix JD confirma à JD que o crédito foi lançado.
5	Sua instituição	Pix JD	API da Lerian	GET /v1/transactions	Encontre o Pix recebido por end_to_end_id ou por account_id.
6	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 5	O Pix recebido está em EXECUTED.

​

Devolver um Pix recebido pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Pix JD	API da Lerian	POST /v1/refunds	Envie o transactionId e o endToEndId do Pix recebido, o accountId, o code da devolução e o amount. Envie o cabeçalho X-Idempotency.
2	Pix JD	Midaz	Chamada interna		O Pix JD reserva o valor com uma transação pendente. Ela debita a conta que recebeu o Pix e credita a conta externa.
3	Pix JD	JD	API da JD		O Pix JD envia a devolução à JD.
4	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 1	O Pix JD responde 201 com a devolução em PENDING. Guarde o id dela.
5	JD	SPI	Entre outras partes		A JD envia a devolução ao SPI.
6	SPI	JD	Entre outras partes		O SPI liquida ou rejeita a devolução.
7	Pix JD	JD	API da JD		O Pix JD consulta o status da devolução na JD para saber o resultado final.
8	Pix JD	Midaz	Chamada interna		Para uma devolução liquidada, o Pix JD confirma a transação pendente. Para uma devolução rejeitada, ele cancela a transação pendente e libera o valor.
9	Sua instituição	Pix JD	API da Lerian	GET /v1/transactions/{transactionId}	Consulte a devolução com o id do passo 4.
10	Pix JD	Sua instituição	API da Lerian	Resposta ao passo 9	A devolução fica EXECUTED quando o SPI a liquida, e ERROR quando é rejeitada.

​

Regras para a JD

​

Enviar um Pix

• O cabeçalho X-Idempotency é obrigatório. Uma chave nova é um pagamento novo.
• Quando o recebedor tem uma conta na sua instituição, o pagamento não vai ao SPI, e o passo 7 pode responder EXECUTED.
• A reserva no Midaz não é a liquidação. O pagamento só é final quando está em EXECUTED ou ERROR.

​

Receber um Pix

• Quando a JD envia o mesmo aviso de novo, o Pix JD não credita o Pix de novo.

​

Devolver um Pix recebido

• O titular do accountId precisa ser o recebedor do Pix.
• O code da devolução é BE08, FR01, MD06 ou SL02.
• Você pode devolver partes de um Pix mais de uma vez. Juntas, as devoluções não podem passar do valor do Pix.
• Uma devolução é uma transação nova, com um id próprio. O Pix recebido continua em EXECUTED.

​

Como saber que terminou na JD

• Enviar um Pix. GET /v1/transactions/{transactionId} mostra EXECUTED ou ERROR.
• Receber um Pix. GET /v1/transactions mostra o Pix recebido em EXECUTED.
• Devolver um Pix recebido. GET /v1/transactions/{transactionId} com o id da devolução mostra EXECUTED ou ERROR.

Onde a entrega de eventos está ligada no seu deploy, o Pix JD também publica o resultado como um evento: transaction.executed, transaction.refunded ou transaction.failed. Veja Eventos do Pix Direct via JD.

​

O que pode dar errado na JD

Situação	O que você vê	O que fazer
A conta pagadora não tem o saldo.	409, código PIX-0076.	Antes de enviar um novo pagamento, leia os pagamentos com GET /v1/transactions. Um pagamento anterior pode reservar o valor. Se nenhum reserva, adicione fundos ou pague um valor menor.
A resposta a um pagamento ou a uma devolução não chega.	Nenhuma resposta, ou um timeout.	Envie a mesma chamada de novo com a mesma chave X-Idempotency. Um 409 com PIX-0029 quer dizer que o Pix JD a registrou. Encontre-a com GET /v1/transactions.
Você envia de novo um pagamento que a JD recusou.	409, código PIX-0133.	Nada se moveu. Envie um pagamento novo com uma chave X-Idempotency nova.
A JD recusa o pagamento depois do passo 5.	A resposta traz a recusa.	Consulte o pagamento. ERROR quer dizer que o Pix JD liberou o valor reservado.
O pagamento continua em PENDING.	O passo 13 responde PENDING.	O resultado não é final. Consulte o pagamento de novo mais tarde. Não envie um pagamento novo para a mesma compra.
O saldo da conta recebedora não aceita créditos.	O Pix recebido está em PENDING, com pendingReason BALANCE_NOT_RECEIVING.	Quando o saldo aceitar créditos, credite o Pix com POST /v1/parked-credits/{transactionId}/credit. Ou devolva-o ao pagador com POST /v1/parked-credits/{transactionId}/return.
O seu Tracer recusa o crédito de um Pix recebido, por uma regra, um limite ou uma revisão.	O Pix recebido está em PENDING, com pendingReason TRACER_DENIED.	Quando o seu Tracer deixar o crédito passar, credite o Pix com POST /v1/parked-credits/{transactionId}/credit. Ou devolva-o ao pagador com POST /v1/parked-credits/{transactionId}/return.
A devolução passa do valor que resta para devolver.	409, código PIX-0075.	Nada se moveu. Devolva um valor menor.

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

​

Pix pelo BTG

---

​

Participantes

• Sua instituição. Chama a API do Pix BTG e recebe os webhooks dele.
• Pix BTG. Lança cada Pix no Midaz e envia os pagamentos ao BTG.
• Midaz. O ledger que guarda as contas dos seus clientes.
• SPI. O sistema de pagamentos instantâneos do BACEN. Liquida cada Pix.
• BTG. O parceiro que troca as mensagens do Pix com o SPI.

​

Antes de começar

• A conta que envia, recebe ou devolve o Pix existe no Midaz, está ativa e tem um titular.
• A Lerian configura seu endpoint para os webhooks de transferências e devoluções do Pix BTG. Veja Webhooks.

​

Enviar um Pix pelo BTG

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Pix BTG	API da Lerian	POST /v1/transfers/cashout/initiate	Envie a conta de origem em X-Account-Id e o initiationType. Adicione a key, o QR code em emv ou os dados da conta em destination.
2	Pix BTG	Midaz	Chamada interna		O Pix BTG lê a conta de origem e o titular dela.
3	Pix BTG	BTG	API do BTG		Para uma chave Pix ou um QR code, o Pix BTG encontra a conta de destino. Quando necessário, ele consulta o BTG.
4	Pix BTG	Sua instituição	API da Lerian	Resposta ao passo 1	O Pix BTG responde 201 com o id da iniciação, o destination e o expiresAt.
5	Sua instituição	Pix BTG	API da Lerian	POST /v1/transfers/cashout/process	Envie o id da iniciação como initiationId e o amount. Envie o mesmo X-Account-Id.
6	Pix BTG	Midaz	Chamada interna		O Pix BTG debita a conta de origem na hora. A transação credita a conta externa. Para um Pix intra-PSP, uma única transação move o dinheiro do pagador para o recebedor, e os passos 7 e 9 a 12 não acontecem.
7	Pix BTG	BTG	API do BTG		O Pix BTG envia o pagamento ao BTG.
8	Pix BTG	Sua instituição	API da Lerian	Resposta ao passo 5	O Pix BTG responde 201 com a transferência em PROCESSING. Quando o BTG não aceita o pagamento na hora, a transferência fica em PENDING. Quando o resultado do débito no Midaz não é conhecido, a transferência fica em CREATED.
9	BTG	SPI	Entre outras partes		O BTG envia a ordem de pagamento ao SPI.
10	SPI	BTG	Entre outras partes		O SPI liquida ou rejeita o pagamento.
11	BTG	Pix BTG	Webhook		O BTG envia o resultado final do pagamento ao Pix BTG.
12	Pix BTG	Midaz	Chamada interna		Só para um pagamento rejeitado: o Pix BTG reverte o débito com uma nova transação reversa.
13	Pix BTG	Sua instituição	Webhook	Webhook transfer.cashout	A transferência fica COMPLETED, ou REJECTED para um pagamento rejeitado.

​

Receber um Pix pelo BTG

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	SPI	BTG	Entre outras partes		Chega um Pix para uma das suas contas.
2	BTG	Pix BTG	Webhook		O BTG pede ao Pix BTG que aceite o Pix.
3	Pix BTG	Midaz	Chamada interna		O Pix BTG encontra a conta de destino e verifica se ela pode receber o valor.
4	Pix BTG	BTG	Resposta		O Pix BTG aceita o Pix ou o recusa.
5	BTG	SPI	Entre outras partes		O BTG envia o aceite ou a recusa ao SPI.
6	SPI	BTG	Entre outras partes		O SPI confirma a liquidação.
7	BTG	Pix BTG	Webhook		O BTG envia a liquidação ao Pix BTG.
8	Pix BTG	Midaz	Chamada interna		O Pix BTG credita a conta de destino com uma transação de entrada.
9	Pix BTG	Sua instituição	Webhook	Webhook transfer.cashin	A transferência recebida fica COMPLETED.

​

Devolver um Pix recebido pelo BTG

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Pix BTG	API da Lerian	POST /v1/transfers/{transfer_id}/refunds	Envie o id da transferência recebida no caminho e o amount. Envie a conta em X-Account-Id e o código da devolução em X-Reason. Envie o cabeçalho X-Idempotency.
2	Pix BTG	Midaz	Chamada interna		O Pix BTG debita a conta na hora. A transação credita a conta externa. Para uma devolução intra-PSP, uma única transação move o dinheiro para o pagador original, e os passos 3 e 5 a 8 não acontecem.
3	Pix BTG	BTG	API do BTG		O Pix BTG envia a devolução ao BTG.
4	Pix BTG	Sua instituição	API da Lerian	Resposta ao passo 1	O Pix BTG responde 201 com a devolução em PROCESSING. Quando a resposta do BTG não é conhecida, a devolução fica em PENDING. Quando o resultado do débito no Midaz não é conhecido, a devolução fica em CREATED.
5	BTG	SPI	Entre outras partes		O BTG envia a devolução ao SPI.
6	SPI	BTG	Entre outras partes		O SPI liquida ou rejeita a devolução.
7	BTG	Pix BTG	Webhook		O BTG envia o resultado final da devolução ao Pix BTG.
8	Pix BTG	Midaz	Chamada interna		Só para uma devolução rejeitada: o Pix BTG reverte o débito com uma nova transação reversa.
9	Pix BTG	Sua instituição	Webhook	Webhook refund.cashout	A devolução fica COMPLETED, ou REJECTED para uma devolução rejeitada.

​

Regras para o BTG

​

Enviar um Pix

• Envie o cabeçalho X-Idempotency nos passos 1 e 5.
• A iniciação fica aberta por 5 minutos. Depois disso, o passo 5 responde 422 com PIX-0411.
• Quando você processa a mesma iniciação de novo, o Pix BTG devolve a transferência que ele criou. Ele não move dinheiro de novo.
• O débito no Midaz não é a liquidação.
• Quando o recebedor devolve um Pix que você enviou, o Pix BTG credita o valor no Midaz. Depois ele envia o webhook refund.cashin.

​

Receber um Pix

• O Pix BTG recusa um Pix quando não encontra a conta, ou quando a conta não pode receber o valor. O Midaz não registra nada para um Pix recusado.

​

Devolver um Pix recebido

• Você só pode devolver um Pix recebido. Juntas, as devoluções não podem passar do valor do Pix.
• O código da devolução em X-Reason é BE08, FR01, MD06 ou SL02.
• O débito do passo 2 não é a liquidação.

​

Como saber que terminou no BTG

• Enviar um Pix. O webhook transfer.cashout informa o status final. GET /v1/transfers/{transfer_id} mostra o mesmo status.
• Receber um Pix. O Pix BTG envia o webhook transfer.cashin com COMPLETED.
• Devolver um Pix recebido. O webhook refund.cashout informa o status final. GET /v1/refunds/{refund_id} mostra o mesmo status.

​

O que pode dar errado no BTG

Situação	O que você vê	O que fazer
A iniciação tem mais de 5 minutos.	422, código PIX-0411.	Nada se moveu. Comece uma iniciação nova.
A resposta ao passo 1 ou ao passo 5 não chega.	Nenhuma resposta, ou um timeout.	Envie a mesma chamada de novo com a mesma chave X-Idempotency.
A resposta a uma devolução não chega.	Nenhuma resposta, ou um timeout.	Consulte as devoluções do Pix com GET /v1/refunds filtradas por end_to_end. Envie a devolução de novo só quando ela não estiver na lista.
O webhook do passo 13 não chega.	A transferência continua em PENDING ou PROCESSING.	Consulte a transferência. Para pedir o status ao BTG, use POST /v1/transfers/{transfer_id}/unblock. Não envie um pagamento novo para a mesma compra.
A transferência ou a devolução continua em CREATED.	O status é CREATED.	Para um Pix inter-PSP, o desbloqueio a recusa com 422. Abra um chamado de suporte com a Lerian e informe o id da transferência ou da devolução.
O webhook do passo 9 de uma devolução não chega.	A devolução continua em PENDING ou PROCESSING.	Consulte a devolução. Para pedir o status ao BTG, use POST /v1/refunds/{refund_id}/unblock.
Seu endpoint não aceitou um webhook.	O webhook está em FAILED ou DEAD_LETTER em GET /v1/webhooks/outbound.	Envie-o de novo com POST /v1/webhooks/outbound/{id}/retry.

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

​

Relacionados

---

• Enviar e receber Pix: as mesmas jornadas no Lerian SPI nativo.
• Devolver um Pix recebido: a devolução no Lerian SPI nativo.
• Pix via JD
• Transferências e cash-out
• Operações de devolução
• Webhooks