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 ID
merchant_uuid	string (UUID)	Yes	Merchant ID
card	object	Yes	Card information to tokenize
card.holder_name	string	Yes	Cardholder's name as printed on the card
card.number	string	Yes	Card number (PAN), 13–16 digits
card.expiry_month	string	Yes	Expiration month (01–12), 2 digits
card.expiry_year	string	Yes	Expiration year (YYYY), 4 digits
card.cvv	string	Yes	Card security code (CVV), 3 digits

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 (UUID)	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

Response example

{
  "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"
}

---

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://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"
    }
  }'

Python

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

Node.js

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

---

Sandbox simulation

In sandbox, tokenization outcomes follow the same test card rules as charges. A successful enrollment returns HTTP 200 with a token_uuid; failures return HTTP 400 with card_tokenization_failed.

Requires tokenization_enabled: true on the merchant. Contact your account manager to enable it.

---

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.