Abra a sessão 3DS
Crie no servidor a sessão de coleta de dados do dispositivo que acompanha cada tentativa de cobrança com cartão de crédito.
/v1/3ds/device-data-sessionsSuperfície API, chamada do seu servidorToda cobrança de crédito com 3DS começa com uma sessão de coleta. A sessão gera um session_token de uso único, que o seu checkout entrega ao SDK no navegador e que o seu servidor envia depois na criação da cobrança. É ele que liga os dados do dispositivo do comprador à cobrança certa.
Abra uma sessão nova para cada tentativa de pagamento, assim que o comprador escolher cartão.
Requisição
curl -X POST "$DM_API_BASE/v1/3ds/device-data-sessions" \
-H "Authorization: $DM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency": "BRL",
"transaction_scope": "Domestic"
}'Esta rota usa nomes de campo em snake_case (transaction_scope, session_token, expires_at). A criação de cobrança usa camelCase. Os dois formatos são intencionais; copie os nomes exatamente como estão em cada página.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | inteiro | Sim | Valor da cobrança na menor unidade da moeda, maior que zero. Precisa ser igual ao amount que você vai enviar na criação da cobrança. |
currency | string | Sim | Moeda da cobrança, como BRL ou USD. Precisa ser igual à da cobrança. |
transaction_scope | string | Não | Domestic (padrão) ou Offshore. Use o escopo informado no credenciamento da sua conta. |
Escolha do escopo
O transaction_scope não depende da moeda. Ele é uma característica da sua conta, definida no credenciamento: uma conta Domestic cobrando em USD continua sendo Domestic. Se a sua conta for Offshore, envie "transaction_scope": "Offshore" em todas as sessões. Escopo diferente do cadastrado faz a cobrança falhar com three_ds_session_scope_mismatch.
Resposta
{
"session_token": "3ds_sess_9J4W2C7X5N8QK2R4T6Y8V0H2M4P6A1B3",
"expires_at": "2026-09-08T15:30:00.1234567Z"
}| Campo | Descrição |
|---|---|
session_token | Identificador opaco da sessão. Pode ser enviado ao navegador; a chave de API continua no servidor. |
expires_at | Fim da validade, em ISO 8601 UTC. A sessão vale 30 minutos. O valor pode ter até sete casas de fração de segundo: use um parser de data que aceite fração. |
Regras da sessão
- Uma sessão, uma tentativa. A sessão é consumida pela primeira cobrança que a usa. Também não pode ser coletada de novo depois que o SDK registrou um resultado, mesmo que a coleta tenha falhado ou sido abortada. Para uma nova tentativa, abra uma nova sessão.
- Mesma conta, mesmo valor, mesma moeda. A cobrança é conferida contra a sessão. Divergências retornam
three_ds_session_amount_mismatchouthree_ds_session_scope_mismatch. - Respeite
expires_at. Sessão vencida retornathree_ds_session_expiredna cobrança.
Erros
Nesta rota, o código do erro está no campo title do Problem Details:
{
"title": "THREE_DS_SESSION_CURRENCY_NOT_SUPPORTED",
"detail": "Moeda 'BRX' não é suportada.",
"status": 400
}| HTTP | title | Causa e ação |
|---|---|---|
400 | amount_must_be_integer_minor_units | amount com casas decimais. Envie inteiro em centavos. |
400 | THREE_DS_SESSION_AMOUNT_INVALID | amount ausente, zero ou negativo. |
400 | THREE_DS_SESSION_CURRENCY_NOT_SUPPORTED | Moeda ausente ou desconhecida. |
400 | campo error: forbidden_field | O corpo trouxe um campo de cartão (pan, cvc, cardNumber…). Dados de cartão nunca vão nesta rota. |
422 | THREE_DS_SESSION_SCOPE_INVALID | transaction_scope diferente de Domestic ou Offshore. |
429 | sem código | Limite de emissão atingido: 300 sessões por minuto por conta. Repita após alguns segundos. |
500 | THREE_DS_SESSION_CONFLICT | Colisão rara de identificador. Abra outra sessão. |
503 | código do provedor | Falha temporária ao preparar a coleta. Nada foi gravado: repita a chamada. |
Erros de autenticação (401, 403) seguem o formato descrito em Autenticação.
Próximo passo
Entregue session_token ao navegador e colete os dados do dispositivo.