Tokenizar cartão

POST/api/v1/bank/wallet/tokenization/Bearer Token

Cabeçalhos da requisição

Cabeçalho	Valor	Obrigatório
`Authorization`	`Bearer {A55_ACCESS_TOKEN}`	Sim
`Content-Type`	`application/json`	Sim
`Idempotency-Key`	UUID v4	Recomendado

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`wallet_uuid`	string (UUID)	Sim	ID da carteira
`merchant_uuid`	string (UUID)	Sim	ID do merchant
`card`	object	Sim	Informações do cartão a tokenizar
`card.holder_name`	string	Sim	Nome do titular como impresso no cartão
`card.number`	string	Sim	Número do cartão (PAN), 13–16 dígitos
`card.expiry_month`	string	Sim	Mês de validade (`01`–`12`), 2 dígitos
`card.expiry_year`	string	Sim	Ano de validade (`YYYY`), 4 dígitos
`card.cvv`	string	Sim	Código de segurança (CVV), 3 dígitos

Tratamento de dados do cartão

Ao enviar dados brutos do cartão, a A55 os criptografa e armazena em cofre imediatamente após o recebimento. Se preferir não manipular dados de cartão no seu backend, use o SDK A55Pay ou a Página de Checkout.

Campos da resposta

Campo	Tipo	Descrição
`token_uuid`	string (UUID)	Identificador de token reutilizável para cobranças futuras
`card_brand`	string	Bandeira do cartão (`visa`, `mastercard`, `amex`, `elo`)
`card_last_four`	string	Últimos 4 dígitos do cartão
`card_expiry_month`	string	Mês de validade
`card_expiry_year`	string	Ano de validade
`status`	string	`active` em caso de sucesso
`created_at`	string	Timestamp de criação ISO 8601

Exemplo de resposta

{
  "token_uuid": "d7641ce9-9411-432c-bb25-240ce7dd3cef",
  "card_brand": "visa",
  "card_last_four": "3191",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "status": "active",
  "created_at": "2026-03-21T14:30:00-03:00"
}

Códigos de status HTTP

Status	Descrição
200	Cartão tokenizado com sucesso
400	Dados do cartão inválidos ou campos obrigatórios ausentes
401	Token Bearer inválido ou expirado
403	Permissões insuficientes para esta carteira
404	Carteira não encontrada
409	Cartão já tokenizado para esta carteira
422	Validação do cartão falhou (número inválido, expirado)
429	Limite de requisições excedido
500	Erro interno do servidor — tente novamente com backoff exponencial

Exemplos de código

cURL
Python
Node.js

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/tokenization/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 880e8400-e29b-41d4-a716-446655440003" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
    "card": {
      "holder_name": "MARIA SILVA",
      "number": "4024007153763191",
      "expiry_month": "12",
      "expiry_year": "2030",
      "cvv": "123"
    }
  }'

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://sandbox.api.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/tokenization/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
            "card": {
                "holder_name": "MARIA SILVA",
                "number": "4024007153763191",
                "expiry_month": "12",
                "expiry_year": "2030",
                "cvv": "123",
            },
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "880e8400-e29b-41d4-a716-446655440003",
        },
    )
    response.raise_for_status()
    result = response.json()
    print(f"Token: {result['token_uuid']} — Brand: {result['card_brand']}")
    print(f"Card: ****{result['card_last_four']} expires {result['card_expiry_month']}/{result['card_expiry_year']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/tokenization/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "880e8400-e29b-41d4-a716-446655440003",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_uuid: "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
      card: {
        holder_name: "MARIA SILVA",
        number: "4024007153763191",
        expiry_month: "12",
        expiry_year: "2030",
        cvv: "123",
      },
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const result = await response.json();
  console.log(`Token: ${result.token_uuid} — Brand: ${result.card_brand}`);
  console.log(`Card: ****${result.card_last_four} expires ${result.card_expiry_month}/${result.card_expiry_year}`);
} catch (error) {
  console.error("Tokenization failed:", error.message);
}

Simulação em sandbox

Em sandbox, os resultados de tokenização seguem as mesmas regras de cartões de teste das cobranças. Um enrollment bem-sucedido retorna HTTP 200 com token_uuid; falhas retornam HTTP 400 com card_tokenization_failed.

Requer tokenization_enabled: true no merchant. Entre em contato com seu account manager para habilitar.

Exemplo de resposta de erro

{
  "status": "error",
  "message": [
    {
      "code": "INVALID_CARD_NUMBER",
      "source": "validation",
      "description": "Card number failed Luhn check"
    }
  ]
}

Criar cobrança →Use o token_uuid para cobrar o cartão posteriormente.Consulta de BIN →Verifique a bandeira e o tipo do cartão antes de tokenizar.Zero-auth →Valide um cartão sem efetuar cobrança.

Cabeçalhos da requisição​

Corpo da requisição​

Campos da resposta​

Exemplo de resposta​

Códigos de status HTTP​

Exemplos de código​

Simulação em sandbox​

Exemplo de resposta de erro​