> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Secure

> O Payment Element autentica pagamentos com cartão para você, sem trabalho extra de integração, e mantém checkout, liberação e reconciliação alinhados.

Use esta página para entender como pagamentos com cartão via Payment Element são autenticados.

## O que você precisa fazer

Nada além do que já faz.

`elements.submit(...)` conclui a autenticação do cartão para você quando o pagamento exige. Você não
coleta nenhum campo adicional no seu formulário de checkout e não orquestra a autenticação.

```js theme={null}
const result = await elements.submit({
  createTransaction: async (tokenData) => createPaymentWithToken(tokenData.token),
});
```

A autenticação usa os dados do comprador e da compra que o seu servidor já envia ao criar a
transaction — o `buyer` e os `products` que você passa para
[`POST /v2/transactions`](/pt/api-reference/transactions/create). Mantenha esses dados completos e
corretos e a autenticação terá tudo de que precisa.

<Warning>
  Envie um cadastro de comprador completo: `buyer.email`, `buyer.name`, um `buyer.phone` com código do
  país e todos os campos de `buyer.address`:

  `country`, `state`, `city`, `zipCode`, `street`, `number` e `neighborhood`. Apenas o `complement` é
  opcional.
</Warning>

## O que você recebe de volta

`submit(...)` resolve quando o pagamento chega a um desfecho, tendo havido autenticação ou não. Leia
`status` no resultado:

* `succeeded` — o pagamento foi aprovado.
* `processing` — o pagamento ainda está sendo resolvido. Aguarde o webhook.
* `failed`, `refused`, `canceled`, `timed_out` — a tentativa não passou. Mostre a mensagem retornada
  e deixe o comprador tentar de novo.

Veja a [referência do SDK](/pt/frontend/payment-element/sdk-reference) para a lista completa de status.

## Se o comprador for interrompido

O comprador pode recarregar a página ou sair no meio do pagamento. Retome a mesma transaction em vez
de iniciar uma nova tentativa de checkout:

```js theme={null}
const result = await elements.resume({
  transactionId: savedTransactionId,
});
```

Persista o id da transaction assim que o seu backend retorná-lo, para que você ainda o tenha depois
de um reload.

### Autenticação de cartão após um reload

Um pagamento que aguardava autenticação de cartão (3DS pré-cobrança) estava vinculado à sessão de
Element que capturou o cartão, e um reload inicia uma nova sessão. `resume()` **se auto-corrige**:
monte um `CardElement` e chame `resume()`. O SDK pede que o comprador reinsira o cartão no element
montado, retokeniza, comprova que é o mesmo cartão, substitui o desafio obsoleto e conclui a
autenticação — resolvendo num resultado terminal. Sem nova tentativa de checkout, sem nova transaction
e sem ramificação extra no seu código.

```js theme={null}
// Mantenha um card element montado e chame resume — o element cuida de toda a recuperação.
const card = elements.create("card");
card.mount("#card-element");

const result = await elements.resume({ transactionId: savedTransactionId });
// result.status é terminal: "paid" / "authorized" / "failed" / "refused" ...
```

<Note>
  O cartão reinserido precisa ser o mesmo da tentativa original — um cartão diferente é recusado.
</Note>

<Warning>
  Se nenhum card element estiver montado, ou o comprador não reinserir dentro do tempo limite,
  `resume()` resolve com um resultado terminal claro pedindo para iniciar uma nova tentativa — nunca
  entra em loop nem trava.
</Warning>

Integradores avançados que querem sua própria UX de recoleta podem passar `manualReentry: true` para
receber `status: "requires_reentry"` em vez do auto-heal, e então chamar `resume()` de novo após
recoletar o cartão. Veja a [referência do SDK](/pt/frontend/payment-element/sdk-reference).

## Estado final

O comprador pode concluir a autenticação depois que o primeiro callback do navegador resolver. Não
libere o pedido apenas pelo resultado no navegador — webhook ou reconciliação no servidor é a fonte
final de verdade do estado do pagamento.

## Leia a seguir

* [Referência do SDK v3](/pt/frontend/payment-element/sdk-reference)
* [Aceitar um pagamento](/pt/frontend/payment-element/accept-a-payment)
* [Testes e troubleshooting](/pt/frontend/payment-element/testing-and-troubleshooting)