Card Tokenization

Quick Reference

WhatReplace PANs with secure tokens

WhyEnable 1-click and recurring payments with A55's secure vault

DifficultyIntermediate

PrerequisitesAuthentication → Create charge

Tokenization replaces raw card numbers (PANs) with non-reversible tokens that can be stored, reused, and passed through your systems without exposing sensitive data.

Why tokenize

Benefit	Detail
Secure storage	Tokens are not PANs — you can store and reuse them without handling sensitive card data
1-click checkout	Charge returning customers without collecting card details again
Recurring billing	Use the same token across subscription cycles without re-authentication
Higher approval rates	Acquirers recognize tokenized transactions as lower risk
Card lifecycle continuity	When a card is reissued, A55 can update the token automatically via account updater

Automatic vs explicit tokenization

Aspect	Automatic	Explicit
Trigger	A55 creates a token on every successful charge	Merchant calls the tokenize endpoint before charging
PAN exposure	Merchant never handles raw PAN after first charge	Merchant sends PAN once to the tokenize endpoint
Use case	Simplest path — no extra API calls	Full control over token lifecycle and metadata
Activation	Enabled per wallet via dashboard or API	Always available

Enable automatic tokenization

Automatic tokenization is disabled by default. To enable it, contact your account manager.

Token lifecycle

Explicit tokenization

POST https://sandbox.api.a55.tech/api/v1/bank/wallet/{wallet_uuid}/tokenize/

Postman: Import the A55 API Collection to test this endpoint interactively.

cURL

curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/{wallet_uuid}/tokenize/ \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"card_number":"4111111111111111","expiry_month":"12","expiry_year":"2027","holder_name":"Jane Doe"}'

Python

resp = requests.post(f"https://sandbox.api.a55.tech/api/v1/bank/wallet/{wallet_uuid}/tokenize/",
    headers={"Authorization": f"Bearer {token}"},
    json={"card_number": "4111111111111111", "expiry_month": "12",
          "expiry_year": "2027", "holder_name": "Jane Doe"})

JavaScript

const resp = await fetch(
  `https://sandbox.api.a55.tech/api/v1/bank/wallet/${walletUuid}/tokenize/`,
  { method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: JSON.stringify({ card_number: "4111111111111111", expiry_month: "12",
      expiry_year: "2027", holder_name: "Jane Doe" }) });

Response

{
  "card_token": "d7641ce9-9411-432c-bb25-240ce7dd3cef",
  "brand": "visa",
  "last_four": "1111",
  "expiry_month": "12",
  "expiry_year": "2027"
}

Charging with a token

Pass card_token (UUID) instead of raw card fields in your charge request:

{ "amount": 15000, "currency": "BRL", "card_token": "d7641ce9-9411-432c-bb25-240ce7dd3cef" }

Token takes priority

When both card_token and raw card fields are present, the token takes priority. A55 ignores the raw fields entirely.

Behavior notes

Behavior	Detail
Token priority	card_token overrides card_number if both are sent
Automatic mode	Returns the token in the charge response under card_token
Compatibility	Tokens are scoped to a single wallet and cannot be shared across wallets
No CVV storage	CVV is never stored — it is used only for the initial transaction
Lifecycle	Tokens remain active until explicitly deleted or the card expires

Explicit vs automatic

Explicit tokenization requires you to send a raw PAN and CVV to the API. A55 encrypts and vaults the data immediately upon receipt. Use automatic tokenization if you want to avoid handling card data entirely.

Sandbox testing

Simulate enrollment success, decline, and timeout scenarios using Test Cards. Change only the last digit of the card number to control the outcome.

Zero Auth →Validate a card before storing its tokenSubscriptions →Use tokens for recurring billingH2H Integration →Server-to-server integration guide