Tokenização de cartão na transação

Gere o token do cartão durante uma compra aprovada e use-o para cobrar o cliente de novo, sem pedir os dados do cartão.

O que é tokenização

Tokenizar um cartão é trocar os dados sensíveis dele (número, validade, nome do titular) por um token: um identificador único e aleatório, sem valor fora da Paytime. Com o token salvo, você cobra o cliente de novo enviando só o token, sem precisar pedir ou guardar os dados do cartão.


Duas formas de tokenizar na Paytime

A Paytime oferece dois caminhos para gerar o token. Os dois chegam ao mesmo resultado: um token que você usa depois no campo card.token de POST /v1/marketplace/transactions. A diferença está em quando o token é gerado e como os dados do cartão chegam à Paytime.

Na transação (esta página)Validação Zero Dollar
Quando o token é geradoJunto com uma compra real, ao enviar create_token: true.Antes de qualquer compra, numa validação de valor zero.
Cobrança no cartãoSim: o valor da primeira compra.Não. Nada é lançado na fatura.
RotaPOST /v1/marketplace/transactionsGET /v1/marketplace/cards/public-key + POST /v1/marketplace/cards/tokenize
Como os dados do cartão trafegamAbertos, do seu backend para a Paytime (número, validade e CVV).Criptografados no navegador com o SDK da PagBank. Seu backend nunca vê os dados abertos.
Escopo PCI do seu ambienteMaior: seu ambiente recebe e transmite dados de cartão.Reduzido: só o encrypted_card passa pelo seu backend.
Validação do cartãoA própria autorização da compra.Validação Zero Dollar com o emissor.
IntegraçãoUm campo a mais na transação que você já faz.Três etapas, incluindo o SDK no frontend.

Qual escolher?

Use a tokenização na transação quando:
  • o cartão é salvo na primeira compra (por exemplo, “salvar cartão para próximas compras” no checkout);

  • você já envia os dados do cartão pelo seu backend e quer só adicionar o token;

  • não há necessidade de validar o cartão antes da cobrança.

Use a validação Zero Dollar quando:
  • o cartão precisa ser cadastrado sem cobrança (carteira, assinatura com período grátis, cadastro prévio);
  • você quer validar o cartão antes da primeira cobrança;
  • você quer reduzir o escopo PCI, sem que os dados abertos passem pelo seu servidor.

Como funciona

sequenceDiagram
    participant BE as Seu backend
    participant PT as API Paytime

    Note over BE,PT: Passo 1 · Primeira compra
    BE->>PT: POST /v1/marketplace/transactions<br/>dados do cartão + "create_token": true
    Note right of PT: Cobra e tokeniza
    PT-->>BE: transação + card.token
    Note over BE: Armazena o token

    Note over BE,PT: Passo 2 · Compras futuras
    BE->>PT: POST /v1/marketplace/transactions<br/>"card": { "token": "..." }
    PT-->>BE: transação
📘

No passo 2, você não envia número, validade nem CVV: apenas o token.


Antes de começar

  • Credenciais e token de acesso: as chamadas exigem Authorization: Bearer {token} (gerado em POST /v1/auth/login, válido por 30 minutos), integration-key, x-token e establishment_id. Veja Credenciais de acesso e Autenticação.
  • Transação de crédito: a tokenização vale para payment_type: "CREDIT". Os demais campos da transação seguem Criar transação com cartão de crédito.
  • PCI DSS: neste fluxo, os dados abertos do cartão passam pelo seu backend. Garanta que o seu ambiente atende aos requisitos PCI DSS aplicáveis. Veja Requisitos de segurança.


Passo 1 · Criar a transação e gerar o token

Na primeira compra, envie a transação normalmente, com os dados do cartão, e adicione "create_token": true dentro do objeto card. Se a transação for processada, a resposta traz o token em card.token.

🔼

POST /v1/marketplace/transactions

Campos do objeto card

NomeTipoObrigatórioDescrição
holder_namestringSimNome do titular, como impresso no cartão.
holder_documentstringSimCPF ou CNPJ do titular, só números.
card_numberstringSimNúmero do cartão (13 a 16 dígitos).
expiration_monthnumberSimMês de validade, de 1 a 12.
expiration_yearnumberSimAno de validade com 4 dígitos.
security_codestringSimCódigo de segurança (CVV), com 3 ou 4 dígitos.
create_tokenbooleanNãoEnvie true para gerar o token do cartão nesta transação.

Exemplo de requisição (resumida)

{
  "payment_type": "CREDIT",
  "amount": 27001,
  "installments": 1,
  "interest": "CLIENT",
  "client": {
    "...":"..."
  },
  "card": {
    "holder_name": "JOAO DA SILVA",
    "holder_document": "12345678909",
    "card_number": "5200000000001005",
    "expiration_month": 12,
    "expiration_year": 2030,
    "security_code": "123",
    "create_token": true
  }
}

Resposta de sucesso · 200 (resumida)

A resposta é a mesma de uma transação de crédito comum. O token vem dentro do objeto card:

