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.

Essa funcionalidade deve ser utilizada sempre que sua aplicação receber uma chave Pix de um usuário, desta forma o caso de uso poderia ser:

Como Fintech quero disponibilizar para os meus usuários a possibilidade de realizar transferências Pix para qualquer instituição financeira, uma vez que ele informa as chaves do recebedor(pessoa física ou jurídica), onde será retirado o saldo de sua conta e enviado para a conta do recebedor.

Consulte a Recipe do produto com o passo a passo, requests e responses:

Consulta chave Pix no DICT

Para realizar uma transferência com uma chave Pix é necessário realizar uma consulta no DICT, através da API Retornar informações do DICT utilizando uma chave cadastrada no Pix, onde será retornado algumas informações que são obrigatórias ao realizar uma transferência, desta forma, sua aplicação deve disponibilizar para o usuário a possibilidade de informar para qual chave Pix ele deseja realizar a transferência. Essa chave pode ser um e-mail, CPF, CNPJ, telefone, ou uma chave aleatória.

Para testar em sandbox é necessario utilizar a chave Pix criada para a credencial de testes ou as chaves abaixo:

E-MAIL: [email protected]
CPF: 34331554376
CNPJ: 13935893000370
EVP(chave aleatória): 93981962-9505-474d-9899-dcb0be3d40c4
PHONE: +5511928434936

O campo payerId é obrigatório devido a uma solicitação do banco central e deve ser preenchido com um CPF, ou CNPJ, sem os caracteres especiais, da sua instituição. Para testar essa consulta em sandbox recomendamos o uso da propriedade key populada com o valor [email protected], pois nosso ambiente está preparado para retornar essa consulta com esse e-mail. O campo ownerTaxId é utilizado para comparação com o documento do proprietário da chave. Deve ser preenchido com um CPF ou CNPJ (somente números). O campo includeStatistics no header da requisição assume o valor padrão false caso não seja informado. Ele deverá ser true para que o objeto statistics seja retornado.

Modelo de request :

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/dict/v2/key' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--header 'includeStatistics: true/false' \
--data-raw '{
  "payerId": "11223344556",
  "key": "[email protected]",
  "ownerTaxId": "0001234567890"
}'

Modelo de retorno:

{
  "key": "[email protected]",
  "keyType": "EMAIL",
  "account": {
    "branch": 0,
    "accountNumber": "********",
    "accountType": "********",
    "participant": "18236120",
    "openingDate": null
  },
  "owner": {
    "type": "********",
    "taxIdNumber": "***778477**",
    "name": "teste celcoin"
  },
  "endtoendid": "E13935893202603231528o285mxZkw7t",
  "creationDate": null,
  "keyOwnershipDate": null,
  "statistics": null,
  "isSameTaxId": true
}

Apenas os campos abaixo serão retornados, isso é determinação do Banco Central.

Nome do titular (ou razão social); Nome fantasia (quando aplicável); CPF mascarado; Chave consultada; Nome do PSP (quando disponível).

Os demais campos poderão ser retornados mascarados (***) ou sem preenchimento (null).

📘

Para os campos account.*,o valor retornado na consulta deverá ser replicado na chamada de pagamento, mesmo quando mascarado ou não preenchido. Importante destacar que essas regras se aplicam somente para as iniciações do tipo DICT.

🚧

Sistema de Balde e Fichas

Esse endpoint adota um “sistema de baldes e fichas" em conformidade com o Manual Operacional do DICT (seção 13: “mecanismos de prevenção a ataques de leitura”).

O objetivo da política de baldes e fichas é garantir o uso adequado e equilibrado da API do DICT, evitando sobrecarga no sistema e protegendo a segurança e a privacidade das informações dos clientes bancários. É importante que os parceiros respeitem as limitações impostas pelo Banco Central para evitar a interrupção da operação ou o cancelamento do acesso à API.

Esse mecanismo é utilizado para controlar o número de consultas que podem ser feitas em um determinado intervalo de tempo e funcionará da seguinte maneira:

