Visão Geral do Módulo de Cartão de Crédito

O módulo de cartão de crédito da Fire Banking foi concebido para operar de forma dedicada, com foco exclusivo em transações de cartão. Em vez de acoplar diferentes meios de pagamento dentro do mesmo fluxo, este módulo trata apenas cartão e expõe uma integração simples, direta e previsível para o seu time.

Integração com contrato único

A integração é direta: a cobrança é solicitada por meio de um único contrato (payload JSON) que reúne todas as informações essenciais da transação. Não é necessário criar previamente um comprador para depois vincular uma cobrança; a própria requisição já contempla o que é preciso. Isso reduz etapas, complexidade e chance de inconsistência entre entidades auxiliares.

Autorização, captura e cancelamento

O fluxo de cobrança admite duas estratégias: pré-autorização (reserva de limite) e captura imediata (cobrança efetiva). Em pré-autorização, a transação fica pendente até que você decida capturá-la; se nada for feito, ela é cancelada automaticamente após 7 dias. Em captura imediata, a cobrança é confirmada no ato. Importante: cancelamento só se aplica a transações ainda não capturadas; uma vez capturada (paga), a reversão passa a ser via reembolso.

[POST] /payment

Gerar uma cobrança única à vista ou parcelada

[POST] :id/capture

Saldos e repasse entre módulos

O saldo de cartão é separado do saldo BaaS (que abrange Pix e Boleto), mas os módulos se comunicam. Após a aprovação e pagamento, o valor é liberado e repassado para a conta Pix em até D+2, tornando-se disponível para movimentações sem conciliações paralelas.

Parcelamento e políticas de taxa

A cobrança pode ser à vista ou parcelada. Em parcelado, é necessário definir quem assume as taxas: o vendedor (sem juros para o cliente) ou o cliente final (juros repassados). Em cobrança à vista, a taxa é do vendedor por padrão. O limite de parcelas pode chegar a 24, mas pode variar conforme o perfil da conta.

Webhooks e direcionamento por transação

Eventos do fluxo de cartão são enviados por webhook. Existe uma configuração global por módulo, mas cada transação pode informar um callbackUrl específico, que prevalece sobre a URL padrão. Isso permite direcionar notificações por produto, ambiente ou contexto operacional, sem alterar a configuração global.

[POST] /business/webhook

Atualizar a URL dos seus Webhooks

Identificação e endereços

Cada transação deve possuir um identificador interno da Fire e um identificador externo do seu sistema externalId), utilizado ao longo de todo o ciclo de vida para consultas e reconciliações. O endereço principal do comprador é obrigatório; o endereço de cobrança é opcional e, se omitido, herda o endereço principal.

Operações de apoio

Além da criação de cobranças, estão disponíveis operações para captura de pré-autorizações, reembolso de transações pagas mediante saldo disponível, listagem e consulta por diferentes chaves de referência.

[POST] /payment/:id/refund

Solicita o reembolso de uma cobrança

[GET] /payment

Lista todas as cobranças geradas

[GET] /payment/:id

Solicita os detalhes de uma cobrança

Âmbito e limitações atuais

O módulo opera apenas com transações elegíveis à antecipação. Operações que não suportam antecipação não estão contempladas nesta versão, o que mantém a previsibilidade do fluxo de liquidez e do repasse.

Acesso, habilitação e segurança

O acesso exige o cabeçalho x-api-key, com o módulo de cartão habilitado na sua conta. Recomenda-se a ativação de whitelist de IP, a gestão cuidadosa do ciclo de vida da chave e o uso das demais medidas disponíveis no dashboard.

Segurança e Controle de Acesso

Conjunto de camadas de defesa e recomendações para uso seguro da API