Skip to main content
POST
Salvar cartão
A resposta é sempre 202 Accepted: a tokenização roda em segundo plano. Acompanhe o campo tokenization_status (pending, tokenized ou failed) com GET /v2/cards/{id}.
Guarde o id retornado e use-o como card.token em pedidos, assinaturas e faturas. Um cartão com tokenização pending ou failed continua podendo ser usado em compras.
customer.document é obrigatório (cpf, cnpj ou passport), e customer.phone.ddi e customer.phone.ddd são números inteiros. Um cartão vencido retorna 422 com param card.exp_year.
Limite de 10 cartões por minuto por conta (429 card_tokenization_rate_limited). Cartão, e-mail ou documento bloqueado retorna 403 (customer_blocked).

Authorizations

Authorization
string
header
required

Chave de API (secret key) da conta, no formato sk_live_... (produção) ou sk_test_... (Dev mode). Envie no header Authorization: Bearer <chave>. Autentica todas as rotas da API v2 e as rotas de Análise de Fraude. A chave identifica a conta, então a API v2 não usa o header account. Uma chave só é aceita no ambiente em que foi criada. Gere a sua no dashboard em Configurações → Chaves de API.

Headers

Idempotency-Key
string

Chave de idempotência opcional e recomendada. Tem até 128 caracteres e vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a resposta original (mesmo status e mesmo corpo), sem processar de novo. Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode ser reutilizada. A mesma chave com um corpo diferente retorna 422 (idempotency_key_conflict), uma requisição original ainda em andamento retorna 409 (idempotency_key_in_use) e uma chave com mais de 128 caracteres retorna 400 (idempotency_key_invalid).

Maximum string length: 128
Example:

"pedido-1024-tentativa-1"

Body

application/json
customer
object
required

Dados do comprador, com documento obrigatório. A API v2 não tem recurso de cliente: envie o comprador em cada requisição.

card
object
required

Response

Cartão salvo, tokenização iniciada

Cartão salvo. O número completo e o código de segurança nunca são devolvidos

id
string<uuid>

Use este valor como card.token em pedidos, assinaturas e faturas

Example:

"9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f"

object
enum<string>
Available options:
card
brand
string
Example:

"visa"

first_six
string
Example:

"411111"

last_four
string
Example:

"1111"

holder_name
string
Example:

"João Silva"

exp_month
integer
Example:

12

exp_year
integer
Example:

2030

type
enum<string> | null
Available options:
credit,
debit
tokenization_status
enum<string>

pending: tokenização em andamento. tokenized: concluída. failed: nenhuma adquirente conseguiu tokenizar. Um cartão com failed ainda pode ser usado em compras.

Available options:
pending,
tokenized,
failed
customer
object
created_at
string
Example:

"2026-09-14T12:00:00-03:00"