Consulta 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 [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

O uso dessa API é recomendado apenas para fluxos de exceção e/ou conferência de recebimentos. Fora esses cenários, o uso desse endpoint não se faz necessário, já que todos os dados contidos no seu retorno serão previamente disponibilizados na notificação via webhook.

❗️
Atenção!
Este fluxo não substituí o caminho obrigatório com a utilização dos gatilhos via webhook.

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 informações ou a existência de um recebimento Pix, para que meu usuário final não tenha problemas com seus recebimentos e sejam evitados problemas de conciliação.

Buscar dados de um recebimento

Este endpoint é destinado à consulta de qualquer recebimento Pix. Para realizar essa busca disponibilizamos a api Consulta o status de um Recebimento Pix. Nesta consulta é possível passar os seguintes parâmetros de busca:

endtoEnd- EndtoEnd do recebimento (webhook)
transactionId- Identificador do recebimento (webhook)
transactionIdBrCode - TransactionID retornado na criação do QRCode.

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

Modelo de request:

curl --request GET \
     --url 'https://sandbox.openfinance.celcoin.dev/pix/v1/receivement/status?endtoEnd=0&transactionId=0&transactionIdBrCode=0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}'

Modelo de retorno:

{
  "requestBody": {
    "transactionType": "RECEIVEPIX",
    "transactionId": 761679887,
    "amount": 118,
    "debitParty": {
      "account": "1234567",
      "bank": "12345678",
      "branch": "30",
      "personType": "NATURAL_PERSON",
      "taxId": "12345678901",
      "accountType": "CACC",
      "name": "Celcoin TESTE Ltda"
    },
    "creditParty": {
      "bank": "12345677",
      "branch": "30",
      "account": "1234567",
      "personType": "LEGAL_PERSON",
      "taxId": "12345678000123",
      "accountType": "CACC",
      "name": "CELCOIN TESTE INTERNO LTDA",
      "key": "f3197f49-2615-41eb-9df2-e6224ebb4470"
    },
    "endToEndId": "E18236120202001199999s0149012FPC",
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk761678748",
    "transactionIdBRCode": "761678748",
    "initiationType": "MANUAL",
    "transactionTypePix": "TRANSFER",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH"
  }
}

A consulta neste endpoint apenas retornará dados caso os identificadores informados estejam relacionados a um Pix recebido, ou seja, após o recebimento do gatilho via webhook.

Buscar dados de um recebimento (Versão Enriquecida (V2))

Este endpoint também é destinado à consulta de qualquer recebimento Pix, porém aceita o identificador utilizado na criação do QRCode ("clientRequestId"). Para realizar essa busca disponibilizamos a api Consulta o status de um Recebimento Pix -Versão Enriquecida (V2). Nesta consulta é possível passar os seguintes parâmetros de busca:

endtoEnd- EndtoEnd do recebimento (webhook).
transactionId- Identificador do recebimento (webhook).
transactionIdBrCode- TransactionID retornado na criação do QRCode.
clientRequestId- Identificador único fornecido pelo cliente durante a criação de um QRCode.

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

❗
O campo clientRequestId é um identificador único que deve ser gerado pelo cliente no momento da criação do QR Code. Caso haja mais de um QR Code gerado com o mesmo identificador, a consulta irá retornar apenas o primeiro QR Code gerado. Não será possível consultar os outros QR Code's utilizando esse parâmetro de busca.

Modelo de request:

curl --request GET \
     --url 'https://sandbox.openfinance.celcoin.dev/pix/v2/receivement/v2/status?endtoEnd=0&transactionId=0&transactionIdBrCode=0&clientRequestId=0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}'

Modelo de retorno: com status = CONFIRMED

{
    "requestBody": {
        "status": "CONFIRMED",
        "transactionType": "RECEIVEPIX",
        "transactionId": 202603110000000531,
        "amount": 0.66,
        "endToEndId": "E30944783202603111754035824df3da",
        "createTimestamp": "03/11/2026 17:54:08",
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000550509",
        "transactionIdBRCode": "4000550509",
        "initiationType": "DYNAMIC_QRCODE",
        "transactionTypePix": "TRANSFER",
        "paymentType": "IMMEDIATE",
        "urgency": "HIGH",
        "debitParty": {
            "account": "50024",
            "bank": "30944783",
            "branch": "0001",
            "personType": "LEGAL_PERSON",
            "taxId": "11935552000108",
            "accountType": "CACC",
            "name": "INVIZZA"
        },
        "creditParty": {
            "bank": "13935893",
            "branch": "0001",
            "account": "30054126591",
            "personType": "LEGAL_PERSON",
            "taxId": "18700590000120",
            "accountType": "TRAN",
            "name": null,
            "key": "888e7c1a-00b9-4205-bae1-576ee2c7ffe1"
        },
        "clientRequestId": null
    }
}

Modelo de retorno com status = PENDING Caso onde a transação ainda está em análise pelo bloqueio cautelar.

{
    "requestBody": {
        "status": "PENDING",
        "transactionType": "RECEIVEPIX",
        "transactionId": 202603110000000531,
        "amount": 0.66,
        "endToEndId": "E30944783202603111754035824df3da",
        "createTimestamp": "03/11/2026 17:54:08",
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000550509",
        "transactionIdBRCode": "4000550509",
        "initiationType": "DYNAMIC_QRCODE",
        "transactionTypePix": "TRANSFER",
        "paymentType": "IMMEDIATE",
        "urgency": "HIGH",
        "debitParty": {
            "account": "50024",
            "bank": "30944783",
            "branch": "0001",
            "personType": "LEGAL_PERSON",
            "taxId": "12345678910",
            "accountType": "CACC",
            "name": "Beltrano"
        },
        "creditParty": {
            "bank": "13935893",
            "branch": "0001",
            "account": "30054126591",
            "personType": "LEGAL_PERSON",
            "taxId": "12345678910",
            "accountType": "TRAN",
            "name": "Fulano",
            "key": "888e7c1a-00b9-4205-bae1-576ee2c7ffe1"
        },
        "clientRequestId": null
    }
}

A consulta neste endpoint apenas retornará dados caso os identificadores informados estejam relacionados a um Pix recebido, ou seja, após o recebimento do gatilho via webhook.

Updated 12 days ago