Devolver um Pix Cash-in
Os endpoints a seguir estão relacionados ao fluxo obrigatório de devolução de recebimentos Pix. A integração com o endpoint de devolução é essencial para permitir que o usuário devolva um Pix recebido. Além disso, disponibilizamos uma rota para consultar o status de uma devolução, que poderá ser utilizado no fluxo de contingência garantindo o sucesso e controle das requisições de devolução.
caso de uso :
Como fintech quero construir do lado da minha aplicação o fluxo de devoluções de Pix recebidos, para que meus usuários e clientes possam devolver os valores recebidos, de forma parcial ou total. Além disso preciso de uma solução preditiva de verificação, a fim de assegurar que uma ou mais devoluções sejam processadas com sucesso.
Devolução de recebimento Pix
Essa funcionalidade pode ser utilizada após receber o gatilho de webhook "pix-payment-in". Com os dados do recebimento será possivel devolve-lo ao pagador.
Passos para Integrar
- Realizar autenticação na API - [API Reference]
- Realizar uma devolução Pix -[API Reference]
Fluxo de integração
A confirmação do sucesso na devolução do recebimento Pix será enviada via webhook no evento pix-reversal-out.
Importante
- O valor da devolução pode ser total ou parcial
- A devolução de um Pix ocorre de forma instantânea, como já é em seu próprio modelo de negócio.
- O prazo máximo para criar a devolução de uma transação Pix, é de até 90 dias, sendo o valor menor ou igual ao que recebeu.
cURL da chamada
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas-wallet-transactions-webservice/v1/pix/reverse' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
"endToEndId": "E3030629420200808185300887639654",
"clientCode": "1458854",
"amount": 150.54,
"reason": "MD06",
"reversalDescription": "Devolução do churrasco"
}'
JSON da chamada
{
"id": "34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
"endToEndId": "E3030629420200808185300887639654",
"clientCode": "1458854",
"amount": 150.54,
"reason": "MD06",
"reversalDescription": "Devolução do churrasco"
}
Descrição dos Campos
| Campo | Descrição |
|---|---|
| id | Identificador da transação do recebimento pix. |
| endToEndId | Identificador ponta-a-ponta associado ao recebimento pix. |
| clientCode | Identificador único gerado pelo cliente. |
| amount | Valor da transação. |
| reason | Razão da Devolução. Podendo ser: BE08: Devolvido como resultado de um erro bancário. FR01: Devolução por suspeita de fraude. MD06: Devolução solicitada pelo cliente final. SL02: Devolução do valor em dinheiro devido a um erro relacionado ao Pix Saque ou Pix Troco. |
| reversalDescription | Texto opcional a ser apresentado ao pagador contendo informações sobre a devolução.. |
Exemplo de retorno
Sucesso 200
{
"status": "PROCESSING",
"version": "1.0.0",
"body": {
"id": "34fee7bc-4d40-4605-9af8-398ed7d0d6b4",
"amount": 25.55,
"clientCode": "1458854",
"originalPaymentId": "34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
"endToEndId": "E3030629420200808185300887639654",
"returnIdentification": "D3030629420200808185300887639654",
"reason": "MD06",
"reversalDescription": "Devolução do churrasco"
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CBE001",
"message": "ClientCode é obrigatório."
}
}
Tabela de errorCode
| Code | Message |
|---|---|
| CBE001 | ClientCode é obrigatório. |
| CBE093 | ClientCode possui tamanho maximo de 200 caracteres. |
| CBE094 | amount é obrigatório. |
| CBE095 | amount invalido. Favor verificar a formatação do campo e deve ser maior que 0. |
| CBE100 | Existe um lançamento idêntico pendente. Favor aguarde para realizar esta operação para evitar duplicidade. |
| CBE101 | Já existe um lançamento com o mesmo clientCode. Favor realizar uma nova operação. |
| CBE102 | Lançamento de debito não permitido. Valor ultrapassa o limite maximo permitido por operação. |
| CBE123 | Transação não permitida. Conta com saldo insuficiente. |
| CBE154 | reason é obrigatório. |
| CBE155 | reason invalido. |
| CBE156 | reversalDescription possui tamanho máximo de 140 caracteres. |
| CBE157 | Devolução não permitida. Somatório de devoluções ou o valor da devolução ultrapassa o valor total do recebimento pix. |
| CBE158 | Devolução não permitida. Prazo limite para devolução foi expirado. |
| CBE159 | Lançamento não permitido. Sua conta esta bloqueada. |
| CBE160 | Lançamento não permitido. Sua conta esta encerrada. |
| CBE204 | É necessário informar pelo menos um dos campos: transactionId ou endToEndId. |
Error 401 | Error 404 | Error 500 | Error 504
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Consultar o Status de uma Devolução de Recebimento Pix
Essa funcionalidade pode ser utilizada após receber o gatilho de webhook "pix-reversal-out". Com os identificadores, é possivel obter o status da devolução de um recebimento.
Consultar uma devolução Pix -[API Reference]
Fluxo de integração
cURL da chamada
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas-wallet-transactions-webservice/v1/pix/reverse/status?returnIdentification=D3030629420200808185300887639654' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
Parâmetros para realizar busca
| Status | Descrição |
|---|---|
| id | Identificador da transação retornado na requisição de payment. |
| clientCode | Identificador único gerado pelo cliente. |
| returnIdentification | Identificador ponta-a-ponta associado a devolução pix. |
Exemplo de retorno
Sucesso 200
{
"status": "PROCESSING",
"version": "1.0.0",
"body": {
"id": "34fee7bc-4d40-4605-9af8-398ed7d0d6b4",
"amount": 25.55,
"clientCode": "1458854",
"originalPaymentId": "34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
"endToEndId": "E3030629420200808185300887639654",
"returnIdentification": "D3030629420200808185300887639654",
"reason": "MD06",
"reversalDescription": "Devolução do churrasco"
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CBE001",
"message": "ClientCode é obrigatório."
}
}
Tabela de errorCode
| Code | Message |
|---|---|
| CBE161 | É necessário informar pelo menos um dos campos: id, clientCode, ou returnIdentification. |
Error 401 | Error 404 | Error 500 | Error 504
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CIE999",
"message": "Ocorreu um erro interno durante a chamada da api."
}
}
Updated 3 days ago