Cria um token representando as informações do cartão de pagamento fornecidas.
POST /v2/tokenization · versão da spec v2 · coleção Postman e spec
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Idempotency-Key | header | string | não | TOK-S09: chave opaca escolhida pelo cliente, escopada por tenant, até 255 caracteres. Opcional - sem ela, o comportamento é o de sempre. |
Corpo da requisição
application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
buyerId | string (uuid) | sim | |
pan | string | sim | |
expirationMonth | integer (int32) | sim | |
expirationYear | integer (int32) | sim | |
cvv | string | sim | |
cardholderName | string | não | |
cardholderDocument | string | não | |
ttlHours | integer (int32) | não |
Respostas
| Status | Descrição | Formato |
|---|---|---|
| 200 | Sucesso. Se a resposta for o replay de uma Idempotency-Key já concluída, o cabeçalho Idempotent-Replayed vem "true" e o corpo é o mesmo token já tokenizado - nenhuma tokenização nova acontece. | application/json |
| 400 | Bad Request | application/json |
| 401 | Unauthorized | application/json |
| 403 | Forbidden | application/json |
| 404 | Not Found | application/json |
| 409 | TOK-S09: conflito de Idempotency-Key. O code em errors[] distingue IDEMPOTENCY_IN_PROGRESS (outra requisição com a mesma chave ainda em andamento; aguardar Retry-After e repetir) de IDEMPOTENCY_KEY_REUSED (mesma chave, corpo de requisição diferente; o cliente deve usar uma chave nova). | application/json |
| 422 | Erro de validação dos dados do cartão. | application/json |
| 500 | Internal Server Error | sem corpo |
Respostas de erro seguem o Problem Details (RFC 9457): trate pelo campo code e consulte o catálogo de erros.
Exemplo
curl -X POST "https://api-payments.sand-fintech.com/v2/tokenization" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @corpo.json