Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Devolução de recebimentos Pix

Suggest Edits

Pré requisitos para implementação:

  • Possuir uma chave api da Celcoin, para mais informações acessar esse link

  • Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.

  • Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [[email protected].](mailto:[email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

  • Ter uma chave Pix cadastrada, caso sua empresa não tenha, basta entrar em contato com o nosso suporte, informando uma chave que nós realizamos esse cadastro. Não recomendamos o envio de um CNPJ, ou e-mail para esse cadastro devido a possibilidade de fraudes.

Essa funcionalidade deve ser utilizada sempre que sua aplicação desejar realizar a devolução de um valor Pix.

Caso de uso:

Como Fintech quero disponibilizar para os meus usuários, a possibilidade de devolver um valor de uma transação Pix, onde ele deve preencher apenas o valor que deseja reembolsar dentro de uma transferência recebida e clicar em devolver, onde o valor será estornado parcialmente, ou completamente para a entidade que fez a transferência, ou pagamento.

Devolução de um recebimento Pix

O webhook é uma forma de receber informações de maneira assíncrona, onde geralmente são disparados gatilhos, no formato JSON, quando um evento acontece. Para realizar uma devolução é necessário que a sua conta Celcoin tenha recebido uma transação, sendo assim, será disparado um gatilho (REVERTPIX), no webhook de seu aplicativo, ou sistema, configurado pelo nosso time de suporte.

❗

Para realizar a configuração de um webhook é necessário entrar em contato com a nossa equipe de suporte informando a url de seu webhook, senha e usuário, no formato BASIC, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

Após receber o gatilho, deve ser realizado uma chamada na api Criar uma devolução (estorno) de um Pix já pago, onde precisa ser informado o transactionId (Identificador da transação original recebido no gatilho de “RECEIVEPIX) e a propriedade reason campo para definir qual motivo 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

Modelo de request: 

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v2/reverse/pi/:transactionId' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
  "reason": "BE08",
  "clientCode": "50321213-9af7-4cc9-8003-7c068e98b1f7",
  "amount": 10,
  "additionalInformation": "teste",
  "reversalDescription": "teste"
}
'

Modelo de response: 

{
    "status": 200,
    "transactionId": 2147967054,
    "amount": 150.54,
    "message": null,
    "returnIdentification": "D13935893202409032338GGn4wwztHCT"
}

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.

🚧

Recomendamos que seja armazenado a propriedade transactionId retornada no request da solicitação de devolução, pois será enviado o gatilho REVERTPIX, para informar sua aplicação que o estorno ocorreu com sucesso e para validar isso o ideal é usar esse campo.


Buscar status de uma devolução de recebimento Pix

Para realizar essa busca disponibilizamos a api Consulta o status de uma devolução de recebimento Pix criada. Nesta consulta é possível passar os seguintes parâmetros de busca:

returnIdentification- EndToEnd da devolução criada.
transactionId- Identificador da devolução criada
clientCode - Código interno informado pelo cliente no momento da criação da devolução.

📘

É necessário informar pelo menos um dos campos para realizar a consulta.

Modelo de request:

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v1/reverse/pi/status?transactionId=2147967054&clientCode=61a388eb-9f42-4365-8aae-f0f057347a50&returnIdentification=D13935893202409032338GGn4wwztHCT' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Modelo de retorno:

{
    "status": "CONFIRMED",
    "returnIdentification": "D13935893202409032338GGn4wwztHCT",
    "additionalInformation": "teste",
    "clientCode": "61a388eb-9f42-4365-8aae-f0f057347a50",
    "transactionIdentification": 0,
    "originalEndToEndId": "E139358932024090323354ShyHOpjrzn",
    "transactionId": 2147967054,
    "amount": 150.54,
    "reason": "BE08",
    "error": null
}

No resultado, será apresentado um dos seguintes status:

PROCESSING: Transação ainda em processamento;
CONFIRMED: Transação confirmada com sucesso;
ERROR: Transação com erro.

As consultas de status realizadas neste endpoint, só terão um status válido a partir de 20 segundos após o recebimento da resposta de sucesso da requisição de pagamento.


Recebendo status da devolução do recebimento via webhook

O webhook é uma forma de receber informações de maneira assíncrona, onde geralmente são disparados gatilhos, no formato JSON, quando um evento acontece. Após a Celcoin realizar a tentativa de reversão do valor para instituição bancária solicitada, ela irá disparar um gatilho (REVERTPIX), no webhook de seu aplicativo, ou sistema, configurado pelo nosso time de suporte.

❗

Para realizar a configuração de um webhook é necessário entrar em contato com a nossa equipe de suporte informando a url de seu webhook, senha e usuário, no formato BASIC, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

Atenção: os webhooks em Sandbox ficam indisponíveis no período entre 22:00h e 07:00h (horário de Brasília). Ao testar a API nestes horários você não receberá os webhooks.

Updated 1 day ago