Widget de checkout: configuração de um formulário de pagamento drop-in seguro para PCI

O Widget de checkout é um formulário de pagamento totalmente renderizado e seguro para PCI que você insere na sua página. Ele trata os inputs de cartão, a exibição de cartões salvos e a caixa de seleção de consentimento “Salvar este cartão” — sem que você construa nenhum HTML de formulário. Se você quer controle total sobre o layout e o estilo, use os Campos hospedados em vez disso.

Configuração básica

Chame sdk.checkout() depois de inicializar o SDK. O widget se monta no DOM automaticamente.

const checkout = sdk.checkout({
  shopperId: sdk.sessionData().customerId,
  vaultConsentEnabled: true,
  onSavedMethodSelected: (token) => {
    // Um comprador recorrente escolheu um cartão salvo
    // Cobre-o diretamente usando sdk.authorizeToken(token)
  },
})

Para montar o widget em um elemento específico, passe um seletor CSS:

const checkout = sdk.checkout({
  container: '#checkout-container',
  vaultConsentEnabled: true,
})

Idioma (`locale`)

Defina locale para escolher o idioma do texto integrado do widget: 'en', 'es' ou 'pt'. Se você omitir, o widget usa o idioma do navegador do comprador e volta para o inglês quando esse idioma não é suportado.

const checkout = sdk.checkout({
  locale: 'pt',
})

locale cobre todo o texto próprio do widget, não apenas a caixa de consentimento: os botões de pagar e assinar, o rodapé “Secured by Therius”, os rótulos e placeholders do formulário de cartão, o texto de cartões salvos, os avisos de assinatura e de cartão em arquivo, o texto dos painéis de Pix e Affirm, e as mensagens comuns de recusa e erro. O conteúdo da sua própria página e qualquer texto retornado por um provedor de pagamento não são traduzidos.

Callbacks

Callback	Dispara quando
`onActionComplete(result)`	Um pagamento chega a um estado final após uma ação em popup (3DS ou redirecionamento) ou após a chamada de autorização integrada do widget. `result` contém `status`, `paymentCode` e, no caminho de retomada, o `payment` completo. Use para mostrar o resultado final na sua interface.
`onDeclined(info)`	Um pagamento é recusado e o widget tem orientação de recuperação. `info` contém `reason` e `recoveryAction` (`'retry'`, `'switch_method'` ou `'terminal'`). O widget já exibe sua própria interface de recuperação, então use apenas para registrar ou reportar a recusa.
`onError(error)`	O widget encontra um erro que não é uma recusa.
`onMethodChange(method)`	O comprador troca de aba de método de pagamento.

onNonce, onApm e onWalletToken são interceptores opcionais. Se você os omitir, o widget chama por conta própria o método do SDK correspondente e reporta o resultado por onActionComplete ou onError. Forneça-os apenas se precisar encaminhar o pagamento pelo seu próprio servidor.

Quando você autoriza a partir do seu próprio servidor, envie o endereço IP real do comprador como ipAddress na solicitação de pagamento. O endereço do seu servidor não é o do comprador, e a pontuação antifraude e alguns provedores dependem do real. O widget o obtém para você e o entrega a onNonce, onApm e onSavedMethodSelected como shopper.ipAddress (ausente se a consulta falhar):

onNonce: async (nonce, ddcSessionId, vaultConsent, shopper) => {
  await fetch('/pay', {
    method: 'POST',
    body: JSON.stringify({ nonce, ddcSessionId, ipAddress: shopper?.ipAddress }),
  })
}

Quando o widget autoriza por conta própria, a Therius usa o endereço da conexão do comprador, então nenhuma etapa extra é necessária.

Seletor de cartões salvos

Se a sessão foi criada com um customerId e esse comprador tem cartões previamente colocados no vault, o widget renderiza automaticamente um seletor de cartões acima do formulário de cartão novo. Os cartões são exibidos como brand / last 4 / expiry — nenhum PAN é devolvido ao navegador. Quando o comprador seleciona um cartão salvo, onSavedMethodSelected é disparado com o token do cartão. Cobre-o de imediato sem um nonce:

const checkout = sdk.checkout({
  onSavedMethodSelected: async (token) => {
    const result = await sdk.authorizeToken(token, {
      amount: { currency: 'USD', value: 4999, exponent: 2 },
    })
    if (result.actionRequired) {
      const finalResult = await sdk.handleAction(result.actionRequired)
    }
  },
})

A lista de cartões salvos é suportada por GET /sdk/vaulted-methods e é limitada ao próprio comprador da sessão — o navegador não pode enumerar os cartões de um comprador diferente.

Combine vaultConsentEnabled: true com um customerId na sua chamada a POST /sdk/session para a melhor experiência de comprador recorrente. Quando há um shopperId presente na sessão, a caixa de seleção “Salvar este cartão” aparece automaticamente.

Para um cartão novo inserido pelo widget, recupere o nonce depois que o comprador envia o formulário e use-o da mesma forma que com os campos hospedados:

checkout.on('submit', async ({ nonce }) => {
  const result = await sdk.authorize(nonce)
  if (result.actionRequired) {
    const finalResult = await sdk.handleAction(result.actionRequired)
  }
})

Como alternativa, chame sdk.authorize(nonce) diretamente depois do envio do widget para deixar o SDK gerenciar o ciclo completo de autorizar-e-ação em uma única chamada.

Tratamento de 3DS

O 3DS é tratado de forma idêntica aos campos hospedados. Se o resultado da cobrança incluir actionRequired, passe-o para sdk.handleAction:

if (result.actionRequired) {
  const finalResult = await sdk.handleAction(result.actionRequired)
}

sdk.handleAction abre o iframe do desafio de 3DS, aguarda a conclusão e resolve com o PaymentResult final. Você não precisa escrever lógica separada para tipos de desafio diferentes.

vaultConsentEnabled só mostra a caixa de seleção “Salvar este cartão” quando há um shopperId presente na sessão. Se nenhum customerId foi passado para POST /sdk/session, a caixa de seleção é ocultada independentemente dessa configuração.

Se você passou cardOnFile ao criar a sessão (veja Assinaturas gerenciadas pelo lojista), o widget mostra um aviso fixo de “o cartão será salvo” em vez da caixa de seleção vaultConsentEnabled — o cartão é salvo incondicionalmente, então não há nada para optar.

Visão geral

Coleta de cartão

Carteiras e mais

Widget de checkout: configuração de um formulário de pagamento drop-in seguro para PCI

Configuração básica

Idioma (`locale`)

Callbacks

Seletor de cartões salvos

Cobrar um cartão novo pelo widget

Tratamento de 3DS

​Configuração básica

​Idioma (locale)

​Callbacks

​Seletor de cartões salvos

​Cobrar um cartão novo pelo widget

​Tratamento de 3DS

Configuração básica

Idioma (`locale`)

Callbacks

Seletor de cartões salvos

Cobrar um cartão novo pelo widget

Tratamento de 3DS