DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Transferência Pix a partir de dados bancários

Suggest Edits

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 possuir os dados bancários de um cliente (instituição financeira, tipo da conta, agência, conta e a titularidade), ou quando o usuário informar que deseja efetuar uma transferência com Pix informando os dados bancários em seu aplicativo, ou sistema, 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 informar os dados bancários do recebedor, onde será retirado o saldo de sua conta e enviado para a conta de outra pessoa, ou empresa.

Iniciar pagamento

Com os dados bancários do usuário e o valor que ele deseja realizar a transferência, deve ser realizada 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 '{
  "vlcpAmount": 15.55,
  "vldnAmount": 10,
  "withdrawalServiceProvider": "13935893",
  "withdrawalAgentMode": "AGTEC",
  "transactionIdentification": "string",
  "endToEndId": "string",
  "debitParty": {
    "account": "1234567",
    "branch": 30,
    "bank": "12345678",
    "taxId": "13935893000109",
    "accountType": "CACC",
    "name": "IS2B - Integrated Solutions to Business S.A"
  },
  "creditParty": {
    "key": "5244f4e-15ff-413d-808d-7837652ebdc2",
    "bank": "30306294",
    "account": "10545584",
    "branch": 0,
    "taxId": "11122233344",
    "accountType": "CACC",
    "name": "Celcoin"
  },
  "initiationType": "DICT",
  "taxIdPaymentInitiator": "01203324000124",
  "remittanceInformation": "string",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER",
  "clientCode": "1458854",
  "amount": 25.55
}'

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, perceba que existe dentro dele uma propriedade bank, para consultar o valor a ser atribuído nesse campo, basta realizar um GET na API Lista participantes do Pix

No creditParty o parâmetro accountType pode ser destes 4 tipos:

  • CACC - Normal ou contas digitais
  • TRAN - Conta de pagamentos
  • SLRY - Conta salario
  • SVGS - Conta poupança

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

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 de valores.

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

Modelo de response: 

{
  "transactionId": 45854857,
  "code": "",
  "slip": "COMPROVANTE TRANSFERENCIA PIX...",
  "slipAuth": "5C.A3.DA.5E.C2.00.27.0B.79.5F.B3.57.F2.0F.02.15",
  "endToEndId": "E3030629420200808185300887639654"
}

Note que será retornado o id da transação Celcoin (transactionId) e a propriedade endToEndId (id da transação Pix fim a fim), recomendamos que esses campos sejam armazenados 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 com eles você pode fazer essas validações do seu lado.

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.

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, porém nesse cenário a Celcoin devolve o saldo retirado da conta, para ser usado em possíveis transações futuras.

🚧

Recomendamos que as informações mencionadas acima, sejam persistidas do lado da sua aplicação.

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

Recebendo status da transação 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, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

Atenção: os webhooks em Sandbox ficam indisponíveis no período entre 22:00h e 07:00h (horário de Brasília). Ao testar a API nestes horários você não receberá os webhooks.

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 igual 2, deve ser utilizado o payload informado no começo do artigo.

Caso você queira simular o pagamento rejeitado recebendo o gatilho PAYMENT com status diferente de 2, basta alterar o payload alterando o objeto creditParty da seguinte forma:

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

Exemplo de aplicação

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

Updated 4 months ago