Antecipação de Cartão

A API de Recebíveis de Cartão de Crédito permite que o Parceiro integre a jornada de antecipações em sua plataforma e facilite a consulta e contratação do serviço.

Casos de Uso

  • Realizar cotações sobre os recebíveis de cartão de crédito disponíveis para antecipação
  • Consultar a agenda de recebíveis de cartão.
  • Contratar a antecipação de recebíveis de cartão de crédito.

Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Recebíveis de Cartão de Crédito deve ser gerado usando o Access Token.

EscopoDescrição
brn:btg:empresas:receivables:credit-cardPermite a consulta dos dados e criação de uma antecipação de recebível
brn:btg:empresas:receivables:credit-card.readonlyPermite consulta do dados de uma antecipação de recebível

Recursos Disponíveis

Com a API de Recebíveis de Cartão de Crédito, você pode:

  • Consultar limite de antecipação disponível e total para um estabelecimento comercial;
  • Consultar recebíveis de cartão de crédito de um estabelecimento comercial disponíveis para antecipação;
  • Antecipar uma lista recebíveis de cartão de crédito de um estabelecimento comercial;
  • Consultar um resumo dos recebíveis de cartão de crédito em atraso de um estabelecimento comercial;
  • Acompanhar a evolução das antecipações desde o momento da solicitação até o momento em que são quitadas.

Os recursos da API de Recebíveis de Cartão de Crédito estão disponíveis no API Reference.

Antecipação de Recebíveis de Cartão de Crédito

Para utilizar o potencial completo dessa API de antecipações vale visitar alguns conceitos sobre o Mercado de Antecipações de Cartão de Crédito Brasileiro.

Mercado de Antecipações de Cartão de Crédito Brasileiro

Três entidades colaboram para que a antecipação ocorra de forma segura:

  • Credenciadora -> Maquininha de cartão de crédito;
  • Registradora -> Instituição que registra todas as operações feitas com os recebíveis de cartão de crédito;
  • Banco financiador da antecipação -> Nesse caso, o BTG Pactual.

Todas as vendas passadas pela maquininha de cartão de crédito em um estabelecimento comercial são enviadas para a Credenciadora, essa por sua vez, agrupa essas vendas por suas datas de vencimento, cnpj do estabelecimento comercial, cnpj da própria credenciadora e pela bandeira do cartão de crédito, gerando assim as unidades de recebíveis que podem ser antecipadas.

As Credenciadoras enviam suas unidades de recebíveis para a Registradora, que por sua vez, repassa essas unidades de recebíveis para todas as instituições financeiras que realizam operações com recebíveis de cartão de crédito, e é assim que, os recebíveis chegam até o BTG Pactual.

Acompanhamento de uma antecipação de recebíveis de cartão de crédito

A jornada de antecipação contempla os seguintes passos:

  1. O recurso de “Consulta de limite” deverá ser utilizado para se ter o conhecimento do valor disponível de antecipação para o cliente. Não se deve permitir que o cliente escolha recebíveis cuja soma do campo “maturityAmount” seja maior que o limite disponível. Se uma operação for enviada ultrapassando esse valor, ela será rejeitada e cancelada.
  2. O recurso de “Listagem de recebíveis” deverá ser utilizado para se ter o conhecimento dos recebíveis disponíveis para o cliente antecipar naquele momento, essa lista varia ao longo do dia então é importante atualizá-la antes da solicitação da antecipação. A lista de recebíveis obtido é valida somente no dia em que é gerada, portanto, deve ser atualizada diariamente.
  3. O recurso de “Antecipação de recebíveis” deverá ser utilizado para solicitar uma nova operação passando uma lista de recebíveis e uma conta de desembolso, o cliente precisa ser titular dessa conta e o recebível deve ter data de vencimento entre 5 e 365 dias corridos. Se o mesmo recebível for enviado em 2 operações diferentes, uma das operações será recusada e cancelada, a outra seguirá o fluxo. Se as contas de desembolso ou liquidação da antecipação não estiverem previamente cadastradas e ativas a operação será recusada e cancelada.
  4. Uma vez que todas as validações dos passos 1- e 3- forem concluídas, os recebíveis solicitados serão enviados para registro na Registradora. Pode acontecer de a Registradora registrar um valor menor que o solicitado, vide a seção “Registro de recebíveis” para detalhes, o valor registrado pela Registradora será o valor de referência para a antecipação, o que chamamos de “registeredAmount”.
  5. Com o valor registrado, o BTG inicia o processo de desembolso e envia o valor registrado subtraído das taxas da operação, o que chamamos de “disbursementAmount”, para a conta de desembolso escolhida do cliente.
  6. Com o recurso de “Consulta de operações” será possível saber os estados dos recebíveis e seus valores em tempo real. Há a alternativa de se realizar a inscrição para o recebimento do evento webhook “receivables-credit-card.update”, esse evento é enviado todo vez que um recebível sofre uma alteração de valor ou estado.
  7. No vencimento dos recebíveis da operação, a credenciadora enviará ao BTG Pactual o valor registrado, e os recebíveis serão marcados como “Settled”, encerrando a Jornada de antecipação. Pode ocorrer de a credenciadora enviar um valor menor que o valor registrado, vide a seção “Chargeback de recebíveis” para detalhes.
  8. O horário possível para envio de antecipações é das 9h às 16h30, se uma antecipação for enviada ao BTG Pactual fora desse horário, ela será recusada e cancelada.

