Pular para o conteúdo principal

Devolução de recebimentos Pix

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 [corp@celcoin.com.br.](mailto:corp@celcoin.com.br. 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.

perigo

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 derequest:

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 deresponse:

{
    "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.

atenção

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.

info

É 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.

perigo

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.