🔗
O criação e utilização de tokens e utilizado é realizado na rota POST /v1/transactions/

👍
Para exemplos de requisição e resposta da API, verifique a seção: VENDAS - OPERAÇÕES E GESTÃO > Criar Venda

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 mitiga 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.

Novas regras para criação e utilização de tokens

Desde outubro de 2022, em razão de atualizações regulatórias da bandeira Mastercard, as transações com tokens (card-on-file -- cartões armazenados) passaram a exigir classificação em diferentes categorias de CIT (Customer Initiated Transaction — iniciada pelo portador do cartão) e MIT (Merchant Initiated Transaction — iniciada pelo estabelecimento).

O envio dessas informações tornou-se obrigatório para operações em 1º de junho de 2023. Desde 1º de junho de 2024, a bandeira poderá aplicar medidas de não conformidade e eventuais penalidades aos estabelecimentos que não realizarem o envio correto dos dados exigidos durante o período regulatório aplicável.

Além do atendimento às exigências regulatórias, o correto preenchimento do campo auxilia a bandeira e os emissores na análise das transações, contribuindo para avaliações de risco mais precisas e potencialmente melhorando os índices de autorização e conversão.

📘
Verifique essa seção detalhada referente as regras CIT/MIT: Novas Regras CIT/MIT

Como realizar a tokenização?

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

Tokenização avulsa (sem cobrança imediata)

A Tokenização avulsa permite criar um token de cartão, sem realizar nenhuma cobrança.

Ao criar o token, o comprador geralmente é notificado, com uma mensagem do tipo "O estabelecimento Fulano acabou de verificar se o seu cartão está ativo".

📘
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 com cobrança simultânea.

A tokenização com cobrança permite realizar uma venda com cartão e criar um token em conjunto.

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"

{
    "order_id": "6849f23f-c0ca-46c2-bb95-8d470d87cd22",
    "order_info": "charge description",
    "currency": "BRL",
    "type": "TOKENIZATION",
    "customer": {
        "name": "João Silva",
        "email": "[email protected]"
    },
    "payments": [
        {
            "create_token": true,
            "payment_method": "card",
            "transaction_initiator": "CUSTOMER",
            "use_case": "REGISTER",
            "card": {
                "number": "5970100300000042",
                "holder_name": "João Silva",
                "exp_month": 12,
                "exp_year": 2029,
                "cvv": "123"
            }
        }
    ]
}

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