Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Devolver um Pix Cash-in

Suggest Edits

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

  1. Realizar autenticação na API - [API Reference]
  2. 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

CampoDescrição
idIdentificador da transação do recebimento pix.
endToEndIdIdentificador ponta-a-ponta associado ao recebimento pix.
clientCodeIdentificador único gerado pelo cliente.
amountValor da transação.
reasonRazã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.
reversalDescriptionTexto 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

CodeMessage
CBE001ClientCode é obrigatório.
CBE093ClientCode possui tamanho maximo de 200 caracteres.
CBE094amount é obrigatório.
CBE095amount invalido. Favor verificar a formatação do campo e deve ser maior que 0.
CBE100Existe um lançamento idêntico pendente. Favor aguarde para realizar esta operação para evitar duplicidade.
CBE101Já existe um lançamento com o mesmo clientCode. Favor realizar uma nova operação.
CBE102Lançamento de debito não permitido. Valor ultrapassa o limite maximo permitido por operação.
CBE123Transação não permitida. Conta com saldo insuficiente.
CBE154reason é obrigatório.
CBE155reason invalido.
CBE156reversalDescription possui tamanho máximo de 140 caracteres.
CBE157Devolução não permitida. Somatório de devoluções ou o valor da devolução ultrapassa o valor total do recebimento pix.
CBE158Devolução não permitida. Prazo limite para devolução foi expirado.
CBE159Lançamento não permitido. Sua conta esta bloqueada.
CBE160Lanç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

StatusDescrição
idIdentificador da transação retornado na requisição de payment.
clientCodeIdentificador único gerado pelo cliente.
returnIdentificationIdentificador 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

CodeMessage
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."
  }
}

Modelo de Webhook

entity: pix-reversal-out

{
"entity": "pix-reversal-out",
"createTimestamp": "2023-07-27T10:46:30.360+00:00",
"status": "CONFIRMED",
"body": {
"amount": 250,
"oldBalance": 50,
"currentBalance": 6.52,
"id": "b94150c9-7dad-4b21-8183-50c83f4c5dd8",
"clientCode": "719d673b-4bec-434e-98f7-f28a9871cb48",
"reason": "MD06",
"returnIdentification": "D13935893202307271346SPpDyb4f123",
"originalEndToEndId": "E1393589320230727130301498341234",
"originalPaymentId": "4d22dea5-5507-45dd-9126-c6be307e6208"
 }
}

Tabela de apoio


amountValor
oldBalanceSaldo anterior
currentBalanceSaldo atual
idIdentificador da transação do recebimento pix
clientCodeCódigo do cliente
reasonRazã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.
returnIdentificationIdentificação do retorno
originalEndToEndIdEndtoEnd id da transação recebida, que é o pix que você deseja devolver
originalPaymentIdId do pagamento

Updated about 1 month ago