> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Emitir token de autenticação
> O token que autoriza o navegador a rodar o desafio de autenticação do portador.
Peça o token no **envio** do formulário, nunca na abertura da página. Ele vive cinco minutos;
emitido cedo, já estaria morto para quem levou algum tempo preenchendo o endereço — e a falha só
aparece depois de o desafio abrir.
**Não é idempotente, e isso é deliberado.** Cada tentativa de pagamento precisa de um token novo:
devolver o anterior entregaria um já queimado no desafio que falhou. Mandar `Idempotency-Key` não
muda nada.
O que o desafio devolve ao seu JavaScript — o identificador da autenticação e o `transStatus` — segue
em `card.three_ds` na [criação da cobrança](/api-reference/cobrancas/criar). Perdê-lo no caminho
significa ter incomodado o comprador com um desafio e pagado a contestação assim mesmo. Ver
[Autenticação do portador](/essenciais/autenticacao-do-portador).
## OpenAPI
````yaml api-reference/openapi.yaml POST /v1/three_ds_tokens
openapi: 3.1.0
info:
title: Vext - API de pagamentos PIX com split
version: 1.0.0
summary: Cobranças PIX, estornos e saldo do vendedor.
description: |
API pública do gateway. Todo endpoint desta versão vive sob `/v1`.
## Dinheiro é sempre CENTAVOS INTEIROS
Não há exceção. `amount`, `platform_fee`, `net_amount`, `refunded_amount`,
`fee_returned`, `seller_debit`, `balance`, `available`, `reserved`, `debt`
e `withdrawable` são inteiros em centavos de real.
| Valor | Envie / receba |
|-------------|----------------|
| R$ 1,00 | `100` |
| R$ 10,50 | `1050` |
| R$ 1.234,56 | `123456` |
Enviar `10.50` devolve `422`. A recusa é deliberada: `10.50` chega ao
servidor como ponto flutuante, `10.50 * 100` não é exatamente `1050` em
binário, e o centavo perdido só aparece na conciliação do mês. Diante de
um decimal preferimos recusar a adivinhar a intenção - com dinheiro,
adivinhar sai caro.
## Autenticação
Toda chamada leva a chave no header:
```
Authorization: Bearer sk_live_SUA_CHAVE_SECRETA
```
A chave é criada em **Desenvolvedores** no painel e o valor em claro
aparece **uma única vez**, na criação - guardamos apenas um hash
SHA-256. Perdeu, gere outra.
Cada chave carrega escopos (`charges:read`, `charges:write`,
`refunds:write`, `balance:read`, `cards:manage`). Chamar um endpoint
fora do escopo devolve `403`, e não `401`: a chave está certa, faltou
permissão.
Chaves de teste usam o prefixo `sk_test_`. A diferença é visível a olho
nu de propósito - uma chave de teste colada em produção precisa ser
reconhecível antes de alguém passar a tarde investigando.
## Idempotência
Envie `Idempotency-Key` em todo `POST`. A conexão que cai depois da
requisição e antes da resposta deixa você sem saber se cobrou; repetir
com a mesma chave resolve isso sem risco de cobrar duas vezes.
- **mesma chave, mesmo corpo** → a resposta gravada, com
`Idempotent-Replayed: true`. A cobrança não é recriada.
- **mesma chave, corpo diferente** → `409 idempotency_key_reused`.
Devolver a cobrança antiga faria você acreditar que cobrou o valor
novo.
- **mesma chave, primeira ainda em voo** → `409
idempotency_key_in_progress`. Repita em instantes.
A ordem dos campos no JSON não invalida o retry. A chave vale por 24
horas e é sua: dois clientes diferentes podem usar `pedido-1` sem
colidir.
## Erros
Todo erro - inclusive os que não previmos - tem a mesma forma:
```json
{
"error": {
"type": "invalid_request_error",
"code": "amount_below_minimum",
"message": "…",
"details": {}
}
}
```
Trate pelo `code`, nunca pela `message`: o código é contrato, o texto
pode ser reescrito a qualquer momento.
contact:
name: Suporte Vext
url: https://wa.me/5511936185272
servers:
- url: https://api.usevext.com
description: Produção
security:
- apiKey: []
tags:
- name: Cobranças
description: Criação, consulta e estorno de cobranças, no PIX e no cartão.
- name: Saldo
description: Quanto o vendedor tem e quanto pode sacar.
- name: Cartão no navegador
description: |
O que o navegador do comprador precisa para virar um formulário de
cartão: a credencial de tokenização e o token do desafio de
autenticação. O número do cartão nunca passa por esta API.
- name: Cartões
description: |
Os cartões que os compradores deixaram guardados, para cobrar de novo
sem pedir nada a eles.
paths:
/v1/three_ds_tokens:
post:
tags:
- Cartão no navegador
summary: Emitir token de autenticação
description: |
O token que autoriza o navegador a rodar o desafio de autenticação do
portador contra o servidor da Stone. Sem corpo.
**POST e não GET**: cada chamada gasta um token de uso único e de
prazo curto, e um GET seria pré-buscado por navegador e por
antivírus - todos morrendo antes de alguém tentar pagar.
Peça-o no **envio** do formulário, nunca na abertura da página. Ele
vive cinco minutos; emitido cedo, já estaria morto para quem levou
algum tempo preenchendo o endereço.
**Não é idempotente, e isso é deliberado.** Repetir aqui é o
comportamento certo: cada tentativa de pagamento precisa de um token
novo, e devolver o anterior entregaria um já queimado no desafio que
falhou. Mandar `Idempotency-Key` não muda nada.
O que o desafio devolve ao seu JavaScript - o identificador da
autenticação e o status - segue em `card.three_ds` na criação da
cobrança.
operationId: createThreeDsToken
responses:
'200':
description: O token, válido por cinco minutos e para um uso só.
content:
application/json:
schema:
$ref: '#/components/schemas/ThreeDsToken'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
description: |
Esta conta não autentica o portador. Ao contrário do que a porta
do navegador faria, aqui o motivo vem junto - quem lê é o seu
servidor, e o motivo é acionável.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
indisponivel:
value:
error:
type: invalid_request_error
code: three_ds_unavailable
message: Esta conta não pode autenticar o portador no momento.
details:
reason: fee_disabled
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/PlatformUnavailable'
security:
- apiKey:
- charges:write
components:
schemas:
ThreeDsToken:
type: object
description: |
O token do desafio. De uso único e de prazo curto: peça um por
tentativa de pagamento, no envio do formulário.
required:
- object
- token
- script_url
- expires_in
properties:
object:
type: string
const: three_ds_token
token:
type: string
description: O JWT que o navegador apresenta ao servidor 3DS.
script_url:
type: string
format: uri
description: |
A biblioteca do **mesmo ambiente** do token. Rodar a de produção
com um token de sandbox devolve um erro que não diz nada sobre a
troca - por isso os dois viajam juntos.
expires_in:
type: integer
description: Segundos de vida do token, a partir da emissão.
example: 300
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
- details
properties:
type:
type: string
description: |
Família do erro. Responde "de quem é o problema e o que
fazer": `invalid_request_error` se corrige mudando a
chamada, `authentication_error` trocando a chave, e
`api_error` é nosso - repita, não reescreva.
enum:
- authentication_error
- permission_error
- invalid_request_error
- idempotency_error
- not_found_error
- rate_limit_error
- api_error
- card_error
code:
type: string
description: |
Código estável do erro. **Trate por ele.** A `message` pode
ser reescrita a qualquer momento; o código, não.
message:
type: string
description: Explicação em português, para leitura humana.
details:
type: object
description: |
Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
campos recusados e suas mensagens.
additionalProperties: true
responses:
Unauthorized:
description: |
Chave ausente, desconhecida, revogada ou expirada. A revogada é
distinguida da inexistente na MENSAGEM, nunca no status: quem
integra precisa saber que a chave existiu e foi desligada, e quem
está adivinhando tokens não aprende nada com isso.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ausente:
summary: missing_api_key
value:
error:
type: authentication_error
code: missing_api_key
message: 'Envie a chave em Authorization: Bearer sk_live_...'
details: {}
invalida:
summary: invalid_api_key
value:
error:
type: authentication_error
code: invalid_api_key
message: Chave de API inválida.
details: {}
revogada:
summary: revoked_api_key
value:
error:
type: authentication_error
code: revoked_api_key
message: >-
Esta chave de API foi revogada. Gere uma nova em
Desenvolvedores.
details: {}
expirada:
summary: expired_api_key
value:
error:
type: authentication_error
code: expired_api_key
message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
details: {}
Forbidden:
description: |
A chave é válida, mas não tem o escopo do endpoint. `403` e não
`401` de propósito: `401` diria "sua chave está errada" a quem tem
a chave certa.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
escopo:
summary: insufficient_scope
value:
error:
type: permission_error
code: insufficient_scope
message: Esta chave não tem o escopo [refunds:write].
details:
required_ability: refunds:write
abilities:
- charges:read
- charges:write
umClique:
summary: one_click_requires_three_ds
value:
error:
type: permission_error
code: one_click_requires_three_ds
message: >-
Esta loja exige autenticação do portador, e o pagamento de
um clique não a suporta.
details: {}
RateLimited:
description: |
Requisições demais.
Há três limites, por minuto: um por IP antes da autenticação, e
depois um de leitura e um de escrita, ambos por CHAVE - o excesso
de uma integração não consome a cota das outras do mesmo
vendedor. A escrita é bem mais apertada porque cada cobrança
criada vira uma chamada ao provedor.
`Retry-After` diz em quantos segundos voltar. Os cabeçalhos
`X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
permitem desacelerar antes de bater no limite.
headers:
Retry-After:
description: Segundos até a cota ser reposta.
schema:
type: integer
X-RateLimit-Limit:
description: Requisições permitidas por minuto neste balde.
schema:
type: integer
X-RateLimit-Remaining:
description: Quantas ainda cabem no minuto corrente.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cota:
summary: too_many_requests
value:
error:
type: rate_limit_error
code: too_many_requests
message: Muitas requisições. Tente novamente em 42 segundos.
details:
retry_after: 42
provedor:
summary: provider_rate_limited
value:
error:
type: rate_limit_error
code: provider_rate_limited
message: >-
Limite de requisições do provedor atingido. Tente novamente
em instantes.
details: {}
InternalError:
description: |
Erro inesperado do nosso lado. Repita com a mesma
`Idempotency-Key` - ela é o que torna repetir seguro.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
interno:
value:
error:
type: api_error
code: internal_error
message: >-
Erro interno. Se persistir, informe o horário da chamada ao
suporte.
details: {}
PlatformUnavailable:
description: |
A plataforma não está apta a criar cobranças agora. É problema
nosso: nada que você mude na chamada resolve.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
indisponivel:
value:
error:
type: api_error
code: platform_unavailable
message: >-
A plataforma está temporariamente indisponível para criar
cobranças. Tente novamente em instantes.
details: {}
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: sk_live_… | sk_test_…
description: |
Chave secreta do vendedor, criada no painel em **Desenvolvedores**.
O valor em claro existe uma única vez, na criação. Guardamos só o
hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto:
um dump do nosso banco não permite cobrar em nome de ninguém.
A chave vai no **servidor**. Colocá-la no navegador do comprador a
entrega a qualquer pessoa que abra a página.
````