Criar sessão 3DS
curl --request POST \
--url https://api.upag.io/v1/3ds/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 123,
"card": {},
"customer": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 123, card: {}, customer: {}})
};
fetch('https://api.upag.io/v1/3ds/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/3ds/sessions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 123, card: {}, customer: {}})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));3D Secure
Criar sessão 3DS
Abre uma sessão 3D Secure para autenticar um cartão e um valor
POST
https://api.upag.io
/
v1
/
3ds
/
sessions
Criar sessão 3DS
curl --request POST \
--url https://api.upag.io/v1/3ds/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 123,
"card": {},
"customer": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 123, card: {}, customer: {}})
};
fetch('https://api.upag.io/v1/3ds/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/3ds/sessions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 123, card: {}, customer: {}})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Abre uma sessão que autentica um cartão para um valor. Chame do seu servidor e entregue o
clientSecret à página de checkout, que o passa ao upag-js (threeDSecure.authenticate).
Permissão: charge.write. Apenas chave secreta (sk_…).
Os exemplos usam o sandbox (
https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_….Endpoint
curl -X POST https://api.upag.dev/v1/3ds/sessions \
-H "Authorization: Bearer sk_test_your_api_key" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"installments": 3,
"card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
"customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83"
}'
import { Upag } from 'upag';
const upag = new Upag('sk_test_your_api_key');
const session = await upag.threeDSecure.createSession(
{
amount: 10000,
installments: 3,
card: '5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15',
customer: '8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83',
},
{ idempotencyKey: 'order-10482' },
);
// envie session.clientSecret à página de checkout
Parâmetros
integer
required
Preço cheio em centavos (maior que zero, até 2.147.483.647). Envie exatamente o que a cobrança terá.
string (uuid)
required
UUID de um cartão tokenizado da conta. Número de cartão nunca é aceito aqui: tokenize antes com
POST /v1/cards.string | object
required
UUID de um cliente, ou um objeto cliente inline (mesmos campos de Criar cliente). Dados inline valem só para esta autenticação e não são gravados. O cliente precisa ter e-mail e telefone.
integer
default:"1"
1 a 12.
string
Nome exibido na tela do desafio do banco, até 255 caracteres. É normalizado (sem acentos, só letras, dígitos e espaços) e cortado em 30. Padrão: descritivo da conta.
string
Até 255 caracteres. Por 24 horas, a mesma chave com o mesmo corpo devolve a mesma sessão com um novo
clientSecret (o anterior deixa de valer). Chave igual com corpo diferente retorna 409.Resposta
201 Created
Response
{
"id": "9b7c1e52-3f0a-4d86-a1c4-6e2d8f35b790",
"status": "requires_action",
"finalAmount": 11016,
"card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
"expiresAt": "2026-09-30T19:06:02.113Z",
"clientSecret": "4fJq8Wm2Xc7Nb1Rt5Yh9Lk3Vd0Ze6Sa7Xp2Qn9Rt5Yh1Lk3V"
}
clientSecret autoriza o browser a trabalhar nesta sessão: entregue só à página de checkout. Ele é guardado apenas como hash, então Obter sessão nunca o devolve. Se perder, repita a criação com a mesma Idempotency-Key para receber outro.
Erros
| Status | Código | Causa |
|---|---|---|
400 | invalid_params | Corpo malformado (inclusive cartão enviado como objeto), ou cartão inativo, vencido ou indisponível para autenticação |
404 | card_not_found | O cartão não existe na conta |
404 | not_found | 3D Secure não está habilitado neste ambiente |
409 | idempotency_key_reused | A Idempotency-Key já foi usada com outro corpo |
422 | customer_incomplete | O cliente não tem o que a autenticação exige; error.details.missingFields lista os campos |
429 | too_many_attempts | Mais de 100 sessões por minuto na conta |