Iniciar sessão 3DS
curl --request POST \
--url https://api.upag.io/v1/3ds/sessions/start \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"clientSecret": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({clientSecret: '<string>'})
};
fetch('https://api.upag.io/v1/3ds/sessions/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/3ds/sessions/start';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({clientSecret: '<string>'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));3D Secure
Iniciar sessão 3DS
Chamado pelo browser: entrega o necessário para autenticar o portador
POST
https://api.upag.io
/
v1
/
3ds
/
sessions
/
start
Iniciar sessão 3DS
curl --request POST \
--url https://api.upag.io/v1/3ds/sessions/start \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"clientSecret": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({clientSecret: '<string>'})
};
fetch('https://api.upag.io/v1/3ds/sessions/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/3ds/sessions/start';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({clientSecret: '<string>'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Endpoint chamado pelo browser. O
O SDK Node.js não tem método para este endpoint: ele pertence ao browser.
upag-js o usa dentro de threeDSecure.authenticate; chame direto só se não usar o SDK.
Autentica com chave publicável (pk_…) e é provado pelo clientSecret da sessão. Chave secreta é recusada. Não exige permissão.
Os exemplos usam o sandbox (
https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com pk_live_….Endpoint
curl -X POST https://api.upag.dev/v1/3ds/sessions/start \
-H "Authorization: Bearer pk_test_your_public_key" \
-H "Content-Type: application/json" \
-d '{ "clientSecret": "4fJq8Wm2Xc7Nb1Rt5Yh9Lk3Vd0Ze6Sa7Xp2Qn9Rt5Yh1Lk3V" }'
import { UpagJs } from 'upag-js';
const upag = new UpagJs('pk_test_your_public_key');
// start e complete são chamados por authenticate()
const { sessionId } = await upag.threeDSecure.authenticate(
{ clientSecret },
{ onStatusChange: (status) => console.log(status) },
);
// envie sessionId ao seu servidor, que o passa em threeDSecureSession na cobrança
Parâmetros
string
required
O
clientSecret devolvido na criação da sessão (1 a 512 caracteres). Identifica a sessão: a chamada não leva ID.Resposta
200 OK. Enquanto a sessão precisa do browser, nextAction traz o necessário para a autenticação:
Response
{
"id": "9b7c1e52-3f0a-4d86-a1c4-6e2d8f35b790",
"status": "requires_action",
"nextAction": {
"type": "browser_authentication",
"token": "eyJhbGciOi...",
"environment": "sandbox",
"payload": { "...": "..." }
}
}
nextAction.token é uma credencial de curta duração para o módulo de autenticação: trate como segredo. payload é opaco e deve ser repassado como veio.
Se a sessão já está completed, a resposta traz "nextAction": null. Chamar start de novo enquanto a sessão aguarda é seguro (idempotente).
Erros
| Status | Código | Causa |
|---|---|---|
400 | invalid_params | Corpo malformado |
401 | unauthorized | clientSecret desconhecido, substituído por um mais novo ou de outra conta |
403 | — | Chave secreta usada neste endpoint (exige chave publicável) |
404 | not_found | 3D Secure não está habilitado neste ambiente |
409 | invalid_session_state | O estado da sessão não permite iniciar (ex.: failed ou canceled) |
410 | session_expired | A sessão expirou |
429 | too_many_attempts | Mais de 20 chamadas por minuto do mesmo IP |
502 | authentication_unavailable | Não foi possível preparar a autenticação; tente de novo |