Validação (Zero Dollar) e armazenamento de cartão

Valide um cartão de crédito sem cobrar nada do cliente e guarde-o com segurança para usar em compras futuras.

O que é

Este recurso junta duas operações em uma única chamada à API da Paytime:

  • Validação Zero Dollar: o cartão passa por uma verificação de valor zero junto ao emissor, via PagBank. Assim você confirma que o cartão existe, está ativo e pode ser usado, sem lançar nenhuma cobrança na fatura do cliente.
  • Armazenamento (tokenização): se o cartão for validado, a Paytime o guarda em ambiente seguro via PagBank e devolve um token. É esse token que você usa depois para capturar transações, sem precisar pedir os dados do cartão de novo.

Os dados do cartão são criptografados no navegador do cliente com o SDK da PagBank, antes de sair do dispositivo. Nem o seu servidor nem a Paytime recebem número, validade ou código de segurança em texto aberto. Isso reduz bastante o escopo PCI da sua integração.


Quando usar

  • Carteira de cartões: o cliente cadastra o cartão uma vez e escolhe ele nas próximas compras.
  • Assinaturas e cobranças recorrentes: valide o cartão na adesão e cobre nos ciclos seguintes com o token.
  • Compra com um clique: finalize pedidos sem que o cliente digite os dados do cartão de novo.
  • Pré-validação: confirme que o cartão é válido antes da primeira cobrança, para diminuir recusas e fraudes.

Visão geral do fluxo

A integração tem três etapas. As chamadas à API da Paytime partem sempre do seu backend, porque é lá que ficam as suas credenciais. A criptografia acontece no frontend, onde o cliente digita os dados do cartão.

EtapaO que aconteceOnde
1. Obter a chave públicaSeu backend consulta a chave pública na Paytime e a repassa ao frontend.Backend → API Paytime
2. Criptografar o cartãoO frontend usa o SDK da PagBank e a chave pública para gerar o encrypted_card.Frontend → SDK PagBank
3. Validar e tokenizarSeu backend envia o encrypted_card à Paytime, que valida o cartão com Zero Dollar e devolve o token.Backend → API Paytime
sequenceDiagram
    participant SDK as SDK PagBank (navegador)
    participant FE as Seu frontend
    participant BE as Seu backend
    participant PT as API Paytime

    Note over BE,PT: Etapa 1
    BE->>PT: GET /v1/marketplace/cards/public-key
    PT-->>BE: { public_key }
    BE-->>FE: public_key

    Note over SDK,FE: Etapa 2 (processamento local, sem rede)
    FE->>SDK: PagSeguro.encryptCard(...)
    SDK-->>FE: encryptedCard

    Note over FE,PT: Etapa 3
    FE->>BE: encrypted_card + holder_document
    BE->>PT: POST /v1/marketplace/cards/tokenize
    Note right of PT: Validação Zero Dollar<br/>e tokenização
    PT-->>BE: token + dados do cartão
    Note over BE: Armazena o token

    Note over BE,PT: Em uma compra futura
    BE->>PT: POST /v1/marketplace/transactions (card.token)
📘

Os dados do cartão só saem do navegador já criptografados.


Antes de começar

  • Credenciais de acesso: você precisa de integration-key, authentication-key e x-token. Veja Credenciais de acesso.
  • Token de autenticação: todas as chamadas desta página exigem o header Authorization: Bearer {token}, gerado em POST /v1/auth/login e válido por 30 minutos. Veja Autenticação.
  • Estabelecimento: o estabelecimento precisa estar cadastrado e ativo. O cartão é tokenizado no contexto dele, informado pelo header establishment_id.
  • HTTPS: a página onde o cliente digita o cartão precisa ser servida com HTTPS (TLS 1.2 ou superior).
AmbienteURL base
Sandboxhttps://api.sandbox.paytime.com.br
Produçãohttps://api.paytime.com.br

Headers usados nas etapas 1 e 3

