Integração Cartão de Crédito - Documentação da API FireBanking

Visão Geral

O processamento de cartão de crédito é ideal para e-commerce, marketplaces e aplicações que precisam de confirmação instantânea, parcelamento ou assinaturas recorrentes.

Pagamento Simples

Processe pagamentos únicos com captura imediata

Pré-autorização

Reserve limite sem capturar - ideal para reservas

Parcelamento

Aceite pagamentos parcelados em até 12x

Tokenização

Salve dados de cartão para pagamentos futuros

Fluxo de Integração

Configuração Inicial

Configure suas credenciais de API no ambiente de sandbox

Primeiro Pagamento

Processe uma transação de teste com cartão válido

Tratamento de Respostas

Implemente lógica para status de aprovação/negação

Webhooks

Configure notificações para mudanças de status

Ambiente de Produção

Migre para produção com credenciais reais

Configuração de Credenciais

Ambientes Disponíveis

Sandbox (Testes)

Base URL: https://api-gateway.firebanking.dev/credit-card/v1Use para desenvolvimento e testes

Produção

Base URL: https://api-gateway.firebanking.com.br/credit-card/v1Use apenas com dados reais validados

Obtendo suas Chaves

Acesse o Dashboard FireBanking
Vá em API & Webhooks → Chaves de API
Copie sua chave de Sandbox (formato: a9b484fc-9...)

Exemplo de Chave de Teste

a9b484fc-90a6-4255-9394-e3c1ca0633b9

Seu Primeiro Pagamento

Estrutura da Requisição

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "purchaseValue": 100,
    "installments": 1,
    "externalId": "card-payment-001",
    "purchaseTitle": "Pagamento com Cartão",
    "payment": {
      "chargeType": "FEE_TO_CUSTOMER",
      "capture": true,
      "card": {
        "name": "JOSE DAS NEVES TEST",
        "number": "5383638854408981",
        "expiration": "12/2024",
        "securityCode": "220"
      }
    },
    "buyer": {
      "name": "João da Silva Teste",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "Centro",
        "street": "Rua das Flores, 123",
        "zipCode": "01000000",
        "number": "123"
      }
    }
  }'

Resposta de Sucesso

Exemplo de Resposta Aprovada

{
  "transactionId": "txn_1234567890",
  "externalId": "card-payment-001",
  "status": "APPROVED",
  "purchaseValue": 100,
  "installments": 1,
  "authorizationCode": "123456",
  "nsu": "000001",
  "tid": "10101010101010101010",
  "brand": "mastercard",
  "lastFourDigits": "8981",
  "created_at": "2024-01-15T10:30:00Z",
  "captured_at": "2024-01-15T10:30:05Z"
}

Parâmetros Importantes

Valores Monetários

Importante: Todos os valores são em reais (BRL)

R$ 1,00 = 1
R$ 10,00 = 10
R$ 100,00 = 100

Tipos de Cobrança

chargeType	Descrição	Quem Paga a Taxa
`FEE_TO_CUSTOMER`	Taxa cobrada do cliente	Cliente
`FEE_TO_SELLER`	Taxa cobrada do vendedor	Vendedor

Captura Imediata vs Pré-autorização

Captura Imediata (capture: true)

Uso: E-commerce tradicional, pagamentos instantâneos
Comportamento: Valor é cobrado imediatamente do cartão
Cancelamento: Possível via estorno até 120 dias
Ideal para: Produtos digitais, entrega imediata

Pré-autorização (capture: false)

Uso: Hotéis, aluguel de carros, reservas
Comportamento: Valor é reservado no limite, mas não cobrado
Captura posterior: Necessária em até 5 dias
Cancelamento: Libera o limite sem cobrança
Ideal para: Serviços com confirmação posterior

Cartões de Teste

Use estes cartões específicos no ambiente de sandbox:

Cartões Aprovados

{
  "mastercard_aprovado": {
    "number": "5383638854408981",
    "expiration": "12/2024",
    "securityCode": "220",
    "name": "JOSE DAS NEVES TEST"
  },
  "visa_aprovado": {
    "number": "4000000000000010",
    "expiration": "12/2024",
    "securityCode": "123",
    "name": "MARIA SILVA TEST"
  }
}

Cartões Negados

{
  "visa_negado": {
    "number": "4000000000000002",
    "expiration": "12/2024",
    "securityCode": "123",
    "error": "Cartão sempre negado - para testar fluxo de erro"
  }
}

Tokenização

Salve dados de cartão de forma segura para pagamentos futuros:

Criando um Token

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment/token" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "card": {
      "name": "JOSE DAS NEVES TEST",
      "number": "5383638854408981",
      "expiration": "12/2024",
      "securityCode": "220"
    },
    "buyer": {
      "document": "11144477735",
      "name": "João da Silva"
    }
  }'

Resposta do Token

