Tokenize um cartão

A tokenização troca os dados do cartão por um identificador reutilizável, o cardTokenUid (ctok_…). Você grava esse identificador junto ao cliente no seu sistema e o usa no lugar do número do cartão nas próximas cobranças. Criar um token não cobra nada: cada pagamento continua sendo uma cobrança criada explicitamente pelo seu servidor.

Crie o tokenCopiar link da seção

curl -X POST "$DM_API_BASE/api/v1/card-tokens" \
  -H "Authorization: $DM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cliente-1001-cartao-tentativa-1" \
  -d '{
    "card": {
      "number": "5555555555554444",
      "expMonth": 12,
      "expYear": 2030,
      "cvv": "123",
      "holderName": "MARIA SOUZA"
    },
    "customerId": "cliente-1001"
  }'

RespostaCopiar link da seção

{
  "cardTokenUid": "ctok_01M0FVG11PZK94T569VFYE4FY3",
  "brand": "MASTERCARD",
  "bin": "555555",
  "last4": "4444",
  "expMonth": 12,
  "expYear": 2030,
  "status": "ACTIVE",
  "cvvStored": true,
  "deduplicated": false
}

Cartão já tokenizadoCopiar link da seção

Se o mesmo cartão já tiver um token ativo para o mesmo customerId na sua conta, a API não cria outro: responde 200 OK com o token existente e deduplicated: true. Um token novo responde 201 Created.

Três detalhes desse reaproveitamento:

• Sem customerId, todos os cartões da conta são tratados como de um mesmo cliente. O mesmo cartão enviado duas vezes sem customerId devolve o mesmo token. Envie sempre customerId se a sua base tem clientes diferentes.
• A validade não é atualizada. Um cartão renovado (mesmo número, validade nova) devolve o token antigo com a validade antiga. Compare expMonth/expYear da resposta com o que o comprador digitou.
• O código de segurança é substituído. Se você enviar cvv, ele passa a ser o guardado.

Cobre com o tokenCopiar link da seção

Na criação da cobrança, troque os dados do cartão por card.token. O restante da compra continua igual: comprador, split, valor, moeda e sessão 3DS.

"paymentMethods": [{
  "type": "CreditCard",
  "amount": 10000,
  "card": { "token": "ctok_01M0FVG11PZK94T569VFYE4FY3" }
}]

• Use o token na mesma conta em que ele foi criado.
• Se o token e os dados do cartão vierem juntos, o token vence e os outros campos são ignorados. Para trocar de cartão, crie outro token.
• Na requisição o campo é card.token. cardTokenUid aparece só nas respostas e nos webhooks, dentro de paymentMethods[].card.
• Um token inválido não faz a API tentar outro instrumento automaticamente.

Erros ao cobrar com tokenCopiar link da seção

Idempotência da tokenizaçãoCopiar link da seção

A tokenização tem regras próprias, diferentes das da criação de cobrança:

Erros de validação e falhas de indisponibilidade não consomem a chave: repetir com a mesma chave executa de novo.

Erros da tokenizaçãoCopiar link da seção

Esta rota responde erros num envelope próprio, com code e message:

{
  "code": "validation_failed",
  "message": "Field 'card.cvc' is not supported; use 'card.cvv' for the card security code."
}

Não exponha ao comprador a resposta técnica. Oriente-o a revisar o cartão ou escolher outro meio de pagamento, e guarde o código, o id do PaymentIntent e a chave de idempotência para diagnóstico.