Tokenização pública de cartão

Tokenização de cartão direto do navegador

Use este endpoint quando o formulário de cartão roda no site do parceiro e você quer trocar os dados do cartão por um token sem passar o cartão pelo seu servidor. A cobrança continua sendo feita pelo seu backend, com a sua API key, usando o token recebido.

Endpoint

POST https://<host-da-api-syncpay>/api/public/v1/card-tokens

Não usa Authorization. A identificação do seu negócio vem só do header X-Public-Key.

Antes de usar

No painel da SyncPay, abra API → Chave pública.

Copie a sua chave pública (começa com pk_live_). Ela pode ser exposta no front-end, mas só funciona nos domínios cadastrados. Se precisar trocar, use "Regenerar": a anterior deixa de valer na hora.

Cadastre cada domínio do seu site em Domínios permitidos, no formato https://loja.com (esquema + host, porta opcional). Sem caminho, sem barra no final. Em desenvolvimento, http://localhost e http://127.0.0.1 são aceitos. Limite de 10 domínios por conta.

A conta precisa estar apta a usar cartão pela API (mesmas exigências da rota POST /api/partner/v1/card-tokens).

Headers

Header	Obrigatório	Valor
`X-Public-Key`	sim	sua chave pública `pk_live_...`
`Content-Type`	sim	`application/json`
`Origin`	sim	enviado pelo navegador; precisa ser um dos domínios cadastrados

Corpo

Igual ao da rota partner POST /api/partner/v1/card-tokens:

{
  "card": {
    "number": "4111111111111111",
    "holder_name": "MARIA S SILVA",
    "expiry_month": "12",
    "expiry_year": "2030",
    "cvv": "123"
  }
}

number: 13 a 19 dígitos, válido no algoritmo de Luhn.

holder_name: até 255 caracteres.

expiry_month: 01 a 12. expiry_year: 4 dígitos (2 dígitos, como 30, são completados para 2030). Cartão vencido é recusado.

cvv: 3 ou 4 dígitos.

Resposta de sucesso (`201`)

{
  "data": {
    "token": "card_token.<token-opaco>",
    "brand": "visa",
    "last4": "1111",
    "expires_at": "2026-10-15T18:30:00.000000Z"
  }
}

Use o data.token na criação da cobrança de cartão pelo seu backend, como já faz com os tokens da rota partner. O token expira em expires_at (data ISO 8601 em UTC).

Erros

Status	Quando	Corpo
`401`	`X-Public-Key` ausente ou desconhecida	`{"message": "Chave pública inválida."}`
`403`	Qualquer outra recusa: origem fora da lista, sem `Origin`, nenhum domínio cadastrado, conta sem permissão para cartão	`{"message": "Chave pública ou origem não autorizada."}`
`422`	Dados do cartão inválidos	`{"message": "...", "errors": {"card.number": ["O número do cartão é inválido."]}}`
`429`	Limite de requisições excedido	`{"message": "Muitas requisiçoes foram detectadas. Tente novamente em 10 minutos.", "error": "rate_limit_exceeded"}`, com header `Retry-After` quando disponível

O 403 é propositalmente igual para todas as causas: ele não diz qual trava falhou.

Limites de uso

20 requisições por minuto para a mesma chave a partir do mesmo IP.

60 requisições por minuto por IP, somando todas as chaves.

Ao receber 429, espere o tempo do header Retry-After antes de tentar de novo.

CORS

O navegador faz uma requisição de pré-voo (OPTIONS) antes do POST; ela é respondida automaticamente com 204. A resposta do POST só pode ser lida pelo seu site se o Origin estiver na lista de domínios permitidos. Se o domínio não estiver cadastrado, o navegador bloqueia a leitura da resposta e o POST volta 403. Não há cookies nem credenciais nessa chamada: não use credentials: 'include'.

Tokenização pública de cartão

Tokenização de cartão direto do navegador#

Endpoint#

Antes de usar#

Headers#

Corpo#

Resposta de sucesso (201)#

Erros#

Limites de uso#

CORS#

Exemplo mínimo (fetch)#