Consultar transfêrencias, pagamentos e devoluções de cash-out 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 [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Criamos essa API, pois sabemos que não é possível garantir que seu ambiente esteja 100% disponível para receber todas os gatilhos de transferências, ou pagamentos da API de Pix Celcoin. Fora isso, também recomendamos o uso dessa API, caso ao tentar realizar uma requisição, a nossa receba algum erro desconhecido, como 5xx.

Desta forma, um caso de uso seria:

Como fintech quero construir do lado da minha aplicação uma medida preditiva de busca, com objetivo de validar se um ou alguns pagamentos ocorrem com sucesso, para que meu usuário final não tenha problemas com seus pagamentos, ou transferências e com isso consigo fazer sem problemas minha conciliação bancária.

Buscar status dos pagamentos

Para realizar essa busca disponibilizamos a api Verificar o status de um pagamento Pix. Nesta consulta é possível passar os seguintes parâmetros de busca:

transactionId - Identificador da transação retornado na requisição de payment
endtoendId - identificador ponta-a-ponta da transação. O mesmo utilizado no DICT GET ou no retorno da v1/payment.
clientCode - Identificador unico fornecido pelo cliente durante a requisição de payment.

📘

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

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/pix/v1/payment/pi/status?transactionId=9162909' \
--header 'accept: application/json' \
--header 'Authorization: Bearer [acess_token]'

Modelo de retorno:

{
    "transactionId": 9162909,
    "clientCode": "1458854123678",
    "endToEndId": "E1393589320220307125800721814129",
    "status": "CONFIRMED",
    "error": null
}

No resultado, será apresentado um dos seguintes status:

INITIATED: Transação Pix iniciada;
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.

🚧

Atenção!

Caso ocorra algum erro da familia 5xx ao tentar realizar um pagamento, ou transfêrencia Pix e, ao consultar nossa api o status da transação esteja PROCESSING, recomendamos que aguarde até receber o disparo do gatilho com o novo status da transação. Sendo assim, não recomendamos o cancelamento da transação, pois o mesmo pode acarretar problemas em sua integração.

Buscar uma devolução de pagamentos Pix

Ao realizar um cash-out Pix é possivel que o recebedor solicite a devolução do recebimento.
Notificaremos este cenario via webhook, em seguida será possivel consultar os detalhes da devolução. Para realizar essa busca disponibilizamos a api Verificar detalhes de uma devolução de cash-out Pix. Nesta consulta é possível passar os seguintes parâmetros de busca:

returnIdentification- EndToEnd da devolução.
transactionId- Identificador da devolução
clientCode - Identificador unico fornecido pelo cliente durante a requisição de payment.

📘

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

Modelo de request:

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v2/receivement/v2/devolution/status?returnIdentification=D13935893202409032338GGn4wwztHCT' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Modelo de retorno:

{
    "status": "CONFIRMED",
    "returnIdentification": "D13935893202409032338GGn4wwztHCT",
    "additionalInformation": null,
    "originalEndToEndId": "E139358932024090323354ShyHOpjrzn",
    "transactionId": 2147967055,
    "transactionIdPayment": 2147967043,
    "transactionType": "REVERTED",
    "amount": 15.0000,
    "reason": "BE08",
    "reversalDescription": null,
    "createdAt": "2024-09-03T20:38:04.313"
}

No resultado, por se tratar de uma devolução recebida o status será sempre:
CONFIRMED: Devolução recebida com sucesso;

As consultas de devoluções de pagamentos neste endpoint, só terão retorno após o recebimento do gatilho via webhook (Evento REVERTED).