Registro de recebíveis

Como os recebíveis estão livres para serem negociados por outras instituições financeiras e por outros produtos financeiros além do produto de antecipação do BTG, o valor disponível do recebível pode ser parcialmente ou totalmente consumido em outra instituição ou por outro produto.
Nesse caso, a Registradora não aprovará o valor total solicitado e registrará o valor que ainda não foi operado por outra instituição, ou outro produto, até aquele momento, chamamos esse valor de “registeredAmount”. Esse valor registrado se torna a referência para o valor de desembolso da Jornada de antecipação.

Credenciadoras Homologadas

Operamos com as seguintes credênciadoras:

  • CIELO S.A. 01027058000191
  • REDECARD S/A 01425787000104
  • GETNET 10440482000154

Bandeiras

Operamos com as seguintes bandeiras:

  • Visa
  • Mastercard
  • Elo
  • AmericanExpress
  • Hipercard

Chargeback de recebíveis

Em alguns casos, após a antecipação de um recebível uma venda que o compõe pode ser cancelada pelo consumidor, quando isso ocorre, no momento do vencimento desse recebível a credenciadora não enviará o valor dessa venda para o BTG. Essa venda cancelada é chamada de chargeback.
No dia do vencimento de um recebível que teve chargeback é necessário existir saldo na conta do cliente para quitar o valor do chargeback, pois caso contrário, o cliente passará a ter um saldo devedor com o BTG no dia seguinte, sendo cobrado multas e juros.
Através do recurso “Resumo do saldo devedor” é possível acompanhar um resumo desses valores de chargeback e pagamentos ainda não enviados pela credenciadora através dos seguintes campos:

  • “overdueReceivablesUnpaidAmount” -> Chargebacks de recebíveis vencidos que ainda não foram quitados somados com seus juros e multas de atraso
  • “dueTodayReceivablesUnpaidAmount” -> Chargebacks de recebíveis que vencem no dia de hoje e ainda não possuem juros e multas de atraso

Há a alternativa de se realizar a inscrição para o recebimento do evento webhook “receivables-credit-card.balance-summary”, esse evento é enviado às 11h todos os dias com os mesmos campos do recurso “Resumo do saldo devedor”.

Máquina de estados do Recebível

Domínio de Erros

A tabela abaixo contém os códigos de erros que a API devolve, quando falha em operar, e suas respectivas descrições indicando o causador da falha.

CódigoDescrição
OPRCC000Erro inesperado
OPRCC001Empresa não cadastrada
OPRCC002Conta de Desembolso não cadastrada
OPRCC003Nenhum recebível solicitado foi encontrado
OPRCC004Recebíveis solicitados não pertencem a empresa
OPRCC005Recebíveis solicitados não estão disponíveis para antecipar
OPRCC006Valor solicitado maior que o valor disponível para antecipar
OPRCC007Valor solicitado menor que o valor mínimo possível
OPRCC008Limite não cadastrado para a empresa
OPRCC009Operação fora da grade horária
OPRCC010Empresa não pode operar por não pagar o Saldo Devedor
OPRCC011Paginador com valores inconsistentes

Eventos

Eventos
A API de Recebíveis de Cartão de Crédito possui dois eventos disponíveis para inscrição:

  1. Evento webhook para comunicar em tempo real a evolução dos estados e valores dos recebíveis operados:

receivables-credit-card.update

{  
  "receivable": {  
    "receivableId": 20,  
    "payerId": "01027058000191",  
    "payeeId": "37297902000141",  
    "maturityDate": "2024-02-15",  
    "brand": "Visa",  
    "maturityAmount": 50000.55,  
    "maximumDisbursementAmount": 40000.44,  
    "status": "InDisbursement"  
  },  
  "registeredAmount": 30500.35,  
  "disbursementAmount": 30000.33  
}
  1. Evento webhook para comunicar o saldo devedor do cliente, é enviado todos os dias às 11h para todos os clientes que operaram:
    receivables-credit-card.balance-summary
{  
  “companyId”: “37297902000141”,  
  "overdueReceivablesUnpaidAmount": 200.12,  
  "dueTodayReceivablesUnpaidAmount": 2000.12  
}