PayZu GatewayClientes e cartões

Tokenização no navegador


Nesta páginaCarregue o scriptGere o tokenParâmetros do encryptCobre com o tokenErros do script

Carregue o script da PayZu na página de pagamento e gere o token do cartão com a chave de tokenização, sem que o cartão passe aberto pelo seu servidor.

Carregue o script

html
<script src="https://static.gateway.payzu.com.br/scripts/gateway.min.js"></script>

O script é o mesmo para todas as contas, carrega sem chave e registra window.PayZuGateway, com as funções init e encrypt.

RequisitoRegra
PáginaEm HTTPS, a não ser em localhost.
NavegadorA partir do Chrome 92, do Firefox 95 ou do Safari 15.4.
Content-Security-PolicyInclua https://static.gateway.payzu.com.br em script-src. O script não precisa de 'unsafe-eval' nem de 'wasm-unsafe-eval'.

Sem HTTPS ou num navegador mais antigo, o script não registra window.PayZuGateway ou init falha. Confira os dois requisitos antes de pedir o cartão.

Gere o token

Chame init com a chave de tokenização e depois encrypt com o cartão que o comprador digitou. As duas funções retornam uma Promise, e encrypt resolve com o token em texto.

html
<head>
  <script src="https://static.gateway.payzu.com.br/scripts/gateway.min.js"></script>
</head>
<script>
  PayZuGateway.init('CHAVE_DE_TOKENIZACAO')
    .then(() => PayZuGateway.encrypt({
      number: '4111111111111111',
      holder: 'MARIA SOUZA',
      expMonth: '12',
      expYear: '2030',
      cvv: '123',
    }))
    .then((token) => fetch('/pagamento', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    }))
    .catch((error) => console.error(error.code, error.field, error.description));
</script>

Uma chave inválida em init apaga a chave anterior.

Depois disso, encrypt falha como antes do primeiro init, até um init que dê certo.

Parâmetros do encrypt

ParâmetroFormatoObrigatório?
numberNúmero do cartão, de 13 a 19 dígitos. Espaços e hifens são ignorados.Sim
holderNome impresso no cartão, de 1 a 64 caracteres.Sim
expMonthMês da validade, com 2 dígitos, de "01" a "12".Sim
expYearAno da validade, com 4 dígitos, como "2030".Sim
cvvCódigo de segurança, com 3 ou 4 dígitos, conforme a bandeira.Sim

Todos os campos são texto, e os espaços das pontas são ignorados. Antes de gerar o token, o script confere o número, a bandeira (Visa, Mastercard, Elo, Diners ou Hipercard), a validade e o tamanho do CVV, com as mesmas regras da cobrança.

O token vale 15 minutos a partir da hora do relógio do aparelho e serve para uma operação só.

Com o relógio do aparelho adiantado mais de um minuto, a cobrança responde 400. Com o relógio atrasado, o token vale menos.

Cobre com o token

O seu servidor envia o token em payment.credit_card.card_token ao criar uma fatura, com a chave de API. O mesmo token serve também para as outras operações listadas em O token.

Corpo de POST /v1/invoices
{
  "description": "Pedido 1234",
  "external_reference": "pedido-1234",
  "amount": 15990,
  "customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
  "payment": {
    "method": "credit_card",
    "credit_card": {
      "card_token": "<token gerado>",
      "installments": 1
    }
  }
}

Gere um token novo para cada operação nova.

Um token já usado ou vencido responde 400. A repetição da mesma fatura com a mesma Idempotency-Key segue as regras de Idempotência.

Erros do script

Os erros acontecem no navegador, antes de qualquer chamada à API, e rejeitam a Promise com um PaymentError.

Campo do erroO que traz
codeO código da tabela abaixo.
descriptionA mensagem, para mostrar junto do campo indicado em field.
fieldnumber, holder, expMonth, expYear ou cvv, quando o erro é de um campo.
CódigoMensagem
PZ210Chave de tokenização ausente ou inválida. Use a chave do painel, em Desenvolvedor.
PZ211Chame init(pk) antes de encrypt().
PZ212Não foi possível iniciar a cifra do cartão nesta página. Use HTTPS e um navegador atualizado.
PZ213Número do cartão inválido.
PZ214Bandeira do cartão não aceita.
PZ215Informe o nome impresso no cartão, com até 64 caracteres.
PZ216Mês de validade inválido. Use dois dígitos, de 01 a 12.
PZ217Ano de validade inválido.
PZ218Cartão vencido.
PZ219CVV inválido.