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.
| Etapa | O que acontece | Onde |
|---|---|---|
| 1. Obter a chave pública | Seu backend consulta a chave pública na Paytime e a repassa ao frontend. | Backend → API Paytime |
| 2. Criptografar o cartão | O frontend usa o SDK da PagBank e a chave pública para gerar o encrypted_card. | Frontend → SDK PagBank |
| 3. Validar e tokenizar | Seu 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-keyex-token. Veja Credenciais de acesso. - Token de autenticação: todas as chamadas desta página exigem o header
Authorization: Bearer {token}, gerado emPOST /v1/auth/logine 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).
| Ambiente | URL base |
|---|---|
| Sandbox | https://api.sandbox.paytime.com.br |
| Produção | https://api.paytime.com.br |
Headers usados nas etapas 1 e 3
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Authorization | string | Sim | Bearer {token} obtido em POST /v1/auth/login. |
integration-key | string | Sim | Chave de integração do parceiro. |
x-token | string | Sim | Token disponível na aba Integração do Gestor. |
establishment_id | string | Sim | ID do estabelecimento ao qual o cartão será vinculado. |
Content-Type | string | Etapa 3 | application/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"
}| Campo | Tipo | Descrição |
|---|---|---|
public_key | string | Chave 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()
PagSeguro.encryptCard()| Parâmetro | Tipo | Descrição |
|---|---|---|
publicKey | string | Valor de public_key obtido na Etapa 1. |
holder | string | Nome do titular, como impresso no cartão. |
number | string | Número do cartão, só dígitos. |
expMonth | string | Mês de validade, de 1 a 12. |
expYear | string | Ano de validade com 4 dígitos, por exemplo 2030. |
securityCode | string | Có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:
| Campo | Tipo | Descrição |
|---|---|---|
encryptedCard | string | Cartão criptografado. É o valor enviado na Etapa 3, no campo encrypted_card. |
hasErrors | boolean | Indica se houve erro na criptografia. |
errors | array | Lista 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ódigo | Significado | Sugestão de mensagem ao cliente |
|---|---|---|
INVALID_NUMBER | Número do cartão inválido. | Confira o número do cartão. |
INVALID_SECURITY_CODE | Código de segurança precisa ter 3 ou 4 dígitos. | Confira o código de segurança. |
INVALID_EXPIRATION_MONTH | Mês precisa estar entre 1 e 12. | Confira o mês de validade. |
INVALID_EXPIRATION_YEAR | Ano precisa ter 4 dígitos. | Confira o ano de validade. |
INVALID_PUBLIC_KEY | Chave pública inválida. | Erro técnico: obtenha a chave novamente (Etapa 1). |
INVALID_HOLDER | Nome do titular inválido. | Confira o nome impresso no cartão. |
Atenção
- O
encryptedCardnã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
encryptedCardna 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:
- valida a requisição e o estabelecimento;
- faz a validação Zero Dollar do cartão na PagBank, sem cobrança;
- se o cartão for aprovado, armazena-o com segurança via PagBank e devolve o
tokene os dados não sensíveis do cartão.
POST/v1/marketplace/cards/tokenize
Body
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
encrypted_card | string | Sim | Valor de encryptedCard gerado pelo SDK na Etapa 2. |
holder_document | string | Não | CPF 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"
}| Campo | Tipo | Descrição |
|---|---|---|
token | string | Token do cartão. Guarde-o para capturar transações futuras, no campo card.token. |
brand_name | string | Bandeira do cartão, por exemplo MASTERCARD ou VISA. |
bin | string | Seis primeiros dígitos do cartão. |
last4_digits | string | Quatro últimos dígitos do cartão. |
holder_name | string | Nome do titular, como informado na criptografia. |
expiration_month | string | Mês de validade. |
expiration_year | string | Ano de validade. |
_id | string | Identificador do cartão armazenado na Paytime. |
DicaUse
brand_nameelast4_digitspara mostrar o cartão salvo ao cliente (por exemplo, “Mastercard final 8884”). Guarde tambémexpiration_montheexpiration_yearpara avisar o cliente antes de o cartão vencer.
Respostas de erro
| Status | Situação | O que fazer |
|---|---|---|
400 | Requisiçã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). |
401 | Token Bearer ausente, inválido ou expirado. | Gere um novo token em POST /v1/auth/login. |
4xx | Cartã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. |
500 | Erro 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-tokene 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íciosTodos 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.
Updated 9 days ago