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	Carteira para associar o token
card_number	string	Sim	PAN do cartão (ex.: 4024007153763191)
card_name	string	Sim	Nome do titular impresso no cartão
card_expiry_month	string	Sim	Mês de validade MM (ex.: 12)
card_expiry_year	string	Sim	Ano de validade YYYY (ex.: 2030)
card_cvv	string	Sim	Código de verificação do cartão
payer_tax_id	string	Sim	Documento do titular (CPF, RFC, RUT, CUIT)
payer_email	string	Não	E-mail do titular para notificações

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	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

---

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

curl -s -X POST https://core-manager.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",
    "card_number": "4024007153763191",
    "card_name": "MARIA SILVA",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "payer_tax_id": "123.456.789-09",
    "payer_email": "maria@example.com"
  }'

Python

import requests
import os

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

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/tokenization/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "card_number": "4024007153763191",
            "card_name": "MARIA SILVA",
            "card_expiry_month": "12",
            "card_expiry_year": "2030",
            "card_cvv": "123",
            "payer_tax_id": "123.456.789-09",
            "payer_email": "maria@example.com",
        },
        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}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.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",
      card_number: "4024007153763191",
      card_name: "MARIA SILVA",
      card_expiry_month: "12",
      card_expiry_year: "2030",
      card_cvv: "123",
      payer_tax_id: "123.456.789-09",
      payer_email: "maria@example.com",
    }),
  });

  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);
}

---

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.