Tokenize card

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

---

Request headers

Header	Value	Required
Authorization	Bearer {A55_ACCESS_TOKEN}	Yes
Content-Type	application/json	Yes
Idempotency-Key	UUID v4	Recommended

Request body

Field	Type	Required	Description
wallet_uuid	string (UUID)	Yes	Wallet to associate the token with
card_number	string	Yes	Card PAN (e.g., 4024007153763191)
card_name	string	Yes	Cardholder name as printed on the card
card_expiry_month	string	Yes	Expiry month MM (e.g., 12)
card_expiry_year	string	Yes	Expiry year YYYY (e.g., 2030)
card_cvv	string	Yes	Card verification value
payer_tax_id	string	Yes	Cardholder tax ID (CPF, RFC, RUT, CUIT)
payer_email	string	No	Cardholder email for notifications

Card data handling

When sending raw card data, A55 encrypts and vaults it immediately upon receipt. If you prefer to avoid handling card data on your backend, use the A55Pay SDK or Checkout Page instead.

---

Response fields

Field	Type	Description
token_uuid	string	Reusable token identifier for future charges
card_brand	string	Card brand (visa, mastercard, amex, elo)
card_last_four	string	Last 4 digits of the card
card_expiry_month	string	Expiry month
card_expiry_year	string	Expiry year
status	string	active on success
created_at	string	ISO 8601 creation timestamp

---

HTTP status codes

Status	Description
200	Card tokenized successfully
400	Invalid card data or missing required fields
401	Invalid or expired Bearer token
403	Insufficient permissions for this wallet
404	Wallet not found
409	Card already tokenized for this wallet
422	Card validation failed (invalid number, expired)
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

---

Code examples

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

---

Error response example

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

---

Create charge →Use the token_uuid to charge the card later.BIN lookup →Check card brand and type before tokenizing.Zero-auth →Validate a card without charging.