NomeTipoObrigatórioDescrição
AuthorizationstringSimBearer {token} obtido em POST /v1/auth/login.
integration-keystringSimChave de integração do parceiro.
x-tokenstringSimToken disponível na aba Integração do Gestor.
establishment_idstringSimID do estabelecimento ao qual o cartão será vinculado.
Content-TypestringEtapa 3application/json


Etapa 1 · Obter a chave pública

A chave pública (public_key) é o que o SDK da PagBank usa para criptografar o cartão. Ela é pública: pode ser entregue ao frontend sem risco, porque só criptografa. Quem descriptografa é a PagBank, com a chave privada correspondente, que só ela tem.

🔼

GET /v1/marketplace/cards/public-key

Exemplo de requisição

curl --request GET \
  --url https://api.sandbox.paytime.com.br/v1/marketplace/cards/public-key \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'integration-key: 3f1c9a2e-0000-0000-0000-000000000000' \
  --header 'x-token: 7b2d4e6f-0000-0000-0000-000000000000' \
  --header 'establishment_id: 123456' \
  --header 'Accept: application/json'

Resposta de sucesso · 200

{
  "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCA...PRpgwIDAQAB"
}
CampoTipoDescrição
public_keystringChave pública RSA, em Base64, a ser passada ao SDK da PagBank no parâmetro publicKey.
📘

Boas práticas

  • Faça a chamada pelo seu backend e entregue ao frontend só a public_key. As credenciais da Paytime nunca devem ir para o navegador ou o app.
  • Use cache. A chave não muda a cada requisição. Guarde-a no seu backend e consulte de novo periodicamente ou quando o SDK devolver INVALID_PUBLIC_KEY.
  • Use só a chave fornecida pela Paytime. Chaves criadas diretamente numa conta PagBank, inclusive as do serviço de Pagamento Recorrente, não funcionam neste fluxo.


Etapa 2 · Criptografar o cartão com o SDK da PagBank

Com a public_key em mãos, o frontend criptografa os dados do cartão com o SDK JavaScript da PagBank. Tudo acontece localmente, no navegador: o SDK não faz chamadas de rede e devolve uma string criptografada (RSA), o encryptedCard.

2.1 Incluir o SDK

Adicione o script antes de fechar a tag </body> da página de pagamento:

<script src="https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js"></script>

2.2 Chamar PagSeguro.encryptCard()

ParâmetroTipoDescrição
publicKeystringValor de public_key obtido na Etapa 1.
holderstringNome do titular, como impresso no cartão.
numberstringNúmero do cartão, só dígitos.
expMonthstringMês de validade, de 1 a 12.
expYearstringAno de validade com 4 dígitos, por exemplo 2030.
securityCodestringCódigo de segurança (CVV), com 3 ou 4 dígitos.
const card = PagSeguro.encryptCard({
  publicKey: publicKey,          // public_key da Etapa 1
  holder: "JOAO DA SILVA",
  number: "5555666677778884",
  expMonth: "12",
  expYear: "2030",
  securityCode: "123",
});

if (card.hasErrors) {
  console.warn(card.errors);     // [{ code: "INVALID_NUMBER", message: "..." }]
} else {
  const encryptedCard = card.encryptedCard; // envie ao seu backend
}

O método devolve um objeto com:

CampoTipoDescrição
encryptedCardstringCartão criptografado. É o valor enviado na Etapa 3, no campo encrypted_card.
hasErrorsbooleanIndica se houve erro na criptografia.
errorsarrayLista de erros, cada um com code e message.

Erros de criptografia

Esses erros são devolvidos pelo SDK antes de qualquer chamada à API. Use-os para avisar o cliente sobre o campo preenchido errado.

CódigoSignificadoSugestão de mensagem ao cliente
INVALID_NUMBERNúmero do cartão inválido.Confira o número do cartão.
INVALID_SECURITY_CODECódigo de segurança precisa ter 3 ou 4 dígitos.Confira o código de segurança.
INVALID_EXPIRATION_MONTHMês precisa estar entre 1 e 12.Confira o mês de validade.
INVALID_EXPIRATION_YEARAno precisa ter 4 dígitos.Confira o ano de validade.
INVALID_PUBLIC_KEYChave pública inválida.Erro técnico: obtenha a chave novamente (Etapa 1).
INVALID_HOLDERNome do titular inválido.Confira o nome impresso no cartão.
🚧

