O que é tokenização de cartão?

A Tokenização é um recurso e processo de segurança usado para proteger os dados sensíveis de um cartão de crédito.

Em vez de armazenar ou transmitir o número real do cartão (PAN – Primary Account Number), o sistema substitui esse número por um token, que é uma sequência aleatória de caracteres sem valor fora do sistema que o gerou.

Para realizar essa ação, é utilizado o serviço de "Zero Dollar Authorization", também conhecido como "Transação de verificação", que permite verificar a veridicidade do cartão sem realizar nenhuma cobrança.

Ao utilizar esse serviço, o portador receberá uma notificação de que houve uma verificação do cartão pelo estabelecimento.

Como funciona?

O comprador insere os dados do cartão (número, validade, CVV) em um site ou app.
O sistema envia os dados ao nosso gateway (PCI-DSS), que é encaminhado a uma autorizadora.
A autorizadora valida as informações e então é gerado um token único que representa o cartão.
O token é armazenado no gateway e poderá ser utilizado pelo estabelecimento ao invés do número real do cartão.
Nesse contexto, se alguém interceptar o token, ele não poderá usá-lo fora do nosso ambiente, o que traz uma segurança maior e impossibilita fraudadores.

🚧
Validação de saldo e limite do cartão.
No momento da tokenização, o serviço da autorizadora apenas verifica se o cartão é valido e está ativo (através do número, validade e CVV), ou seja, não é verificado saldo e limite do cartão.

Vantagens da tokenização

Segurança: reduz o risco de vazamento de dados sensíveis.
Conformidade: ajuda ao estabelecimento estar em conformidade com normas como PCI DSS.
Experiência do usuário: permite pagamentos recorrentes ou com um clique, sem expor os dados reais do cartão.

Como realizar a tokenização?

Existem duas maneiras de realizar a tokenização: com ou sem cobrança imediata.

Apenas tokenização (sem cobrança imediata)

Para realizar a tokenização, sem efetuar uma cobrança imediata, verifique a seção da documentação referente ao endpoint.

Tokenizar (Salvar cartão)

Tokenização durante cobrança

Para realizar a tokenização com uma cobrança, basta utilizar o parâmetro payment.create_token como true.

O token será retornado através do campo transactions.token

Exemplo disponível em Tokenizar (Salvar cartão)

Como utilizar o token?

Para realizar a cobrança com um token, basta enviar o token através do parâmetro payments.card.token conforme exemplo abaixo, e payment_method como "token"

{
    "amount": 1000,
    "order_id": "BR0000-58748892",
    "order_info": "charge description",
    "currency": "BRL",
    "type": "PAYMENT",
    "soft_descriptor": "PAYTEST",
    "payments": [
        {
            "amount": 1000,
            "payment_method": "token",
            "card": {
                "token": "7b4784e54a534d529d4975eb771bcd33"
            }
        }
    ],
    "client_ip": "117.149.23.241",
    "customer": {
        "name": "Edna Turner",
        "email": "[email protected]",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "birth_date": "2000-01-01",
        "document_type": "CPF",
        "document_number": "62286843023"
    }
}

{
    "uuid": "08639c08-55de-4c72-8658-da6e1aecbad2",
    "type": "PAYMENT",
    "expiry_date": "2025-11-14T02:59:59Z",
    "status": "PAID",
    "order_id": "BR0000-58748892",
    "order_info": "charge description",
    "currency": "BRL",
    "original_amount": 1000,
    "amount": 1000,
    "paid": 1000,
    "due": 0,
    "refunded": 0,
    "attempts": 1,
    "max_attempts": 5,
    "drop_reason": "",
    "surcharge": false,
    "client_ip": "117.149.23.241",
    "soft_descriptor": "PAYTEST",
    "enable_checkout_3ds": null,
    "customer": {
        "uuid": "819edeaa-7735-442d-a15d-73fa65a0a656",
        "name": "Edna Turner",
        "email": "[email protected]",
        "birth_date": "2000-01-01",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "document_type": "CPF",
        "document_number": "622******23",
        "created_at": "2025-11-11T14:18:30Z",
        "updated_at": "2025-11-11T14:18:30Z"
    },
    "transactions": [
        {
            "uuid": "0c330f4c-c83d-4513-9e06-c0b98c3d6ba5",
            "charge_uuid": "08639c08-55de-4c72-8658-da6e1aecbad2",
            "gateway_id": "82d2bbb081e040cb9301a0f09af42a5f",
            "amount": 1000,
            "paid_amount": 1000,
            "status": "PAID",
            "payment_option": "CARD",
            "payment_option_detail": "token",
            "scheme": "MASTERCARD",
            "external_id": "0123456789456789",
            "transaction_id_reference": null,
            "expected_capture_date": "2025-11-11T14:18:32Z",
            "payment_at": "2025-11-11T14:18:32Z",
            "captured_at": null,
            "auth_num": "123456",
            "auth_response_code": "0",
            "operation_type": "DEBIT",
            "extra": null,
            "payment_number": "597010XXXXXX0067",
            "payer_info": "Edna Turner",
            "expiry_month": 12,
            "expiry_year": 2025,
            "acquirer_network": "SUB",
            "nsu": "654321",
            "tid": "",
            "token": null,
            "create_token": false,
            "detailed_status": "AUTHORISED",
            "currency": "BRL",
            "document_type": "CPF",
            "document_number": "622******23",
            "installments": 1,
            "sub_acquirer": 1002,
            "has_auth_3ds": false,
            "created_at": "2025-11-11T14:18:33Z",
            "updated_at": "2025-11-11T14:18:33Z"
        }
    ],
    "created_at": "2025-11-11T14:18:30Z",
    "updated_at": "2025-11-11T14:18:30Z"
}