Tokenização de Cartão
Quick Reference
A tokenização de cartão substitui números de conta primários (PANs) brutos por tokens não-sensíveis que seus sistemas podem armazenar e reutilizar com segurança. Um vazamento do seu banco de dados não expõe números de cartão utilizáveis, e clientes recorrentes pagam com um clique.
Por que tokenizar
| Benefício | Detalhe |
|---|---|
| Armazenamento seguro | Tokens não são PANs — a A55 criptografa e armazena os dados com segurança |
| Checkout 1-clique | Cobre clientes recorrentes sem recoletar dados do cartão |
| Cobrança recorrente | Use o mesmo token para renovações de assinatura (MIT) |
| Maiores taxas de aprovação | Transações tokenizadas são tratadas como confiáveis pelos emissores |
| Continuidade do ciclo de vida do cartão | Tokens sobrevivem à reemissão do cartão (nova validade, mesmo token) |
Tokenização automática vs explícita
A A55 suporta dois modos de tokenização:
| Modo | Gatilho | Caso de uso |
|---|---|---|
| Automática (nível de conta) | A primeira cobrança bem-sucedida tokeniza o cartão de forma transparente | Integração sem alterações — ative e aproveite |
| Explícita (por cartão) | POST /api/v1/bank/wallet/tokenization/ antes de qualquer cobrança | Armazene um cartão antes do primeiro pagamento, setup off-session |
A tokenização automática é configurada a nível de conta. Contate tech.services@a55.tech para solicitar a ativação.
Ciclo de vida do token
Tokenização explícita
POST https://core-manager.a55.tech/api/v1/bank/wallet/tokenization/
- cURL
- Python
- JavaScript
curl -sS -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/tokenization/' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"wallet_uuid": "1f937eb2-cf2c-421c-aa24-3f26519f42fa",
"merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
"card": {
"holder_name": "Jane Doe",
"card_number": "4111111111111111",
"expiry_month": "12",
"expiry_year": "2030",
"cvv": "123",
"brand": "Visa"
}
}'
import os, requests
r = requests.post(
"https://core-manager.a55.tech/api/v1/bank/wallet/tokenization/",
headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
json={
"wallet_uuid": "1f937eb2-cf2c-421c-aa24-3f26519f42fa",
"merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
"card": {
"holder_name": "Jane Doe",
"card_number": "4111111111111111",
"expiry_month": "12",
"expiry_year": "2030",
"cvv": "123",
"brand": "Visa",
},
},
timeout=30,
)
token = r.json()["card_token"]
const res = await fetch('https://core-manager.a55.tech/api/v1/bank/wallet/tokenization/', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
wallet_uuid: '1f937eb2-cf2c-421c-aa24-3f26519f42fa',
merchant_uuid: 'd6f921ef-5bdd-4ebf-a065-bd38de839bd1',
card: {
holder_name: 'Jane Doe',
card_number: '4111111111111111',
expiry_month: '12',
expiry_year: '2030',
cvv: '123',
brand: 'Visa',
},
}),
});
const { card_token } = await res.json();
Resposta
{
"card_token": "d7641ce9-9411-432c-bb25-240ce7dd3cef"
}
Cobrando com um token
Uma vez que você tenha um card_token, referencie-o nas cobranças subsequentes em vez de campos de cartão brutos:
{
"wallet_uuid": "1f937eb2-cf2c-421c-aa24-3f26519f42fa",
"merchant_id": "merchant_123",
"currency": "BRL",
"installment_value": 100,
"type_charge": "credit_card",
"card_token": "d7641ce9-9411-432c-bb25-240ce7dd3cef",
"payer_name": "Jane Doe",
"payer_email": "jane@example.com",
"payer_tax_id": "12345678901"
}
Se tanto card_token quanto campos de cartão brutos forem enviados na mesma requisição, o token tem prioridade. Os campos brutos são ignorados.
Notas de comportamento
| Regra | Detalhe |
|---|---|
| Prioridade do token | O token prevalece quando token e dados brutos do cartão estão presentes |
| Modo automático | A tokenização ocorre na primeira cobrança bem-sucedida — nenhuma chamada de API é necessária |
| Compatibilidade | Totalmente compatível com 3DS, scoring antifraude e lógica de roteamento |
| Sem armazenamento de CVV | O CVV nunca é armazenado — usado apenas na tokenização inicial |
| Ciclo de vida | Tokens sobrevivem à reemissão do cartão; excluídos apenas por solicitação explícita ou cancelamento do cartão |
A tokenização explícita recebe PAN e CVV brutos. A A55 criptografa e protege esses dados, mas garanta que o transporte seja feito via HTTPS. Prefira a tokenização automática, a menos que o controle explícito seja necessário.