Confirmação do pagamento
stable
Após o título ter sido validado com sucesso, o parceiro deverá utilizar este endpoint para confirmar o pagamento . Somente após a confirmação, o pagamento será efetivado.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O parceiro possua o ID de pagamento gerado na validação do título;
- O cliente possua uma conta e cadastro ativos pra que seja possível debitar o saldo do pagamento.
Requisição
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/bill-payment/confirm
--location --request POST 'https://api-mtls.sandbox.bankly.com.br/bill-payment/confirm' \
--header 'api-version: 1.0' \
--header 'authorization: Bearer {{Token}}' \
--header 'content-type: application/*+json' \
--header 'x-correlation-id: GUID' \
--data '{
"id": "código ID gerado na etapa de validação",
"bankBranch": "{{bankBranch}}",
"bankAccount": "{{bankAccount}}",
"amount": {{00.00}}
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
| Scope | Descrição |
|---|---|
payment.confirm | Concede acesso para confirmar o pagamento de um título. |
Cabeçalhos (Headers)
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
authorization | Obrigatório. Token de autorização do tipo Bearer. |
x-correlation-id | Obrigatório. Informe um GUID, sendo um novo cada requisição. |
Parâmetros da rota (Path)
Não é necessário enviar parâmetros no path desta requisição.
Corpo da requisição (Body)
No body, envie o seguintes campo em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
id | string | Obrigatório. Código ID gerado na etapa de validação. |
bankBranch | string | Obrigatório. Número da agência do banco do pagador. |
bankAccount | string | Obrigatório. Número da conta do pagador. |
amount | number | Obrigatório. Valor a ser pago. |
description | string | Descrição do pagamento. |
{
"id": "código ID gerado na etapa de validação",
"bankBranch": "{{bankBranch}}",
"bankAccount": "{{bankAccount}}",
"amount": 00.00,
"description": "Descrição do pagamento"
}
Resposta (Response)
O status code 200 indicará que o pagamento foi confirmado com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
authenticationCode | string | Id de confirmação da transação que será utilizado para realizar consultas sobre o pagamento. |
settleDate | string | Data em que o pagamento será liquidado, no formato ISO 8601 - UTC. Caso a data de vencimento coincida com feriados ou finais de semana, esse campo informará a data do próximo dia útil. |
{
"authenticationCode": "4b3eaf21-0e70-47f1-ab39-8f742dd5ed7a",
"settleDate": "2022-03-24T00:00:00"
}
Após o envio da requisição de confirmação (status Created), e caso não haja nenhum impedimento, o pagamento é confirmado (status Completed), e o valor é retirado da conta do pagador.
Isso geralmente acontece instantaneamente, porém, a compensação do título poderá ocorrer em até três dias úteis.
Nota
Em caso de intermitência, e consequente atraso na confirmação do pagamento em mais de 30 minutos, o dinheiro do pagador é estornado para sua conta e a transação é cancelada (status Canceled).
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
| Status code | Código | Mensagem | Descrição |
|---|---|---|---|
| 400 | ASSIGNOR_NOT_AUTHORIZED | Non authorized assignor, payment was not completed | Comerciante não autorizado. O pagamento não foi efetivado. |
| 400 | PAYMENT_AMOUNT_GREATER_THAT_MAX_ALLOWED_AMOUNT | Amount to be paid is above the maximum allowed amount | O valor do pagamento informado é maior do que o permitido. |
| 400 | PAYMENT_AMOUNT_LOWER_THAT_MIN_ALLOWED_AMOUNT | Amount to be paid is bellow the min allowed amount | O valor informado é inferior ao mínimo permitido. Consulte o campo minAmount retornado no endpoint de validação do título. |
| 400 | QUERY_ID_ALREADY_UTILIZED | Query protocol ID already utilized by another payment | O ID informado já foi utilizado anteriormente. |
| 400 | QUERY_ID_NOT_FOUND | Query protocol ID not not found in the current date | Id não encontrado. É possível que a consulta tenha sido realizada no mesmo dia da criação do pagamento. |
| 400 | INVALID_BAR_CODE_BY_QUERY_ID | Bar Code is incorrect for the query protocolId informed | Código de barras inválido. |
| 400 | AMOUNT_NOT_ALLOWED | Payment amount not allowed | O valor informado no campo amount é inválido. |
| 400 | PAYMENT_ALREADY_PERFORMED | Payment already performed | O pagamento já foi realizado. |
| 400 | TRANSACTION_NOT_FOUND | Transaction not found | Código de barras ou linha digitável é inválida. |
| 400 | CASHOUT_LIMIT_NOT_ENOUGH | Sender does not have sufficient cash out limit | A transação excede o limite de valor da transferência. |
| 400 | OPERATIONAL_ERROR | There is no resource available to perform a transaction at this time. | Não há recurso disponível para realizar a transação no momento. |
| 400 | OPERATION_NOT_COMPLETED | Operation not completed. Try Again | A operação não foi completada. Tente novamente em alguns minutos. |
| 400 | AMOUNT_BELLOW_MIN_ALLOWED | Payment amount bellow min allowed | O valor informado é inferior ao mínimo permitido. Consulte o campo minAmount retornado no endpoint de validação do título. |
| 400 | AMOUNT_ABOVE_MAX_ALLOWED | Payment amount above max allowed | O valor informado é superior ao máximo permitido. Consulte o campo maxAmount retornado no endpoint de validação do título. |
| 400 | PAYMENT_CONFIRMATION_ALREADY_IN_PROCESS | A confirmation is already being processed for the payment in question. | A confirmação desse pagamento já está está sendo processada. |
| 400 | PAYMENT_VALUE_EXCEEDED | Exceeded the maximum value | Este boleto supera o valor máximo que pode ser pago, sendo R$249.999,99 para fichas de compensação e R$950.000,00 para concessionárias, tributos e convênios. |
| 400 | PAYMENT_AMOUNT_CANNOT_BE_CHANGED | Payment amount cannot be changed | O valor do pagamento não pode ser alterado. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400.
Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. O evento é:
| Evento | Descrição |
|---|---|
| BILL_PAYMENT_WAS_CONFIRMED | Pagamento confirmado. |
Updated 12 days ago