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

Criamos essas 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.

caso de uso :

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.

Fluxo de integração

Consultar o status de pagamentos ou transferências Pix

Essa funcionalidade permite que os clientes da Celcoin consigam verificar o status de pagamentos ou transferências Pix realizados, a consulta de status pode ser feita posterior ao recebimento de webhook ou em caso de muita demora para o recebimento da confirmação via webhook.

É possível informar os seguintes parâmetros de busca:

id - 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 (/baas-wallet-transactions-webservice/v1/pix/payment).
clientCode - Identificador unico fornecido pelo cliente na requisição de payment.

cURL da chamada

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v2/pix/payment/status?id=00000&endtoendId=E1000000&clientCode=00000' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Exemplo de retorno

👍

Sucesso 200

{
    "status": "CONFIRMED",
    "version": "1.0.0",
    "body": {
        "id": "60ec4471-71dd-43a3-a848-efe7a314d76f",
        "amount": 50,
        "clientCode": "1458856889",
        "transactionIdentification": null,
        "endToEndId": "E1393589320221110144001306556986",
        "initiationType": "MANUAL",
        "paymentType": "IMMEDIATE",
        "urgency": "HIGH",
        "transactionType": "TRANSFER",
        "debitParty": {
            "account": "30053913714179",
            "branch": "0001",
            "taxId": "77859635097",
            "name": "Hernani  Conrado",
            "accountType": "TRAN"
        },
        "creditParty": {
            "bank": "30306294",
            "key": null,
            "account": "42161",
            "branch": "20",
            "taxId": "12312312300",
            "name": "Fulano de Tal",
            "accountType": "CACC"
        },
        "remittanceInformation": "Texto de mensagem",
        "error": null
    }
}

❗

Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE150",
    "message": "É necessário informar pelo menos um dos campos: id, clientCode, ou endtoendId."
  }
}

No resultado, serão apresentado até 4 tipos de status diferentes:

Status 0: INITIATED: Transação Pix iniciada;

Status 1: PROCESSING: Transação ainda em processamento;
Status 2: CONFIRMED: Transação confirmada com sucesso;
Status 3: ERROR: Transação com erro.Vide nó 'error' do payload de response para detalhes sobre o 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.

Tabela de errorCode

Cenários em que a consulta não retornará o status da transação

A consulta de status da transação não retornará resultados nos casos em que a transação não tenha sido efetivamente criada/persistida na plataforma.

Isso ocorre, principalmente, quando há falha nas validações síncronas realizadas no momento da requisição de criação da transação, como por exemplo:

• Saldo insuficiente no momento da requisição
• Dados inválidos ou inconsistentes no payload.
• Regras de negócio impeditivas (ex.: bloqueios, restrições cadastrais, etc.)

Nesses cenários, a transação é recusada imediatamente na chamada da API de criação (ex.: post-payment), não sendo possível sua posterior consulta, uma vez que ela não chega a ser registrada como uma transação em processamento dentro da plataforma.

Exemplo prático:

• Cliente realiza chamada para criação de pagamento (Pix-Out);
• A API valida o saldo disponível no momento da requisição;
• Identifica saldo insuficiente;
• Retorna erro imediatamente na resposta da API;
• A transação não segue para processamento;
• Nenhum identificador transacional válido é gerado para consulta posterior;

👍

Boas práticas para integração!

Recomendamos que os clientes:

• Sempre tratem corretamente a resposta síncrona da API de criação da transação;
• Não assumam que uma requisição com erro possa ser consultada posteriormente;
• Apenas realizem consultas de status para transações que foram efetivamente aceitas para processamento.

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 (Evento: pix-reversal-in ), 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. É possível informar os seguintes parâmetros/identificadores :

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 transferências ou pagamentos neste endpoint estarão disponíveis após o recebimento do gatilho via webhook pix-reversal-in .

Modelo de Webhook

entity: pix-reversal-in

{
                        "entity": "pix-reversal-in",
                        "createTimestamp": "2023-07-27T11:17:57.783+00:00",
                        "status": "CONFIRMED",
                        "body": {
                            "amount": 40.97,
                            "oldBalance": 10,
                            "id": "8a18df09-5155-4397-acc1-3dc61df1d151",
                            "reason": "MD06",
                            "originalClientCode": "76d1d810-6ecd-41b4-9724-e3daca0e722f",
                            "returnIdentification": "D10573521202307271417gUTeaw9DZC4",
                            "originalId": "092294bc-7cc1-4575-811a-1191e7e315f0",
                            "originalEntoEndId": "E1393589320230727130301498341234",
                            "debitParty": {
                                "taxId": "46463721000",
                                "accountType": "TRAN",
                                "name": "TESTE",
                                "bank": "10573521",
                                "branch": "0001",
                                "account": "300123"
                            },
                            "creditParty": {
                                "bank": "60701190",
                                "taxId": "46463721000",
                                "accountType": "CACC",
                                "name": "TESTE",
                                "branch": "360",
                                "account": "300123"
                            }
}