Cobrança Única- Cartão de Crédito
A solução de cobrança única do BaaS, permite realizar cobranças via cartão de crédito, possibilitando o pagamento de um serviço ou compras pontuais. Abaixo iremos explicar como se integrar com esse módulo do BaaS.
Caso de uso:
Como Fintech quero conseguir disponibilizar as empresas do meu ecossistema a possibilidade de realizar cobranças únicas via cartão de crédito.
Nesse artigo você irá aprender sobre:
- Limitações e exceções
- Criar uma cobrança única
- Listar cobranças
- Editar cobranças
- Retentar cobranças via cartão de crédito
- Estornar cobranças via cartão de crédito
- Cancelar cobranças
- Homologação
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.
Limitações e exceções:
Esse produto realiza somente cobranças únicas via cartão de crédito
É obrigatório ter credenciado as contas BaaS que utilizarão esse produto.
Criar cobrança única
Para criar uma cobrança única via cartão de crédito é necessário realizar uma chamada na api Criar Cobrança utilizando o método POST, onde precisa ser preenchido algumas informações relacionadas a cobrança que será realizada. Os dados necessários estão no quadro "Parâmetros do Body"
Modelo de requisição:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"myId": "pay-67eec64d2d6f62.59466661",
"value": 12999,
"additionalInfo": "Lorem ipsum dolor sit amet.",
"payday": "2025-04-03",
"mainPaymentMethodId": "creditcard",
"Customer": {
"name": "Lorem ipsum dolor sit amet.",
"document": "62846017352",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"PaymentMethodCreditCard": {
"Card": {
"myId": "pay-67eec64d71cd63.91075655",
"galaxPayId": 1,
"number": "4111 1111 1111 1111",
"holder": "JOAO J J DA SILVA",
"expiresAt": "2025-04",
"cvv": "363"
},
"qtdInstallments": 12
}
'
Parâmetros do Body:
Campo | Descrição | Tipo |
---|---|---|
myId | Identificador do Cliente | String (255) |
value | Valor da cobrança em centavos | Int (11) |
additionalInfo | Informações adicionais | text |
payday | Data de Vencimento | String (date-time) |
mainPaymentMethodId | Método de Pagamento | String (30) |
customer.name | Nome do Cliente | String (255) |
customer.document | CPF OU CNPJ do cliente. Apenas números | String (14) |
customer.emails | Emails do cliente. Separe cada email por vírgula. | Array String (255) |
customer.phones | Telefones do cliente. Separe cada telefone por vírgula. | Array Int (11) |
customer.address.zipCode | CEP | String (255) |
customer.address.street | Logradouro | String (255) |
customer.address.number | Número | String (255) |
customer.address.neighborhood | Bairro | String (255) |
customer.address.city | Código de Município | String (255) |
customer.address.state | Sigla de Estado | String (255) |
customer.address.complement | Complemento | String (255) |
PaymentMethodCreditCard.number | Número do cartão. | String (30) |
PaymentMethodCreditCard.holder | Nome do portador. Não aceita caracteres especiais ou acentuação. | String (30) |
PaymentMethodCreditCard.expiresAt | Mês e ano da expiração do cartão. String contendo ano e mês de expiração do cartão. | String (7) |
PaymentMethodCreditCard.cvv | Código de segurança. | String (4) |
PaymentMethodCreditCard.qtdInstallments | Quantidade de parcelas. | Int (11) |
Modelo de retorno:
{
"type": true,
"Charge": {
"galaxPayId": 1,
"myId": "pay-67f9567aa9d8d9.87867238",
"mainPaymentMethodId": "creditcard",
"paymentLink": "https://app.celcoin.com.br/link-payment",
"value": 12999,
"additionalInfo": "Lorem ipsum dolor sit amet.",
"status": "active",
"Customer": {
"galaxPayId": 1,
"myId": "pay-67f9567abc9e85.72127015",
"name": "Lorem ipsum dolor sit amet.",
"document": "70427051223",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"Transactions": [
{
"galaxPayId": 1,
"value": 12999,
"payday": "2025-04-11",
"installment": 3,
"statusDate": "2025-04-11 14:50:50",
"status": "captured",
"datetimeLastSentToOperator": "2025-04-11 14:50:50",
"statusDescription": "Capturada na Operadora",
"reasonDenied": "Limite do cartão insuficiente.",
"authorizationCode": "pay-67f9567af20bd9.36701250",
"tid": "pay-67f9567af35231.16239082",
"AbecsReasonDenied": {
"code": "51",
"message": "Saldo/limite insuficiente"
},
"PaymentMethodCreditCard": {
"qtdInstallments": 12,
"CreditCard": {
"Card": {
"myId": "pay-67f9567b12e670.91943253",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "bin,pagseguro"
},
"expiresAt": "2025-04"
}
},
}
],
}
}
}
Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro da empresa.
Tabela descritiva dos campos retornados
Campo | Descrição | Tipo |
---|---|---|
type | Tipo do identificador. Valores possíveis para informar no campo: 1. true - Quando a cobrança for cancelada com sucesso 2. false- Quando ocorrer erro ao solicitar o cancelamento da cobrança | bool |
charge.galaxPayId | Identificador da transação na Celcoin | Int (11) |
charge.myId | Identificador do Cliente | String (255) |
charge.mainPaymentMethodId | Método de Pagamento. Valor possível: creditcard | Strint (30) |
charge.paymentLink | Link para pagamento | Strint (255) |
charge.value | Valor da cobrança em centavos | Int (11) |
charge.additionalInfo | Informações adicionais | text |
charge.status | Status da cobrança avulsa. Valores possíveis: - active: Ativa - canceled: Cancelada - closed: Encerrada - waitingPayment: Aguardando Pagamento - inactive: Inativa | String (30) |
customer.name | Nome do Cliente | String (255) |
customer.document | CPF OU CNPJ do cliente. Apenas números | String (14) |
customer.emails | Emails do cliente. Separe cada email por vírgula. | Array Int (255) |
customer.phones | Telefones do cliente. Separe cada telefone por vírgula. | Array Int (11) |
customer.address.zipCode | CEP | String (255) |
customer.address.street | Logradouro | String (255) |
customer.address.number | Número | String (255) |
customer.address.neighborhood | Bairro | String (255) |
customer.address.city | Código de Município | String (255) |
customer.address.state | Sigla de Estado | String (255) |
customer.address.complement | Complemento | String (255) |
transactions.galaxPayId | Identificador da Transação | Int (11) |
transactions.value | Valor da transação em centavos | Int (11) |
transactions.payday | Data do vencimento | Date |
transactions.installment | Parcelas | Int (1) |
transactions.statusDate | Data do Status | dateTime |
transactions.status | Status da Transação. Valores Possíveis: - notSend: Ainda não enviada para operadora de Cartão - authorized: Autorizado - captured: Capturada na Operadora de Cartão - denied: Negada na Operadora de Cartão - reversed: Estornada na Operadora de Cartão - chargeback: Estorno por chargeback | String (30) |
transactions.datetimeLastSentToOperator | Data de último envio para a operadora | dateTime |
transactions.statusDescription | Mais informações sobre o status da transação. | String (255) |
transactions.reasonDenied | Motivo de negação da transação (Quando houver). | String (255) |
transactions.authorizationCode | Código de autorização da transação na operadora. | String (255) |
transactions.tid | TID: Identificador da transação na operadora. | String (255) |
AbecsReasonDenied.code | Motivo de negação da transação (Quando houver): Código do motivo de negativa da ABECS | String (4) |
AbecsReasonDenied.message | Motivo de negação da transação (Quando houver): Mensagem do motivo de negativa da ABECS | String (255) |
PaymentMethodCreditCard.qtdInstallments | Quantidade de parcelas. | (String 11) |
PaymentMethodCreditCard.card.number | Número truncado do cartão. | String (30) |
PaymentMethodCreditCard.card.createdAt | Data de criação. | dateTime |
PaymentMethodCreditCard.card.updatedAt | Data de alteração. | dateTime |
PaymentMethodCreditCard.card.brand.id | Id da bandeira de cartão. | String (255) |
PaymentMethodCreditCard.card.brand.name | Nome da bandeira. | String (255) |
PaymentMethodCreditCard.card.brand.maxInstallment | Máximo de vezes que pode ser parcelado. | int (11) |
PaymentMethodCreditCard.card.brand.operatorIds | Operadoras que aceitam a bandeira, separados por vírgula. CardOperator.id | text |
PaymentMethodCreditCard.card.expiresAt | Mês e ano da expiração do cartão. String contendo ano e mês de expiração do cartão. YYYY-MM | String (7) |
Listar Cobranças
Para consultar uma empresa cadastrada é necessário realizar uma chamada na api Listar Cobranças utilizando o método GET, onde precisa passar os parâmetros da consulta.
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{acess_token}}' \
--header 'Content-Type: application/json' \
Modelo de retorno:
{
"totalQtdFoundInPage": 1,
"Charges": [
{
"galaxPayId": 1,
"myId": "pay-67f59150ca9c40.45124410",
"mainPaymentMethodId": "creditcard",
"additionalInfo": "Lorem ipsum dolor sit amet.",
"value": 12999,
"status": "active",
"Transactions": [
{
"galaxPayId": 1,
"myId": "pay-67f591516ca7f5.60454399",
"value": 12999,
"payday": "2025-04-08",
"additionalInfo": "Lorem ipsum dolor sit amet.",
"installment": 3,
"statusDate": "2025-04-08 18:12:49",
"datetimeLastSentToOperator": "2025-04-08 18:12:49",
"status": "captured",
"fee": 300,
"statusDescription": "Capturada na Operadora",
"tid": "pay-67f5915203df50.88935858",
"authorizationCode": "pay-67f59152111723.68682304",
"reasonDenied": "Limite do cartão insuficiente.",
"AbecsReasonDenied": {
"code": "51",
"message": "Saldo/limite insuficiente"
}
}
],
"Customer": {
"galaxPayId": 1,
"myId": "pay-67f59153638801.16393108",
"name": "Lorem ipsum dolor sit amet.",
"document": "31277264813",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"PaymentMethodCreditCard": {
"Card": {
"myId": "pay-67f591544da745.48884622",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "cielo,bin"
},
"expiresAt": "2025-04"
},
"qtdInstallments": 12
}
}
]
}
Editar Cobranças
É possível Editar uma cobrança avulsa, para editar algum dado de sua cobranças, você deve realizar uma chamada na API Editar Cobrança utilizando o método PUT
Modelo de requisição:
curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges/{chargeId}/{typeId}' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{acess_token}}' \
--header 'Content-Type: application/json' \'
--data-raw '{
"value": 1000
}
'
Parâmetros do Body:
Campo | Descrição | Tipo |
---|---|---|
chargeId | Identificador da cobrança avulsa | |
typeId | Tipo do Identificador que será utilizado como filtro. Valores Possíveis: 1. galaxPayId - Identificador da Celcoin. 2. myId - Identificador único da empresa.. |
Modelo de retorno:
{
"type": true,
"Charge": {
"galaxPayId": 1,
"myId": "pay-67f9567aa9d8d9.87867238",
"mainPaymentMethodId": "creditcard",
"paymentLink": "https://app.celcoin.com.br/link-payment",
"value": 1000,
"additionalInfo": "Lorem ipsum dolor sit amet.",
"status": "active",
"Customer": {
"galaxPayId": 1,
"myId": "pay-67f9567abc9e85.72127015",
"name": "Lorem ipsum dolor sit amet.",
"document": "70427051223",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"Transactions": [
{
"galaxPayId": 1,
"value": 12999,
"payday": "2025-04-11",
"installment": 3,
"statusDate": "2025-04-11 14:50:50",
"status": "captured",
"datetimeLastSentToOperator": "2025-04-11 14:50:50",
"statusDescription": "Capturada na Operadora",
"reasonDenied": "Limite do cartão insuficiente.",
"authorizationCode": "pay-67f9567af20bd9.36701250",
"tid": "pay-67f9567af35231.16239082",
"AbecsReasonDenied": {
"code": "51",
"message": "Saldo/limite insuficiente"
},
"PaymentMethodCreditCard": {
"qtdInstallments": 12,
"CreditCard": {
"Card": {
"myId": "pay-67f9567b12e670.91943253",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "bin,pagseguro"
},
"expiresAt": "2025-04"
}
},
}
],
}
}
}
Note que todos os dados podem ser alterados, exceto o cliente.
Você pode alterar todos os dados ou somente o campo que desejar.
Os campos retornados são os mesmos descritos no retorno da API de "Criar Cobrança", com os dados solicitados alterados para o valor que você definiu.
Retentar Cobrança
Para realizar uma nova tentativa de cobrança única via cartão de crédito, será necessário realizar uma chamada na api Retentar Cobrança utilizando o método PUT. Todas as informações necessárias para retentativa de cobrança estão no quadro "Parâmetros do Body"
Modelo de requisição:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges/{chargeId}/{typeId}/retry' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
Parâmetros do Body:
Campo | Descrição | Tipo |
---|---|---|
chargeId | Identificador da cobrança | |
typeId | Tipo do identificador. Valores possíveis para informar no campo: 1. galaxPayId - Identificador da Celcoin. 2. myId - Identificador único da empresa.. |
Modelo de retorno:
{
"Charge": {
"myId": "pay-67f95f4b2c81f6.81062699",
"galaxPayId": 1,
"mainPaymentMethodId": "creditcard",
"paymentLink": "https://app.celcoin.com.br/link-payment",
"value": 12999,
"additionalInfo": "Lorem ipsum dolor sit amet.",
"status": "active",
"Transactions": [
{
"galaxPayId": 1,
"myId": "pay-67f95f4bdd2404.18166132",
"value": 12999,
"payday": "2025-04-11",
"additionalInfo": "Lorem ipsum dolor sit amet.",
"installment": 3,
"statusDate": "2025-04-11 15:28:28",
"datetimeLastSentToOperator": "2025-04-11 15:28:28",
"status": "captured",
"fee": 300,
"statusDescription": "Capturada na Operadora",
"tid": "pay-67f95f4c749b99.71457070",
"authorizationCode": "pay-67f95f4c843de5.83487105",
"reasonDenied": "Limite do cartão insuficiente.",
"AbecsReasonDenied": {
"code": "51",
"message": "Saldo/limite insuficiente"
},
"CreditCard": {
"Card": {
"myId": "pay-67f95f4cbc3b50.14748316",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "pagseguro,cielo"
},
"expiresAt": "2025-04"
}
}
}
],
"Customer": {
"galaxPayId": 1,
"myId": "pay-67f95f4d5c3b38.61303899",
"name": "Lorem ipsum dolor sit amet.",
"document": "94575058165",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"PaymentMethodCreditCard": {
"qtdInstallments": 12,
"Card": {
"myId": "pay-67f95f4e4c8549.45172437",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "bin,pagseguro"
},
"expiresAt": "2025-04"
}
}
}
}
Estornar Cobrança no cartão
Para estornar cobrança no cartão, será necessário realizar uma chamada na api Estornar Cobrança no cartão utilizando o método PUT, onde na requisição é necessário informar o Identificador da Cobrança.
Modelo de requisição:
curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges/{chargeId}/{typeId}/reverse' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"valueToReverse": 1000
}
'
O campo valueToReverse é opcional. Caso não informado, será considerado o valor total da cobrança
Tabela descritiva dos campos
Campo | Descrição | Tipo |
---|---|---|
chargeId | Identificador da cobrança | |
typeId | Tipo do identificador. Valores possíveis para informar no campo: 1. galaxPayId - Identificador da Celcoin. 2. myId - Identificador único da empresa.. | |
valueToReverse | Valora ser estornado |
Modelo de retorno:
{
"Charge": {
"galaxPayId": 1,
"myId": "pay-67f95fd1e9cfe8.93565161",
"mainPaymentMethodId": "creditcard",
"paymentLink": "https://app.celcoin.com.br/link-payment",
"value": 12999,
"additionalInfo": "Lorem ipsum dolor sit amet.",
"status": "active",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Transactions": [
{
"galaxPayId": 1,
"myId": "pay-67f95fd20b78c5.61798477",
"value": 12999,
"payday": "2025-04-11",
"additionalInfo": "Lorem ipsum dolor sit amet.",
"installment": 3,
"statusDate": "2025-04-11 15:30:42",
"datetimeLastSentToOperator": "2025-04-11 15:30:42",
"status": "captured",
"createdAt": "2020-06-02 10:10:00",
"fee": 300,
"statusDescription": "Capturada na Operadora",
"tid": "pay-67f95fd22382c1.40673689",
"authorizationCode": "pay-67f95fd224d531.00132717",
"CreditCard": {
"Card": {
"myId": "pay-67f95fd2260c18.50206926",
"galaxPayId": 1,
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "pagseguro,bin"
},
"expiresAt": "2025-04"
}
}
}
],
"Customer": {
"galaxPayId": 1,
"myId": "pay-67f95fd2376ba3.41318868",
"name": "Lorem ipsum dolor sit amet.",
"document": "65587323510",
"emails": [
"[email protected]",
"[email protected]"
],
"phones": [
3140201512,
31983890110
],
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Address": {
"zipCode": "30411330",
"street": "Rua platina",
"number": "1330",
"complement": "2º andar",
"neighborhood": "Prado",
"city": "Belo Horizonte",
"state": "MG"
}
},
"PaymentMethodCreditCard": {
"Card": {
"galaxPayId": 1,
"myId": "pay-67f95fd25851c3.42861518",
"number": "5451*********1515",
"createdAt": "2020-06-02 10:10:00",
"updatedAt": "2020-06-02 10:10:00",
"Brand": {
"id": "mastercard",
"name": "MasterCard",
"maxInstallment": 12,
"operatorIds": "bin,rede"
},
"expiresAt": "2025-04"
}
}
}
}
Cancelar uma Cobrança Avulsa
Para cancelar uma cobrança avulsa, será necessário realizar uma chamada na api Cancelar Cobrança Avulsa utilizando o método DELETE, onde precisa ser preenchido algumas informações relacionadas a cobrança realizada. Todas as informações necessárias para cancelar uma cobrança estão no quadro "Parâmetros do Body"
Modelo de requisição:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges/{chargeId}/{typeId}' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
Parâmetros do Body:
Campo | Descrição | Tipo |
---|---|---|
chargeId | Identificador da cobrança | |
typeId | Tipo do identificador. Valores possíveis para informar no campo: 1. galaxPayId - Identificador da Celcoin. 2. myId - Identificador único da empresa.. |
Modelo de retorno:
{
"type": true
}
Tabela descritiva dos campos retornados
Campo | Descrição | Tipo |
---|---|---|
type | Tipo do identificador. Valores possíveis para informar no campo: 1. true - Quando a cobrança for cancelada com sucesso 2. false- Quando ocorrer erro ao solicitar o cancelamento da cobrança | Bool |
Tabela de Erros
Os principais erros de negócio mapeados nas APIs acima estão disponíveis nesse link
Homologação
As instruções para realizar a homologação deste produto estão centralizadas neste link
Updated 2 days ago