Transferência Pix a partir de uma chave

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.

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 Retorna as 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.

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.

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}' \
--data-raw '{
  "payerId": "11223344556",
  "key": "[email protected]"
}'

Modelo de retorno:

{
    "key": "[email protected]",
    "keyType": "EMAIL",
    "account": {
        "openingDate": "2014-01-22T03:00:00Z",
        "participant": "60701190",
        "branch": 1500,
        "accountNumber": "00611833",
        "accountType": "CACC"
    },
    "owner": {
        "taxIdNumber": "05216208000166",
        "type": "LEGAL_PERSON",
        "name": "TESTE DE RAZAO SOCIAL"
    },
    "endtoendid": "E1393589320220302185301269155842"
}

Note que no retorno é apresentado no objeto account nas propriedades branch(agência), accountNumber(número da conta), accountType(tipo da conta), os dados bancários da chave que foi consultada, no caso de uma pessoa física, ou empresa que irá receber a transferência. A propriedade participant representa o código da instituição financeira participante no ISPB (Instituição de Sistema de Pagamentos Brasileiros), ou seja, para onde será enviado o dinheiro.

No objeto owner será apresentado informações sobre o dono da chave, como taxIdNumber(tipo do documento CPF, ou CNPJ), type(tipo de pessoa), sendo LEGAL_PERSON(pessoa jurídica) e NATURAL_PERSON(pessoa física) e name(o nome do dono).

Por fim, mas não menos importante, é apresentado a propriedade endtoendid que seria o identificador de ponta a ponta da transação de consulta que também é utilizado para transferências com QRcode.

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": 25.55,
  "clientCode": "14588549",
  "debitParty": {
    "account": "3794245",
    "branch": 30,
    "taxId": "13935893000109",
    "accountType": "CACC",
    "name": "IS2B - Integrated Solutions to Business S.A"
  },
  "creditParty": {
    "key": "[email protected]",
    "bank": "30306294",
    "account": "42161",
    "branch": 20,
    "taxId": "07693440704",
    "accountType": "CACC",
    "name": "Davi Ferreira de Sousa"
  },
  "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 objeto debitParty, deve ser preenchido com os dados da conta bolsão 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, accountNumber igual a account, taxIdNumber igual a taxId.

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.

Ao realizar a chamada de payments a Celcoin irá retirar o dinheiro da sua conta bolsão 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:07693440704          \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.

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 status das transferências via gatilho

Para conseguir receber da Celcoin os status das transferências, pagamentos e cobranças, deve ser realizada a configuração de um webhook.

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.

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 PAYMENTS com status igual 2 (sucesso), deve ser utilizado o payload informado no começo do artigo.

Caso você queira simular o pagamento com status rejeitado, basta alterar o payload alterando o objeto creditParty da seguinte forma:

"creditParty": {
        "bank": "30306294",
        "account": "10545584",
        "branch": 0,
        "taxId": "11122233344",
        "accountType": "CACC",
        "name": "Celcoin"
    }

Did this page help you?