Consultar transferências, pagamentos e devoluções de Pix-Out

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

Fluxo de integração

Consultar o status de um pagamento ou transferência Pix

Para realizar essa consulta disponibilizamos a api Verificar o status de um pagamento Pix. É possível informar 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 retornado na consulta DICT e no retorno do endpoint de pagamento (v1/payment).
clientCode - Identificador unico fornecido pelo cliente na 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 terão um status válido somente 20 segundos após o recebimento da resposta de sucesso da requisição de pagamento. Recomendamos o uso deste endpoint como contingência durante o processamento da transação. Vale ressaltar que o endpoint apenas retornará registros de operações realizadas nos últimos 8 dias, com base nos parâmetros fornecidos.

🚧

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.

Consultar uma devolução de pagamento ou transferência 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).