Skip to main content
POST
Salvar cartão
Requer o header account com o código da conta. O cartão é salvo para o cliente informado no clientCode e a tokenização é iniciada automaticamente.
A resposta retorna imediatamente com tokenization_status: "pending". O resultado da tokenização é entregue de forma assíncrona por webhook — você não precisa fazer polling. Envie o header opcional Idempotency-Key para evitar cadastros duplicados em caso de retentativa.

Ciclo de tokenização

Acompanhe a disponibilidade do cartão pelos eventos de webhook: Enquanto o tokenization_status estiver pending, o cartão ainda está sendo preparado. Aguarde o card.token_created antes de usá-lo em uma cobrança.

Usando o cartão salvo

O campo card_token (presente na resposta e no evento card.token_created) é o identificador que você envia em payment.card.card_token ao criar uma cobrança ou pedido com o cartão salvo.
Billing Address — o billing address do cartão não é tokenizado. Ao criar um pedido/cobrança com card_token, você também precisa informar o billing address (client.address) na requisição.
O número completo (PAN) e o código de segurança (CVV) nunca são retornados. A resposta expõe apenas first_six_digits e last_four_digits.

Authorizations

Authorization
string
header
required

Token JWT obtido via POST /v1/login. Envie no header Authorization: Bearer <token>.

Headers

account
string
required

Código da conta à qual a operação se aplica

Example:

"acc_abc123xyz"

Idempotency-Key
string

Chave de idempotência para evitar cadastros duplicados (máx. 128 caracteres)

Example:

"a1b2c3d4-idem-key"

Path Parameters

clientCode
string
required

Código único do cliente dono do cartão

Example:

"cli_abc123"

Body

application/json
name
string
required

Nome do portador impresso no cartão

Maximum string length: 255
Example:

"Tony Stark"

number
string
required

Número do cartão (13–19 dígitos, validado por Luhn)

Example:

"5425011234567793"

month
integer
required

Mês de validade

Required range: 1 <= x <= 12
Example:

1

year
integer
required

Ano de validade (2 ou 4 dígitos; deve estar no futuro)

Example:

2030

security_code
string
required

Código de segurança (CVV, 3 ou 4 dígitos)

Example:

"123"

type
enum<string>
default:credit

Tipo do cartão

Available options:
credit,
debit
Example:

"credit"

flag
enum<string>

Bandeira do cartão (opcional)

Available options:
visa,
mastercard,
elo,
amex
Example:

"mastercard"

Response

Cartão recebido; tokenização iniciada

mensagem
string
Example:

"Cartão recebido. A tokenização foi iniciada; o resultado será enviado por webhook."

erro
boolean
Example:

false

mensagenserro
string[]
Example:
codigoretorno
integer
Example:

201

id
string
Example:

"00000000-0000-0000-0000-000000000000"

data
object