• A quantidade atual de fichas será exibida no response da requisição, através da propriedade x-bacen-bucket que será enviada no header.
• O parceiro possuirá um balde com um número máximo de fichas, que poderão ser usadas para consultar chaves Pix no DICT, com o objetivo de iniciar uma transação;
• Cada busca com sucesso ao DICT consumirá 1 ficha.
• Cada pagamento com sucesso (Pix cash-out) fará a reposição de 1 ficha.
• Uma busca com erro (400 ou 404) consumirá, de forma definitiva, 20 fichas.
• O balde de cada cliente terá uma taxa fixa de reposição de 2 fichas por minuto para PF e de 10 fichas para PJ.

Quando todas as fichas de um balde são usadas, o cliente ficará temporariamente impedido de consultar o DICT e irá receber um erro do tipo 429 (HTTP). A partir daí, será necessário esperar até que o balde esteja novamente positivo para que as consultas sejam reiniciadas.
Desta forma, pedimos atenção ao número de consultas ao DICT que realizam, a fim de evitar qualquer tipo de transtorno.

Tabela com os Campos de Consulta DICT

Transferência dos valores

Após realizar a consulta da chave no DICT, deve ser realizada a transferência dos valores, para isso é necessário realizar uma chamada na API Iniciar pagamento Pix.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/payment' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "amount": 2,
  "clientCode": "my-unique-client-code-for-idempotency",
  "endToEndId": "E139358932026032313566ZQX3kOHGyf",
  "initiationType": "DICT",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER",
  "debitParty": {
     "account": "3794245",
    "branch": 30,
    "taxId": "13935893000109",
    "accountType": "CACC",
    "name": "IS2B - Integrated Solutions to Business S.A"
  },
  "creditParty": {
    "key": "[email protected]",
    "bank": "30306294",
    "name": "Fulano de Tal"
  },
  "endToEndId": "E1393589320220720183401897103833",
  "initiationType": "DICT",
  "remittanceInformation": "Texto de mensagem",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER"
}'

Na propriedade amount, deve ser preenchido o valor a ser transferido, já na clientCode, deve ser utilizado um identificador único da sua aplicação, o qual deve ser armazenado e não pode ser repetido.

O objeto debitParty, deve ser preenchido com os dados da Conta Pagamento Proprietária da Celcoin e o objeto creditParty, deve ser populado com os dados da conta que vai receber o valor, retornados na chamada Retorna as informações do DICT utilizando uma chave cadastrada no Pix, onde a propriedade participant é igual a bank.
Em sandbox, é possivel utilizar a conta fornecida pela Celcoin tanto no debitParty como também no creditParty, isso simulará o pagamento e o recebimento.

A propriedade initiationType, deve ser populado com o valor DICT, para que a aplicação da Celcoin entenda que sua aplicação está executando uma transferência a partir de uma chave Pix.

A propriedade urgency, deve ser populada com o valor HIGH para ser executada na hora.

A propriedade transactionType, deve ser populada com valor TRANSFER, pois estamos executando uma transferência.

A propriedade paymentType, deve ser populada com IMMEDIATE para ser executada na hora.

A propriedade endToEndId, deve ser populada com o endToEndId recebido na Consulta DICT (/pix/v1/dict/v2/key).

Ao realizar a chamada de payments a Celcoin irá retirar o dinheiro da sua Conta Pagamento Proprietária e vai executar a tentativa de transferência. Caso tudo ocorra como esperado, será enviado via webhook uma notificação, porém se por algum motivo ocorrer uma falha, sua aplicação também será notificada via webhook, mas nesse cenário a Celcoin devolve o saldo retirado da conta, para ser usado em possíveis transações futuras.

Modelo de retorno:

{
    "transactionId": 9153724,
    "code": "SUCCESS",
    "slip": "     COMPROVANTE TRANSFERENCIA PIX      \n            03/03/2022 10:16            \n           TERM 11 AGENTE 999           \n                CONTROLE                \n    E1393589320220303131601345285635    \n----------------------------------------\n                PAGADOR                 \n\n                Contrato                \n            AG:1 CC:100548925           \n        CPF/CNPJ:23694719000175         \n----------------------------------------\n               RECEBEDOR                \n\n        30306294 AG:20 CC:42161         \n          CPF/CNPJ:09958359006          \n     CHAVE:[email protected]      \n----------------------------------------\n   DATA DO PAGAMENTO 03/03/2022 10:16   \n\n            VALOR R$ 25,5500            \n----------------------------------------\n              AUTENTICACAO              \n4E.E9.6B.12.73.18.88.59.FA.9D.73.B1.04.86.92.8E\n",
    "slipAuth": "4E.E9.6B.12.73.18.88.59.FA.9D.73.B1.04.86.92.8E",
    "endToEndId": "E1393589320220303131601345285635"
}