Atenção

  • O encryptedCard não é o token do cartão. Ele só transporta os dados com segurança até a Paytime. O token só é gerado na Etapa 3.
  • Use o encryptedCard na hora e uma única vez. Não guarde, não reutilize e não grave em logs.
  • Os dados abertos do cartão não devem ir para o seu servidor. Envie apenas o encryptedCard. Nunca armazene o CVV.


Etapa 3 · Validar (Zero Dollar) e tokenizar o cartão

O frontend envia o encryptedCard ao seu backend, que repassa à Paytime junto com o documento do titular. A Paytime então:

  1. valida a requisição e o estabelecimento;
  2. faz a validação Zero Dollar do cartão na PagBank, sem cobrança;
  3. se o cartão for aprovado, armazena-o com segurança via PagBank e devolve o token e os dados não sensíveis do cartão.
🔼

POST /v1/marketplace/cards/tokenize

Body

NomeTipoObrigatórioDescrição
encrypted_cardstringSimValor de encryptedCard gerado pelo SDK na Etapa 2.
holder_documentstringNãoCPF ou CNPJ do titular do cartão, só números.

Exemplo de requisição

curl --request POST \
  --url https://api.sandbox.paytime.com.br/v1/marketplace/cards/tokenize \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'integration-key: 3f1c9a2e-0000-0000-0000-000000000000' \
  --header 'x-token: 7b2d4e6f-0000-0000-0000-000000000000' \
  --header 'establishment_id: 123456' \
  --header 'Content-Type: application/json' \
  --data '{
    "encrypted_card": "Xk3pQ9vL2mN8rT5wY1zA4N4oP6qR8sT0uV...aB3cD5eF7gH9iJ==",
    "holder_document": "12345678909"
  }'

Resposta de sucesso · 200

Cartão validado e armazenado.

{
  "token": "c1f0a8e2b7d94c3f9a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a",
  "brand_name": "MASTERCARD",
  "bin": "555566",
  "last4_digits": "8884",
  "holder_name": "JOAO DA SILVA",
  "expiration_month": "12",
  "expiration_year": "2030",
  "_id": "6a3535a1383e6084c41135cb"
}
CampoTipoDescrição
tokenstringToken do cartão. Guarde-o para capturar transações futuras, no campo card.token.
brand_namestringBandeira do cartão, por exemplo MASTERCARD ou VISA.
binstringSeis primeiros dígitos do cartão.
last4_digitsstringQuatro últimos dígitos do cartão.
holder_namestringNome do titular, como informado na criptografia.
expiration_monthstringMês de validade.
expiration_yearstringAno de validade.
_idstringIdentificador do cartão armazenado na Paytime.
👍

Dica

Use brand_name e last4_digits para mostrar o cartão salvo ao cliente (por exemplo, “Mastercard final 8884”). Guarde também expiration_month e expiration_year para avisar o cliente antes de o cartão vencer.

Respostas de erro

StatusSituaçãoO que fazer
400Requisição inválida: campo ausente, encrypted_card malformado ou expirado, documento inválido.Corrija os dados. Se o problema for o encrypted_card, gere um novo (Etapa 2).
401Token Bearer ausente, inválido ou expirado.Gere um novo token em POST /v1/auth/login.
4xxCartão não aprovado na validação Zero Dollar.Peça ao cliente para conferir os dados ou usar outro cartão. Não tente de novo com o mesmo encrypted_card.
500Erro interno.Tente de novo mais tarde com um novo encrypted_card. Se persistir, acione o suporte.


Usar o token em uma transação

Com o cartão salvo, crie transações de crédito informando apenas o token no objeto card, sem os dados do cartão. Os demais campos da transação seguem o padrão de Criar transação com cartão de crédito.