{
  "_id": "6a1f0c2e9b7d4a0012ab34cd",
  "status": "PAID",
  "type": "CREDIT",
  "amount": 27001,
  "installments": 1,
  "card": {
    "brand_name": "MASTERCARD",
    "first4_digits": "5200",
    "last4_digits": "1005",
    "expiration_month": "12",
    "expiration_year": "2030",
    "holder_name": "JOAO DA SILVA",
    "token": "6ed0cc99bbf3a2fa68f45cc55df7ec96501b02af64d081c08e12235794069928167ca"
  },
  "created_at": "2026-11-12T14:32:10.000Z"
}
CampoTipoDescrição
card.tokenstringToken do cartão. Guarde-o vinculado ao seu cliente para as próximas cobranças.
card.brand_namestringBandeira do cartão.
card.first4_digits / card.last4_digitsstringPrimeiros e últimos 4 dígitos, para exibir o cartão salvo ao cliente.
card.expiration_month / card.expiration_yearstringValidade do cartão, útil para avisar o cliente antes do vencimento.


Passo 2 · Usar o token em compras futuras

Nas próximas compras, envie o token no objeto card no lugar dos dados do cartão. Não envie número, validade, CVV nem create_token.

🔼

POST /v1/marketplace/transactions

NomeTipoObrigatórioDescrição
card.tokenstringSimToken obtido no Passo 1 (ou na validação Zero Dollar).

Exemplo de requisição (resumida)

{
  "payment_type": "CREDIT",
  "amount": 29001,
  "installments": 1,
  "interest": "CLIENT",
  "client": {
    "...": "..."
  },
  "card": {
    "token": "6ed0cc99bbf3a2fa68f45cc55df7ec96501b02af64d081c08e12235794069928167ca"
  }
}

A resposta segue o formato de uma transação de crédito comum. Veja os status possíveis em Criar transação com cartão de crédito.


📘

Antifraude

Algumas restrições podem se aplicar ao usar token junto com antifraude (antifraud_type THREEDS ou IDPAY). Veja Uso de antifraude e envio de dados.


Respostas de erro

StatusSituaçãoO que fazer
400Requisição inválida ou token inexistente.Confira o token salvo. Se ele não for mais válido, peça ao cliente para cadastrar o cartão de novo.
401Token Bearer ausente, inválido ou expirado.Gere um novo token em POST /v1/auth/login.


Exemplo de implementação

Exemplo em Node.js (18+) com as duas chamadas. A função paytimeHeaders() monta os headers de autenticação, como no exemplo da página Validação (Zero Dollar) e armazenamento de cartão.

const API_URL = process.env.PAYTIME_API_URL; // https://api.sandbox.paytime.com.br

// Passo 1: primeira compra, gerando o token
async function firstPurchase(customer, cardData, amount) {
  const r = await fetch(`${API_URL}/v1/marketplace/transactions`, {
    method: "POST",
    headers: await paytimeHeaders(customer.establishmentId),
    body: JSON.stringify({
      payment_type: "CREDIT",
      amount,
      installments: 1,
      interest: "CLIENT",
      client: customer.paytimeClient,
      card: { ...cardData, create_token: true }, // nunca registre cardData em log
    }),
  });
  const transaction = await r.json();

  if (r.ok && transaction.status === "PAID" && transaction.card?.token) {
    await saveCustomerCard(customer.id, {
      token: transaction.card.token,
      brand: transaction.card.brand_name,
      last4: transaction.card.last4_digits,
      expMonth: transaction.card.expiration_month,
      expYear: transaction.card.expiration_year,
    });
  }
  return transaction;
}

// Passo 2: compras futuras, só com o token
async function chargeSavedCard(customer, savedCard, amount) {
  const r = await fetch(`${API_URL}/v1/marketplace/transactions`, {
    method: "POST",
    headers: await paytimeHeaders(customer.establishmentId),
    body: JSON.stringify({
      payment_type: "CREDIT",
      amount,
      installments: 1,
      interest: "CLIENT",
      client: customer.paytimeClient,
      card: { token: savedCard.token },
    }),
  });
  return r.json();
}


Segurança e boas práticas

  • Guarde o token com segurança: ele permite cobrar o cliente. Armazene com acesso restrito, vinculado ao cliente e ao estabelecimento.
  • Não guarde os dados do cartão: depois de obter o token, descarte número, validade e CVV. O CVV nunca pode ser armazenado.
  • Nada sensível em logs: não registre dados de cartão, tokens ou payloads completos em logs, traces ou ferramentas de monitoramento.
  • Consentimento: peça autorização do cliente para salvar o cartão e para cobranças futuras, e ofereça uma forma de remover o cartão salvo.
  • Quer reduzir o escopo PCI? Considere a validação Zero Dollar, em que os dados do cartão são criptografados no navegador e não passam abertos pelo seu backend.


Perguntas frequentes

Posso usar um token gerado na validação Zero Dollar nesta mesma rota?

Sim. Os dois fluxos geram um token usado da mesma forma, no campo card.token de POST /v1/marketplace/transactions.

Preciso enviar create_token em toda compra?

Não. Envie create_token: true só quando quiser salvar um cartão novo. Nas compras com token, não envie esse campo.

O token tem cobrança?

Não há cobrança pelo token em si. A primeira compra (Passo 1) é uma transação normal, cobrada no cartão do cliente.


Did this page help you?