Tokenizar via API

Use este fluxo quando o cartão trafega pelo seu servidor (back-end). A autenticação é feita com o token secreto de API, o mesmo usado nos demais endpoints (Autenticação).

Endpoint

POST /api/v1/card/tokenize

Exemplo — token efêmero (sem vincular cliente)

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/card/tokenize \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "card": {
            "holder": "MARIA SOUZA",
            "number": "4111111111111111",
            "expiration": "12/2030",
            "security": "123"
        }
    }'

O token retornado expira após o período configurado (padrão: 15 minutos). Para gerar um token permanente, vincule um cliente.

Exemplo — vinculando um cliente novo (find-or-create por documento)

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/card/tokenize \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "card": {
            "holder": "MARIA SOUZA",
            "number": "4111111111111111",
            "expiration": "12/2030",
            "security": "123"
        },
        "customer": {
            "fullname": "Maria Souza",
            "taxvat": "12345678909",
            "email": "cliente@exemplo.com",
            "telephone": "11999998888"
        }
    }'

Se o cliente já existe na sua empresa, informe apenas o customer_id:

"customer_id": 4231

Atributos

Atributo	Tipo	Obrigatório	Descrição
card ⌄	Objeto	Sim	Dados do cartão a ser tokenizado.
card.holder	Texto	Sim	Nome impresso no cartão (máx. 25 caracteres). Ex: MARIA SOUZA
card.number	Texto	Sim	Número do cartão de crédito.
card.expiration	Texto	Sim	Validade no formato MM/YYYY, não vencida. Ex: 12/2030
card.security	Texto	Sim	Código de segurança (CVV).
customer_id	Número	Não	ID de um cliente já existente na sua empresa. Gera token permanente.
customer ⌄	Objeto	Não	Cliente a vincular (find-or-create pelo taxvat). Gera token permanente.
customer.taxvat	Texto	Condicional	Documento do cliente (CPF/CNPJ). Obrigatório quando customer é informado.
customer.fullname	Texto	Não	Nome do cliente.
customer.email	Texto	Não	E-mail do cliente.
customer.telephone	Texto	Não	Telefone do cliente.

Cliente é opcional

Envie customer_id (existente), o objeto customer completo (find-or-create) ou nada. Sem cliente, o token é efêmero e expira.

Resposta

Sucesso (HTTP 201)

{
    "data": {
        "token": "card_3e1d9542-09fe-4b8b-9800-38f99f5b2147",
        "customer_id": null,
        "brand": "visa",
        "last_digits": "1111",
        "expiration": "12/2030",
        "expires_at": "2026-07-07T12:15:00-03:00"
    }
}

Quando o token é permanente (cliente vinculado), expires_at é null e customer_id traz o ID do cliente.

Situação	Status
Cartão tokenizado com sucesso	201
Credencial ausente ou inválida	401
Cartão inválido ou vencido	422

Rate limit

A tokenização é limitada a 15 requisições por minuto por credencial. Ao exceder, a resposta é 429.

Usando o token na venda

Informe o token em payment.card.token ao criar uma venda avulsa, no lugar dos dados completos do cartão:

"payment": {
    "method": "credit",
    "installments": 1,
    "card": {
        "token": "card_3e1d9542-09fe-4b8b-9800-38f99f5b2147"
    }
}

Tokens efêmeros só valem dentro da janela de expiração e na empresa que os gerou. Token inválido ou expirado retorna 422 na venda.