🔼

POST /v1/marketplace/transactions

{
  "payment_type": "CREDIT",
  "amount": 15990,
  "installments": 1,
  "interest": "STORE",
  "client": {
    "first_name": "Joao",
    "last_name": "da Silva",
    "document": "12345678909",
    "phone": "27999990000",
    "email": "[email protected]"
  },
  "card": {
    "token": "c1f0a8e2b7d94c3f9a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a"
  },
  "reference_id": "pedido-000123"
}

📘

Quer tokenizar durante a compra?

Se o cartão for salvo na primeira compra, você pode gerar o token na própria transação, com create_token: true, sem a validação Zero Dollar. Veja Tokenização de cartão na transação e compare os dois fluxos.



Exemplo completo de implementação

O exemplo abaixo mostra o fluxo de ponta a ponta com uma página HTML e um backend Node.js (18+) com Express. Os nomes das rotas do seu backend (/checkout/public-key e /checkout/cards) são só ilustrativos.

<form id="card-form">
  <!-- Os inputs NÃO têm o atributo "name": os dados abertos nunca são enviados -->
  <input id="holder"    placeholder="Nome impresso no cartão" autocomplete="cc-name">
  <input id="document"  placeholder="CPF/CNPJ do titular">
  <input id="number"    placeholder="Número do cartão" inputmode="numeric" autocomplete="cc-number">
  <input id="exp-month" placeholder="MM"   inputmode="numeric" autocomplete="cc-exp-month">
  <input id="exp-year"  placeholder="AAAA" inputmode="numeric" autocomplete="cc-exp-year">
  <input id="cvv"       placeholder="CVV"  inputmode="numeric" autocomplete="cc-csc">
  <button type="submit">Salvar cartão</button>
</form>

<script src="https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js"></script>
<script>
  const val = (id) => document.getElementById(id).value.trim();
  const digits = (s) => s.replace(/\D/g, "");

  document.getElementById("card-form").addEventListener("submit", async (e) => {
    e.preventDefault();

    // Etapa 1: busca a chave pública no SEU backend
    const { public_key } = await fetch("/checkout/public-key").then((r) => r.json());

    // Etapa 2: criptografa o cartão localmente
    const card = PagSeguro.encryptCard({
      publicKey: public_key,
      holder: val("holder"),
      number: digits(val("number")),
      expMonth: val("exp-month"),
      expYear: val("exp-year"),
      securityCode: val("cvv"),
    });

    if (card.hasErrors) {
      alert(card.errors.map((err) => err.code).join(", "));
      return;
    }

    // Etapa 3: envia só o cartão criptografado ao SEU backend
    const resp = await fetch("/checkout/cards", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        encrypted_card: card.encryptedCard,
        holder_document: digits(val("document")),
      }),
    });

    if (resp.ok) {
      const saved = await resp.json();
      alert(`Cartão ${saved.brand} final ${saved.last4} salvo!`);
    } else {
      alert("Não foi possível validar o cartão. Confira os dados ou use outro cartão.");
    }
  });
</script>
import express from "express";

const app = express();
app.use(express.json());

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