{
  "token": "fbk_token_abc123def456",
  "lastFourDigits": "8981",
  "brand": "mastercard",
  "expiresAt": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Status e Consultas

Status Possíveis

Status	Descrição	Ação Recomendada
`PROCESSING`	Processando autorização	Aguardar webhook
`APPROVED`	Pagamento aprovado	Liberar produto
`DENIED`	Pagamento negado	Ofertar outro método
`AUTHORIZED`	Pré-autorizado	Capturar em até 5 dias
`CANCELLED`	Cancelado/estornado	Confirmar cancelamento

Consultando Status

curl -X GET "https://api-gateway.firebanking.dev/credit-card/v1/payment/{transactionId}" \\
  -H "x-api-key: SUA_CHAVE_DE_API"

Captura Posterior

Para pagamentos pré-autorizados, capture o valor:

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment/{transactionId}/capture" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "amount": 100
  }'

Webhooks para Cartão

Configure endpoints para receber notificações:

Eventos Disponíveis

Evento	Descrição
`payment.authorized`	Pagamento pré-autorizado
`payment.captured`	Pagamento capturado
`payment.denied`	Pagamento negado
`payment.cancelled`	Pagamento cancelado
`payment.refunded`	Pagamento estornado

Payload do Webhook

Exemplo de Webhook

{
  "event": "payment.captured",
  "transaction_id": "txn_1234567890",
  "external_id": "card-payment-001",
  "timestamp": "2024-01-15T10:30:05Z",
  "data": {
    "transactionId": "txn_1234567890",
    "status": "APPROVED",
    "purchaseValue": 100,
    "installments": 1,
    "brand": "mastercard",
    "lastFourDigits": "8981"
  }
}

Tratamento de Erros

Erros Comuns

Cartão Negado (400)

{
  "error": {
    "code": "CARD_DECLINED",
    "message": "Cartão recusado pelo banco emissor",
    "details": "Saldo insuficiente ou cartão bloqueado"
  }
}

Solução: Oferecer método alternativo ou solicitar outro cartão

Dados Inválidos (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados de cartão inválidos",
    "fields": ["card.number", "card.expiration"]
  }
}

Solução: Validar dados antes do envio

Limite Excedido (403)

{
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Valor excede limite permitido",
    "limit": 5000
  }
}

Solução: Reduzir valor ou usar PIX/boleto

Assinaturas Recorrentes

Para cobranças automáticas mensais ou anuais:

Criando Assinatura

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/subscription" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "basicValue": {
      "type": "MONTHLY",
      "valuePerMonth": 29.90
    },
    "payment": {
      "method": "CREDIT_CARD",
      "cardToken": "fbk_token_abc123def456"
    },
    "buyer": {
      "name": "João da Silva",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55"
    },
    "description": "Assinatura Premium",
    "startDate": "2024-02-01"
  }'

Migração para Produção

Validar Testes

Confirme que todos os cenários funcionam em sandbox

Obter Credenciais de Produção

Solicite chaves de produção via dashboard

Atualizar URLs

Mude para api-gateway.firebanking.com.br

Implementar Logs

Configure logging para monitoramento

Monitorar Transações

Acompanhe as primeiras transações reais

Checklist de Produção

Webhooks configurados e testados
Tratamento de erros implementado
Validação de dados no frontend
Logs de auditoria configurados
Monitoramento de uptime ativo
Backup de credenciais seguro

Próximos Passos

Webhooks Avançados

Configure notificações para todos os eventos

Referência da API

Documentação completa dos endpoints

Integração PIX

Adicione PIX como método alternativo

Melhores Práticas

Otimize sua integração para produção

🎉 Parabéns! Você agora tem uma integração completa de cartão de crédito com a FireBanking.

Início

Conceitos Principais

Guias de Integração

​Visão Geral

Pagamento Simples

Pré-autorização

Parcelamento

Tokenização

​Fluxo de Integração

​Configuração de Credenciais

​Ambientes Disponíveis

Sandbox (Testes)

Produção

​Obtendo suas Chaves

​Seu Primeiro Pagamento

​Estrutura da Requisição

​Resposta de Sucesso

​Parâmetros Importantes

​Valores Monetários

​Tipos de Cobrança

​Captura Imediata vs Pré-autorização

​Cartões de Teste

​Cartões Aprovados

​Cartões Negados

​Tokenização

​Criando um Token

​Resposta do Token

​Status e Consultas

​Status Possíveis

​Consultando Status

​Captura Posterior

​Webhooks para Cartão

​Eventos Disponíveis

​Payload do Webhook

​Tratamento de Erros

​Erros Comuns

​Assinaturas Recorrentes

​Criando Assinatura

​Migração para Produção

​Checklist de Produção

​Próximos Passos

Webhooks Avançados

Referência da API

Integração PIX

Melhores Práticas

Visão Geral

Fluxo de Integração

Configuração de Credenciais

Ambientes Disponíveis

Obtendo suas Chaves

Seu Primeiro Pagamento

Estrutura da Requisição

Resposta de Sucesso

Parâmetros Importantes

Valores Monetários

Tipos de Cobrança

Captura Imediata vs Pré-autorização

Cartões de Teste

Cartões Aprovados

Cartões Negados

Tokenização

Criando um Token

Resposta do Token

Status e Consultas

Status Possíveis

Consultando Status

Captura Posterior

Webhooks para Cartão

Eventos Disponíveis

Payload do Webhook

Tratamento de Erros

Erros Comuns

Assinaturas Recorrentes

Criando Assinatura

Migração para Produção

Checklist de Produção

Próximos Passos