Skip to main content
O 3D Secure (3DS) faz o banco emissor autenticar o portador antes de você cobrar o cartão. Seu servidor abre uma sessão, o browser do pagador executa a autenticação e a cobrança de cartão referencia a sessão concluída em threeDSecureSession. start e complete são chamados pelo upag-js no browser (threeDSecure.authenticate), com chave publicável e o clientSecret da sessão. Você só chama create e get do servidor.
Sandbox: https://api.upag.dev/v1. Produção: https://api.upag.io/v1. Cartão de teste que força o desafio 3DS em Simulador.

​
Fluxo

  1. O servidor cria a sessão (Criar sessão) e envia o clientSecret à página de checkout.
  2. A página chama upag.threeDSecure.authenticate({ clientSecret }). O SDK chama start, roda a autenticação do banco e chama complete. Resolve com { sessionId, status: 'completed' }.
  3. O servidor cria a cobrança de cartão com threeDSecureSession igual ao id da sessão.
Guia completo: Cartão com 3DS.

​
Estrutura

Na criação a resposta inclui também clientSecret (veja Criar sessão).

​
Atributos

​
string
UUID da sessão.
​
string
requires_action, completed, failed, canceled ou expired.
  • requires_action: aguardando o browser.
  • completed: portador autenticado; a sessão pode ser usada por uma cobrança.
  • canceled: o pagador fechou o desafio, ou o browser estourou o tempo.
  • failed: a autenticação falhou.
  • expired: passou de expiresAt.
failed, canceled e expired são finais: crie uma sessão nova para tentar de novo.
​
integer
Valor que o cartão será cobrado, em centavos: o amount enviado mais os juros de parcelamento que o pagador assume. Fixado na criação.
​
string
UUID do cartão autenticado.
​
string
ISO 8601. A sessão vale 1 hora.
A sessão não repete o que você enviou (amount, installments, cliente). O clientSecret só é devolvido na criação e nunca mais.

​
Usando a sessão na cobrança

Passe o id em threeDSecureSession numa cobrança de cartão:
  • card precisa ser o cartão da sessão.
  • O cartão é cobrado pelo finalAmount da sessão, sem recalcular: mudar taxas depois não altera o que o pagador autenticou.
  • amount e installments da cobrança precisam ser iguais aos da sessão.
A cobrança é recusada, sem cobrar o cartão, quando a sessão:
  • não existe na conta (404 session_not_found);
  • não está completed ou já foi usada (409 invalid_session_state);
  • expirou (410 session_expired);
  • foi autenticada para outro cartão, valor ou parcelas (409 threeds_session_mismatch).
A sessão é consumida assim que uma cobrança a usa, mesmo que o banco depois recuse o pagamento. Para tentar de novo, crie outra sessão.

​
Disponibilidade

O 3D Secure é habilitado por ambiente. Com ele desligado, todos os endpoints desta seção respondem 404 not_found.