Tokenização

Troque dados sensíveis do cartão por um token seguro.

Dados brutos de cartão são aceitos apenas aqui. Charges recebem `card_token`; PAN e CVV são descartados antes do fluxo de cobrança.

Fronteira PCI

sk_test_ / sk_live_: são chaves server-side e nunca devem ir para código frontend.
pk_test_ / pk_live_: serão usadas futuramente no browser com allowlist de origem.
Tokenização exige API key seller-scoped e KYC aprovado pela white label. Caso contrário, a API retorna `seller_kyc_required`.
POST /charges rejeita card, number, cvv e cvc. Com `card_token`, `security_code` (CVV) é permitido apenas na cobrança e nunca é persistido.

POST/payment-methods/tokenize

Tokenizar método de pagamento

Troca dados sensíveis do cartão por um token `tok_`. Este é o único endpoint público que aceita PAN/CVV. Exige API key seller-scoped com KYC aprovado.

Auth: Bearer API keypayment_methods:tokenize

Parâmetros e body

Campo	Tipo	Descrição
`card.number`obrigatório	string	PAN do cartão, descartado depois da tokenização. Aceita dígitos com ou sem espaços/hífens.
`card.exp_month`obrigatório	integer	Mês de expiração.
`card.exp_year`obrigatório	integer	Ano de expiração.
`card.cvv`obrigatório	string	CVV/CVC, nunca persistido.
`card.holder_name`obrigatório	string	Nome impresso no cartão.
`billing_address`	object	Endereço de cobrança opcional.
`metadata`	object	Metadados do integrador.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Token público com prefixo `tok_`.
`object`	string	`payment_method_token`.
`brand`	string	Bandeira detectada.
`last4`	string	Apenas os quatro últimos dígitos.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

curl -X POST https://wl.zedy.com.br/api/v1/payment-methods/tokenize \  -H "Authorization: Bearer sk_test_xxx" \  -H "Content-Type: application/json" \  -d '{  "card": {    "number": "4242 4242 4242 4242",    "exp_month": 12,    "exp_year": 2030,    "cvv": "123",    "holder_name": "Ada Lovelace"  }}'

Resposta

{  "id": "tok_xxx",  "object": "payment_method_token",  "type": "card",  "brand": "visa",  "last4": "4242",  "exp_month": 12,  "exp_year": 2030,  "livemode": false,  "request_id": "req_xxx"}

Use o token em uma charge

Criar charge de cartão

curl -X POST https://wl.zedy.com.br/api/v1/charges \  -H "Authorization: Bearer sk_test_xxx" \  -H "Idempotency-Key: charge_123" \  -H "Content-Type: application/json" \  -d '{    "amount": 10990,    "currency": "BRL",    "payment_method": "CREDIT_CARD",    "card_token": "tok_xxx"  }'

Rejeição de cartão bruto

{  "error": {    "type": "validation_error",    "code": "raw_card_not_allowed",    "message": "Raw card data is not accepted on this endpoint. Use payment method tokenization first.",    "request_id": "req_xxx"  }}