Boletos e contas por um parceiro

Pague boletos, contas de consumo e DARF por uma interface de parceiro e saiba quando cada pagamento foi liquidado.

Pague boletos, contas de consumo e DARF de uma conta do Midaz quando o BTG os paga pela sua instituição.

A documentação do parceiro prevalece sobre esta página. Sua instituição valida o fluxo e o implementa sobre as APIs da Lerian. Veja como ler os diagramas.

​

Participantes

---

• Sua instituição. Chama a API do Payments BTG e recebe os webhooks dele.
• Payments BTG. Reserva o valor no Midaz e paga a cobrança no BTG.
• Midaz. O ledger que guarda as contas dos seus clientes.
• BTG. O parceiro que paga a cobrança.

​

Antes de começar

---

• A conta pagadora existe no Midaz e tem um titular.
• O Payments BTG está conectado ao BTG para sua instituição.
• Configure seu webhook com POST /v1/admin/webhooks. Envie uma callbackUrl HTTPS, um secret de pelo menos 32 caracteres e os eventos que você quer em enabledEvents. Envie um Idempotency-Key.

​

Diagrama

---

​

Pagar um boleto ou uma conta de consumo

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Payments BTG	API da Lerian	POST /v1/payments/consult	Opcional. Consulte a cobrança pela digitableLine antes de pagá-la.
2	Payments BTG	BTG	API do BTG		O Payments BTG consulta a cobrança no BTG.
3	Payments BTG	Sua instituição	API da Lerian	Resposta ao passo 1	O Payments BTG responde com os dados da cobrança.
4	Sua instituição	Payments BTG	API da Lerian	POST /v1/payments	Envie a digitableLine, a conta pagadora em midazAccountId e o ledgerId dela. Envie o cabeçalho X-Organization-Id e um novo Idempotency-Key.
5	Payments BTG	Midaz	Chamada interna		O Payments BTG verifica se a conta pertence à organização e ao ledger. Ele lê o titular da conta como pagador.
6	Payments BTG	BTG	API do BTG		O Payments BTG consulta a cobrança e o valor dela no BTG.
7	Payments BTG	Midaz	Chamada interna		O Payments BTG reserva o valor com uma transação pendente. Ela debita a conta pagadora e credita a conta externa.
8	Payments BTG	BTG	API do BTG		O Payments BTG paga a cobrança no BTG.
9	Payments BTG	Sua instituição	API da Lerian	Resposta ao passo 4	O Payments BTG responde 201 com o id do pagamento e o status dele. Quando a resposta do BTG não é conhecida, ele responde 202 com o pagamento em UNCONFIRMED.

​

Pagar um DARF

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Payments BTG	API da Lerian	POST /v1/payments/darf	Envie o treasuryRevenueCode, a referenceDate, o type, o mainAmount, o interestAmount e o fineAmount. Envie a conta pagadora em midazAccountId e o ledgerId dela. Envie o cabeçalho X-Organization-Id e um novo Idempotency-Key.
2	Payments BTG	Midaz	Chamada interna		O Payments BTG verifica a conta e lê o titular dela como pagador.
3	Payments BTG	Payments BTG	Passo interno		O Payments BTG soma o valor principal, os juros e a multa. A soma é o valor a pagar.
4	Payments BTG	Midaz	Chamada interna		O Payments BTG reserva o valor com uma transação pendente. Ela debita a conta pagadora e credita a conta externa.
5	Payments BTG	BTG	API do BTG		O Payments BTG paga o DARF no BTG.
6	Payments BTG	Sua instituição	API da Lerian	Resposta ao passo 1	O Payments BTG responde 201 com o id do pagamento e o status dele. Quando a resposta do BTG não é conhecida, ele responde 202 com o pagamento em UNCONFIRMED.

​

Saber quando um pagamento foi liquidado

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	BTG	Payments BTG	Webhook		O BTG envia ao Payments BTG o resultado do pagamento.
2	Payments BTG	Midaz	Chamada interna		Para um pagamento liquidado, o Payments BTG confirma a transação pendente. Para um pagamento rejeitado, cancelado ou com falha, ele cancela a transação pendente e libera o valor.
3	Payments BTG	Sua instituição	Webhook	Webhook PAYMENT_SETTLED	O Payments BTG envia PAYMENT_SETTLED à sua callbackUrl. Para um pagamento rejeitado, cancelado ou com falha, ele envia PAYMENT_REJECTED, PAYMENT_CANCELED ou PAYMENT_FAILED.
4	Sua instituição	Payments BTG	API da Lerian	GET /v1/payments/{id}	Consulte o pagamento pelo id dele.
5	Payments BTG	Sua instituição	API da Lerian	Resposta ao passo 4	Depois do passo 3, o pagamento mostra o mesmo resultado: SETTLED, REJECTED, CANCELED ou FAILED.

​

Regras

---

​

Pagar um boleto, uma conta de consumo ou um DARF

• O Payments BTG reserva o valor no Midaz antes de pagar. Quando a reserva falha, o BTG não recebe o pagamento.
• Envie um Idempotency-Key em cada requisição de pagamento. A chave é um UUID.
• Uma chave nova inicia um pagamento novo. Consulte o pagamento antes de enviar uma chave nova para a mesma cobrança.

​

Saber quando um pagamento foi liquidado

• O webhook do passo 3 pode chegar antes de o passo 2 terminar.
• O Payments BTG envia só os eventos que você lista em enabledEvents.

​

Como saber que terminou

---

• GET /v1/payments/{id} mostra o resultado: SETTLED, REJECTED, CANCELED ou FAILED.
• Na sua callbackUrl, os webhooks PAYMENT_SETTLED, PAYMENT_REJECTED, PAYMENT_CANCELED e PAYMENT_FAILED mostram os mesmos resultados.

​

O que pode dar errado

---

Situação	O que você vê	O que fazer
A resposta do BTG ao pagamento não é conhecida.	202, com o pagamento em UNCONFIRMED.	Consulte o pagamento com GET /v1/payments/{id}. Se você enviar a requisição de novo, use o mesmo Idempotency-Key.
A resposta a uma requisição de pagamento não chega.	Nenhuma resposta, ou um timeout.	Envie a mesma requisição de novo com o mesmo Idempotency-Key.
Uma requisição anterior com a mesma chave ainda está em execução.	409, código PBP-0007.	Espere. Depois envie a requisição de novo com a mesma chave.
Você envia uma chave de novo com outros campos.	422, código PBP-0013.	Envie a primeira requisição de novo com a chave dela. Para um pagamento novo, use uma chave nova.
O BTG recusa o pagamento.	422, código PBP-0014.	Nada foi pago. Verifique a cobrança antes de tentar de novo.
O BTG não recebeu o pagamento.	503, código PBP-0211.	Nada foi pago. Envie o pagamento de novo com um Idempotency-Key novo.

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

​

Relacionados

---

• Boletos e pagamento de contas
• Reservar um valor e depois confirmar ou cancelar (API)
• Pix por um parceiro