Pular para o conteúdo principal
POST
/
credit-card
/
v1
/
payment
/
token
Criar Token de Cartão
curl --request POST \
  --url https://api-gateway.firebanking.dev/credit-card/v1/payment/token \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "card": {
    "name": "JOSE DAS NEVES TEST",
    "number": "5383638854408981",
    "expiration": "12/24",
    "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",
      "zipCode": "01000000",
      "number": "220",
      "complement": "Apto 45"
    }
  },
  "checkZeroDollar": false
}
'
{
  "cardToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "maskedCardNumber": "****-****-****-1111",
  "expirationDate": "12/24",
  "createdAt": "2023-11-07T05:31:56Z"
}
Criar um token seguro e reutilizável para um cartão de crédito. Isso permite armazenar informações do cartão com segurança e usá-lo para pagamentos futuros sem lidar com dados sensíveis do cartão.

​
Benefícios da Tokenização de Cartão

Segurança

Reduzir escopo de conformidade PCI não armazenando dados do cartão

Conveniência

Permitir checkout mais rápido para clientes recorrentes

Assinaturas

Essencial para cobrança recorrente e assinaturas

Conformidade

Atender padrões de segurança da indústria

​
Exemplo de Requisição

Exemplo de Requisição
{
  "card": {
    "name": "Maria Santos",
    "number": "5383638854408981",
    "expiration": "12/2024",
    "securityCode": "220"
  },
  "buyer": {
    "name": "Maria Santos",
    "document": "98765432109",
    "email": "[email protected]",
    "phone": "11888888888",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "RJ",
      "city": "Rio de Janeiro",
      "district": "Copacabana",
      "street": "Avenida Atlântica",
      "zipCode": "22070000",
      "number": "456"
    }
  },
  "checkZeroDollar": false
}

​
Exemplo de Resposta

Resposta
{
  "cardToken": "550e8400-e29b-41d4-a716-446655440000",
  "maskedCardNumber": "****-****-****-4444",
  "expirationDate": "06/26",
  "cardBrand": "mastercard",
  "buyerUuid": "buyer-uuid-67890",
  "createdAt": "2024-01-15T14:30:00Z"
}

​
Verificação de Zero Reais

​
checkZeroDollar
boolean
default:"false"
Realizar uma autorização de R$ 0,00 para validar o cartão
Quando habilitado, esse recurso:
  • Valida informações do cartão com o banco emissor
  • Verifica se o cartão está ativo e válido
  • Verifica endereço de cobrança (se fornecido)
  • Reverte imediatamente a autorização
Verificações de zero reais podem aparecer como transações pendentes nos extratos dos clientes por 1-3 dias úteis, mesmo que nenhum dinheiro seja cobrado.

​
Usando Tokens de Cartão

Uma vez criado, use o token em requisições de pagamento:
Exemplo de Pagamento com Token
{
  "purchaseValue": 5000,
  "installments": 1,
  "payment": {
    "chargeType": "FEE_TO_CUSTOMER",
    "cardToken": {
      "cardToken": "550e8400-e29b-41d4-a716-446655440000",
      "cvv": "456"
    }
  },
  "buyerUuid": "buyer-uuid-67890"
}
Tokens de cartão estão vinculados ao comprador que os criou. Você deve fornecer o buyerUuid ao usar um token para pagamentos.

​
Segurança do Token

  • Único: Cada token é único e não pode ser engenharia reversa
  • Escopo: Tokens funcionam apenas com o comprador associado
  • Expirante: Tokens expiram quando o cartão subjacente expira
  • Criptografado: Todos os dados de token são criptografados em repouso

​
Melhores Práticas

  1. Armazene UUID do comprador - Sempre armazene o UUID do comprador com o token
  2. Gerencie expiração - Monitore expiração do token e solicite atualizações de cartão
  3. CVV para pagamentos - Sempre exija CVV ao usar tokens para pagamentos
  4. Consentimento do cliente - Certifique-se de que os clientes consintam com a tokenização do cartão
  5. Limpeza regular - Remova tokens não utilizados para manter a segurança

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Body

application/json
​
card
object
required
​
buyer
object
required
​
checkZeroDollar
boolean
default:false

Se deve realizar verificação de dólar zero

Response

Token de cartão criado com sucesso

​
cardToken
string<uuid>

Token do cartão gerado

​
maskedCardNumber
string

Número do cartão mascarado

Example:

"****-****-****-1111"

​
expirationDate
string

Data de expiração do cartão

Example:

"12/24"

​
createdAt
string<date-time>

Timestamp de criação do token