Tokenization

Exchange raw card data for a safe token.

Raw card data is accepted only here. Charges receive `card_token`; PAN and CVV are discarded before the charge flow.

PCI boundary

sk_test_ / sk_live_: are server-side keys and must never ship in frontend code.
pk_test_ / pk_live_: will be used by browser tokenization with origin allowlists.
Tokenization requires a seller-scoped API key and seller KYC approved by the whitelabel. Otherwise the API returns `seller_kyc_required`.
POST /charges rejects card, number, cvv and cvc. With `card_token`, `security_code` (CVV) is allowed at charge time only and is never persisted.

POST/payment-methods/tokenize

Tokenize payment method

Exchanges raw card data for a `tok_` token. This is the only public endpoint that accepts PAN/CVV. Requires a seller-scoped API key with approved seller KYC.

Auth: Bearer API keypayment_methods:tokenize

Parameters and body

Field	Type	Description
`card.number`required	string	PAN, discarded after tokenization. Digits with or without spaces/hyphens are accepted.
`card.exp_month`required	integer	Expiration month.
`card.exp_year`required	integer	Expiration year.
`card.cvv`required	string	CVV/CVC, never persisted.
`card.holder_name`required	string	Cardholder name.
`billing_address`	object	Optional billing address.
`metadata`	object	Integrator metadata.

Response fields

Field	Type	Description
`id`	string	`tok_` public token.
`object`	string	`payment_method_token`.
`brand`	string	Detected card brand.
`last4`	string	Last four digits only.
`request_id`	string	Request trace id.

Request examples

curl -X POST https://bunne.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"  }}'

Response

{  "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 the token in a charge

Create card charge

curl -X POST https://bunne.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"  }'

Raw card rejection

{  "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"  }}