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 é gerado | Junto com uma compra real, ao enviar create_token: true. | Antes de qualquer compra, numa validação de valor zero. |
| Cobrança no cartão | Sim: o valor da primeira compra. | Não. Nada é lançado na fatura. |
| Rota | POST /v1/marketplace/transactions | GET /v1/marketplace/cards/public-key + POST /v1/marketplace/cards/tokenize |
| Como os dados do cartão trafegam | Abertos, 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 ambiente | Maior: seu ambiente recebe e transmite dados de cartão. | Reduzido: só o encrypted_card passa pelo seu backend. |
| Validação do cartão | A própria autorização da compra. | Validação Zero Dollar com o emissor. |
| Integração | Um campo a mais na transação que você já faz. | Três etapas, incluindo o SDK no frontend. |
Qual escolher?
-
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.
- 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 emPOST /v1/auth/login, válido por 30 minutos),integration-key,x-tokeneestablishment_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
card| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
holder_name | string | Sim | Nome do titular, como impresso no cartão. |
holder_document | string | Sim | CPF ou CNPJ do titular, só números. |
card_number | string | Sim | Número do cartão (13 a 16 dígitos). |
expiration_month | number | Sim | Mês de validade, de 1 a 12. |
expiration_year | number | Sim | Ano de validade com 4 dígitos. |
security_code | string | Sim | Código de segurança (CVV), com 3 ou 4 dígitos. |
create_token | boolean | Não | Envie 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"
}| Campo | Tipo | Descrição |
|---|---|---|
card.token | string | Token do cartão. Guarde-o vinculado ao seu cliente para as próximas cobranças. |
card.brand_name | string | Bandeira do cartão. |
card.first4_digits / card.last4_digits | string | Primeiros e últimos 4 dígitos, para exibir o cartão salvo ao cliente. |
card.expiration_month / card.expiration_year | string | Validade 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
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
card.token | string | Sim | Token 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.
AntifraudeAlgumas restrições podem se aplicar ao usar token junto com antifraude (
antifraud_typeTHREEDSouIDPAY). Veja Uso de antifraude e envio de dados.
Respostas de erro
| Status | Situação | O que fazer |
|---|---|---|
400 | Requisiçã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. |
401 | Token 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.
Updated 10 days ago