Return of Pix receipts
Prerequisites for implementation:
-
Have a Celcoin API key, for more information access this link
-
Have familiarity with Rest APIs using the OAuth 2.0 protocol.
-
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.
Use case:
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.
Returning a Pix receipt
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.
To configure a webhook, you must contact our support team, providing your webhook URL, password and username, in BASIC format . This way, they will register you on our platform so that triggers can be sent.
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
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_:
JSON
{ "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.
Request model:
cURL
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}'
Return model:
JSON
{ "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: Transaction still in processing;
CONFIRMED: Transaction confirmed successfully;
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.
To configure a webhook, you must contact our support team, providing your webhook URL, password and username, in BASIC format . This way, they will register you on our platform so that triggers can be sent.
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.