// Token Bearer reaproveitado por até 25 min (expira em 30 min)
let auth = { token: null, expiresAt: 0 };
async function getBearerToken() {
  if (auth.token && Date.now() < auth.expiresAt) return auth.token;
  const r = await fetch(`${API_URL}/v1/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      "integration-key": process.env.PAYTIME_INTEGRATION_KEY,
      "authentication-key": process.env.PAYTIME_AUTHENTICATION_KEY,
      "x-token": process.env.PAYTIME_X_TOKEN,
    }),
  });
  const { token } = await r.json();
  auth = { token, expiresAt: Date.now() + 25 * 60 * 1000 };
  return token;
}

async function paytimeHeaders(establishmentId) {
  return {
    Authorization: `Bearer ${await getBearerToken()}`,
    "integration-key": process.env.PAYTIME_INTEGRATION_KEY,
    "x-token": process.env.PAYTIME_X_TOKEN,
    establishment_id: establishmentId,
    "Content-Type": "application/json",
  };
}

// Etapa 1: entrega a chave pública ao frontend
app.get("/checkout/public-key", async (req, res) => {
  const r = await fetch(`${API_URL}/v1/marketplace/cards/public-key`, {
    headers: await paytimeHeaders(process.env.PAYTIME_ESTABLISHMENT_ID),
  });
  if (!r.ok) return res.status(502).json({ message: "Chave indisponível" });
  const { public_key } = await r.json();
  res.json({ public_key });
});

// Etapa 3: valida (Zero Dollar) e tokeniza o cartão na Paytime
app.post("/checkout/cards", async (req, res) => {
  const { encrypted_card, holder_document } = req.body; // nunca registre em log

  const r = await fetch(`${API_URL}/v1/marketplace/cards/tokenize`, {
    method: "POST",
    headers: await paytimeHeaders(process.env.PAYTIME_ESTABLISHMENT_ID),
    body: JSON.stringify({ encrypted_card, holder_document }),
  });

  if (!r.ok) return res.status(422).json({ message: "Cartão não validado" });

  const card = await r.json();
  // Persista token, _id, brand_name, last4_digits e validade vinculados ao seu cliente
  await saveCustomerCard(req.user.id, card);

  res.status(201).json({ brand: card.brand_name, last4: card.last4_digits });
});

app.listen(3000);

Segurança e boas práticas

  • Credenciais só no servidor: integration-key, authentication-key, x-token e o token Bearer nunca devem aparecer no frontend, em apps ou em repositórios.
  • Dados do cartão só criptografados: o número, a validade e o CVV não devem passar pelo seu backend. Envie apenas o encrypted_card.
  • Nada sensível em logs: não registre encrypted_card, tokens ou payloads completos em logs, traces, filas de erro ou ferramentas de monitoramento.
  • Guarde o token com segurança: ele permite cobrar o cliente. Armazene-o com acesso restrito e vinculado ao cliente e ao estabelecimento.
  • Consentimento: peça o consentimento do cliente para salvar o cartão e para cobranças futuras ou recorrentes, e deixe claro como ele pode remover o cartão.
  • PCI: criptografar no navegador reduz o seu escopo PCI, mas não o elimina. Você continua responsável pela segurança da página e dos scripts onde o cliente digita os dados. Veja Requisitos de segurança.


Testes em sandbox

Faça toda a integração no ambiente sandbox (https://api.sandbox.paytime.com.br) antes de pedir as credenciais de produção. Valide pelo menos:

  • um cartão aprovado na validação Zero Dollar, com o token gerado e usado numa transação;
  • um cartão recusado na validação, com a mensagem correta exibida ao cliente;
  • o tratamento dos erros do SDK, como número ou validade inválidos;

Inclua essas evidências no Roteiro de Homologação.



Cartões de teste para usar no SDK

Para testar a integração do SDK usando cartões de teste, disponibilizamos uma lista que permite simular diversos cenários em sua aplicação.

Cartão de teste Bandeira Respostas
Número: 4539620659922097
Cód. de Seg.: 123
Data Exp.:12/2030
VISA Autorização bem-sucedida.
Número: 4929291898380766
Cód. de Seg.: 123
Data Exp.:12/2030
VISA Autorização negada.
Número: 5240082975622454
Cód. de Seg.: 123
Data Exp.:12/2030
MASTERCARD Autorização bem-sucedida.
Número: 5530062640663264
Cód. de Seg.: 123
Data Exp.:12/2030
MASTERCARD Autorização negada.
Número: 4514161122113757
Cód. de Seg.: 123
Data Exp.:12/2030
ELO Autorização bem-sucedida.
Número: 4389350446134811
Cód. de Seg.: 123
Data Exp.:12/2030
ELO Autorização negada.
🚧

Números fictícios

Todos os números de cartões de créditos na tabela são fictícios e não devem ser utilizados no ambiente Produção.




Did this page help you?