Abrir sessão 3DS do checkout
curl --request POST \
--url https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"card": {},
"customer": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({card: {}, customer: {}})
};
fetch('https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({card: {}, customer: {}})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Sessões de checkout
Abrir sessão 3DS do checkout
Abre uma sessão 3D Secure para o valor de uma sessão de checkout, antes de confirmar com cartão
POST
https://api.upag.io
/
v1
/
checkout
/
sessions
/
{sessionId}
/
3ds
/
session
Abrir sessão 3DS do checkout
curl --request POST \
--url https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"card": {},
"customer": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({card: {}, customer: {}})
};
fetch('https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/checkout/sessions/{sessionId}/3ds/session';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({card: {}, customer: {}})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Abre uma sessão 3D Secure para pagar uma sessão de checkout com cartão. O valor não é seu para informar: a Upag usa o que a confirmação vai cobrar (itens, bumps aceitos e cupom, ou o valor da fatura se a primeira tentativa já aconteceu), para que o que o banco autentica seja o que é cobrado.
Fluxo no navegador, com o
O corpo não aceita outros campos.
clientSecret da sessão de checkout:
- Tokenize o cartão (
upag.cards.create) e chame este endpoint com ocard.id. - Autentique com o
clientSecretda sessão 3DS devolvido aqui:upag.threeDSecure.authenticate({ clientSecret }). - Confirme com
charge.threeDSecureSessionigual aoiddevolvido.
account.threeDSecureEnabled na visão do pagador), a rota responde 404.
Permissão: checkout_session.write. Aceita a chave secreta ou o clientSecret da sessão de checkout. Limite do navegador: 20 por minuto por IP.
Os exemplos usam o sandbox (
https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_…; no navegador, o upag-js usa só a chave pública.Endpoint
curl -X POST https://api.upag.dev/v1/checkout/sessions/4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26/3ds/session \
-H "Authorization: Bearer Zk3v0pQ8xJ2mR7cYt1LwN5dHs9uAeB4gXo6iFqVjT0E" \
-H "Content-Type: application/json" \
-d '{
"card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
"installments": 2,
"customer": {
"name": "Maria Pagadora",
"email": "maria@example.com",
"document": { "type": "cpf", "number": "39053344705" }
}
}'
import { UpagJs } from 'upag-js';
const upag = new UpagJs('pk_test_your_public_key');
const customer = {
name: 'Maria Pagadora',
email: 'maria@example.com',
document: { type: 'cpf', number: '39053344705' },
};
const threeDS = await upag.checkout.createThreeDSecureSession(id, clientSecret, {
card: card.id,
installments: 2,
customer,
});
await upag.threeDSecure.authenticate({ clientSecret: threeDS.clientSecret });
const paid = await upag.checkout.confirm(id, clientSecret, {
customer,
charge: {
method: 'card',
card: card.id,
installments: 2,
threeDSecureSession: threeDS.id,
},
});
import { Upag } from 'upag';
const upag = new Upag('sk_test_your_api_key');
const threeDS = await upag.checkoutSessions.createThreeDSecureSession(
'4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26',
{
card: '5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15',
installments: 2,
customer: '8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83',
},
);
Parâmetros
string (uuid)
required
ID da sessão de checkout. Precisa estar
open, dentro do prazo, e aceitar card.string (uuid)
required
UUID de um cartão tokenizado.
integer
default:"1"
Número de parcelas, de 1 a 12.
string (uuid) | object
required
O pagador, no mesmo formato de Confirmar. Do navegador, só os dados (não um UUID).
array
default:"[]"
UUIDs dos bumps da sessão que o pagador aceitou. Ignorados quando a sessão já tem fatura.
Resposta
201 Created. O clientSecret aparece só aqui. Campos da sessão 3DS em Sessões 3D Secure.
Response
{
"id": "9b7c1e52-3f0a-4d86-a1c4-6e2d8f35b790",
"status": "requires_action",
"finalAmount": 20140,
"card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
"expiresAt": "2026-10-07T19:13:00.000Z",
"clientSecret": "k2Xv9QmT5aLw1RzJ7dHn0cYeB4uFgS8oPi3VtA6xNqM"
}
Erros
| Status | Código | Quando |
|---|---|---|
404 | THREEDS_DISABLED | O 3D Secure não está habilitado |
404 | CHECKOUT_SESSION_NOT_FOUND | Do servidor: a sessão não existe ou é de outra conta |
404 | THREEDS_CARD_NOT_FOUND | O cartão não existe na conta |
409 | CHECKOUT_SESSION_NOT_OPEN | A sessão já está complete ou expired |
410 | CHECKOUT_SESSION_EXPIRED | A sessão passou do expiresAt |
400 | CHECKOUT_SESSION_PAYMENT_METHOD_NOT_ALLOWED | A sessão não aceita card |
400 | CHECKOUT_SESSION_CUSTOMER_DATA_REQUIRED | Do navegador: customer veio como UUID |
400 | THREEDS_INVALID_PARAMS | A sessão não tem valor a autenticar (por exemplo, um teste sem nada a pagar hoje) |
422 | THREEDS_CUSTOMER_INCOMPLETE | Faltam dados do pagador exigidos pela autenticação |
422 | VALIDATION_FAILED | Campo desconhecido ou inválido no corpo |