Perceba que será retornado o id da transação Celcoin (transactionID) e o campo endtoEndId, recomendamos que seja armazenado esses campos em sua aplicação, pois a Celcoin irá enviar um gatilho em seu webhook, informando se a transação ocorreu com sucesso, ou não e através dele é possível fazer essas validações.

O campo code exibe se a requisição ocorreu com sucesso ou não conforme abaixo:

• SUCCESS = Pagamento realizado com sucesso;
• SUCCESSFUL_WITH_ERROR = Pagamento realizado com sucesso, porém tivemos algum erro interno na hora de gerar comprovante;
• ALREADY_PAID = Pagamento já foi realizado anteriormente (mesmo clientCode ou endToEndId);
• ALREADY_PAYD_WITH_ERROR = Pagamento já foi realizado anteriormente (mesmo clientCode ou endToEndId), porém aconteceu algum erro como geração de comprovante.

Nos casos de retornos "SUCCESS" e "SUCCESSFUL_WITH_ERROR", o webhook será disparado confirmando a transação ou o erro ocorrido.

A propriedade slip devolve o comprovante do pagamento e o endToEndId é o id da transação Pix no BACEN.

🚧

Recomendamos que essas informações sejam persistidas do lado da sua aplicação e apresentado, para o seu usuário confirmar se deseja realizar o pagamento.

Ele optando por realizar o pagamento, deve ser realizado os processos abaixo, caso contrário, basta encerrar a execução da transferência.

Recebendo o status das transferências 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 transferência do valor para instituição bancária solicitada, ela irá disparar um gatilho (PAYMENT), no webhook de seu aplicativo, ou sistema, configurado pelo nosso time de suporte.

❗

Para realizar a configuração de um webhook é necessário entrar em contato com a nossa equipe de suporte informando a url de seu webhook, senha e usuário, no formato BASIC AUTH, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

Uma vez que a propriedade RequestBody.StatusCode.StatusId for igual a 2, seu usuário final pode ser notificado que a transferência ocorreu com sucesso, qualquer coisa diferente de 2, deve ser validado o retorno, tratado e apresentado ao usuário.

Criamos uma tabela que mostra quais são os possíveis retornos que podemos apresentar, para acessar basta clicar nesse link.

Para realizar testes em sandbox e receber o webhook de PAYMENT com status de sucesso ( "StatusId": 2 e "Description": confirmed), deve ser utilizada a chave Pix criada para a credencial de testes ou o payload e chaves informadas no começo do artigo.

Caso você queira simular um pagamento com status de rejeitado ( "StatusId": 3 e "Description": Error), basta utilizar a chave Pix 66486782000129 , consequentemente a requisição de pagamento ficará com o objeto creditParty da seguinte forma:

"creditParty": {
    "bank": "13935893",
    "key": "66486782000129",
    "name": "Teste erro Celcoin"
  },

Exemplo de aplicação

Criamos o protótipo de um aplicativo para exemplificar a utilização da API:

❗️

Com a alteração definida pela Circular BCB nº 501, o Banco Central passou a impedir, a partir de 04/10/2025, o retorno de dados de chaves Pix que estejam marcadas como suspeitas de fraude no DICT. Isso significa que, sempre que uma nova chave com essa marcação for consultada, o DICT não retornará informações do titular ou da conta vincula

Exemplo de retorno com chave marcada com fraude

{
"code":"422",
"description":"Chave Pix com dados restritos por marcação de fraude."
}

End To End ID no Pix - Entendendo como Funciona

A cada consulta de chave Pix realizada, a Celcoin irá gerar e devolver no response um EndToEndId, que deverá ser utilizado na hora de efetivar a transação.

O End To End ID é o identificador único entre todo o arranjo, seguindo um padrão definido pelo próprio Banco Central. A principal forma de identificar uma transação Pix, é através do End To End ID da mesma, que trafega na Instituição Pagadora, Instituição Recebedora e no Banco Central.

Cada EndToEndID tem validade máxima de 12 horas após o momento de geração do mesmo.