# Cartão com a Imperium

> Regras e comportamento do checkout quando a venda passa pela Imperium (acquirer imperium).

Fonte: https://app.thronecorporate.com/docs/cartao/imperium

## O que é igual às outras adquirentes

A integração é a mesma do [guia de cartão](/docs/cartao): `POST /elements/checkout` na moeda do comprador, Throne Elements na página, webhook `transaction.paid`. Campos, respostas, erros, moedas e formato do webhook não mudam. Esta página cobre só o que é próprio da Imperium.

**Para usar a Imperium**, mande `"acquirer": "imperium"` na criação do checkout. Se a Imperium for a padrão da sua conta, o campo é opcional. Veja [Escolher a adquirente](/docs/cartao/escolher).

## Resumo

| Item | Na Imperium |
|---|---|
| Verificação do banco | Não tem: o resultado sai na própria tentativa |
| Navegador de app (Instagram, Facebook, Google, TikTok) | Tudo dentro do elemento; os eventos chegam normalmente |
| Valor máximo por venda | Varia com a moeda e com a cotação do dia. Veja [Limites](#limites) |
| Tentativas por checkout | 5 |
| Validade do checkout | 24 horas |
| Fechamento por recusa | Na 5ª recusa, ou 10 minutos depois de uma recusa sem nova tentativa (`failed`) |
| Tempo de resposta | Aprovação em segundos; uma recusa pode levar até 25 segundos |
| Parcelas | À vista |
| Idioma do checkout | Pelo país do comprador; Brasil e Portugal veem em inglês |
| Idioma das mensagens de recusa | Pelo header `Accept-Language` da chamada que criou o checkout: português por padrão, inglês com `en` e espanhol com `es` |

## Limites

| Limite | Na Imperium |
|---|---|
| Mínimo por venda | Varia com a moeda e com a cotação do dia, ou o mínimo próprio da Imperium, se houver |
| Máximo por venda | Depende da adquirente e varia com a moeda e com a cotação do dia. Consulte `GET /elements/acquirers?currency=` (campo `limits.max_amount_cents`) |
| Acima do máximo | `422 invalid_amount` com `max_amount_cents` na sua moeda e `alternatives`. Nada é criado |
| Capacidade de criação | Em pico ou instabilidade, `503 temporarily_unavailable` com `Retry-After` |

## Como o comprador paga

1. Preenche número, validade, CVV e nome impresso no cartão.
2. Clica em pagar. O elemento mostra "processando" até a resposta.
3. Aprovado: a confirmação aparece na hora e o elemento dispara `throne-elements:paid`.
4. Recusado: o elemento avisa que o pagamento não foi autorizado, mostra quantas tentativas restam e o botão para tentar de novo. A venda continua `pending`.

> [!NOTE]
> A resposta de uma recusa pode demorar até 25 segundos. Não recarregue a página nem crie outro checkout nesse intervalo: o elemento continua acompanhando a tentativa.

Como não existe etapa de verificação do banco, não há janela nem tela extra: tudo acontece dentro do elemento, no computador, no celular e no navegador de app. Os eventos chegam à sua página nos três casos.

## Requisitos da página

- Uma tela de pagamento que aguarda até 25 segundos sem recarregar.
- Container sem altura fixa e sem `overflow` escondido.
- Sem `sandbox` em volta do elemento. Se não der para tirar, use a lista mínima de [Throne Elements](/docs/cartao/elements#boas-praticas).

## Erros e o que fazer

| Situação | Resposta | O que fazer |
|---|---|---|
| Valor acima do máximo | `422 invalid_amount`, com `max_amount_cents` e `alternatives` | Não repita. Crie com o `acquirer` de uma das `alternatives` ou divida o pedido |
| Imperium em pausa, instável ou sem capacidade | `503 temporarily_unavailable`, com `Retry-After` | Espere o `Retry-After` e repita com uma `Idempotency-Key` nova, ou use outra adquirente habilitada |
| Criação recusada | `502 checkout_failed`, com `"retryable": false` | Não repita igual. Se continuar, fale com o suporte |
| Falha passageira de conexão | `502 checkout_failed`, com `"retryable": true` | Repita com uma `Idempotency-Key` nova |
| Sem resposta (timeout do seu lado) | Nenhuma | Repita com a **mesma** `Idempotency-Key` ([regra](/docs/comecar#como-repetir-uma-chamada-com-seguranca)) |

Na página, a Imperium não envia `code` em `throne-elements:error`, só `e.detail.message`. Falha de conexão, validade e encerramento chegam como `network`, `expired` e `ended`. Numa recusa, inclusive a última, chega o texto mostrado ao comprador, que não diz se ainda há tentativa; `attempts_exhausted` só chega quando o elemento abre num checkout que já fechou. O próprio elemento mostra ao comprador se ele pode tentar de novo. Para saber se o checkout fechou, consulte `GET /transactions/{id}`. A tabela completa está em [Throne Elements](/docs/cartao/elements#codigos-de-erro).

## Quando chega o webhook

O resultado sai na própria tentativa, então o webhook `transaction.paid` costuma sair logo depois da aprovação. Não cancele o pedido por falta de webhook antes da validade de 24 horas; na dúvida, consulte `GET /transactions/{id}`.

## Depois da venda

- **Estorno**: não é feito pela API; fale com o suporte. A venda estornada fica `refunded`.
- **Contestação**: a venda vira `chargeback`. Se a contestação for revertida a seu favor, ela volta para `paid`.
- Nenhum desses eventos gera webhook. Acompanhe pelo `GET /transactions/{id}`.

## Testar

Use um cartão de verdade com valor baixo. Os erros que dá para provocar sem custo estão em [Como testar](/docs/testar).

## Checklist

- [ ] Checkout criado no servidor, com `Idempotency-Key` nova por venda e timeout de 60 segundos.
- [ ] Moeda do comprador em `currency`, sem ajustar o valor no seu site.
- [ ] Tela de pagamento que aguarda até 25 segundos sem recarregar.
- [ ] Pedido liberado só com `transaction.paid` (assinatura validada).
- [ ] Novo checkout para cada nova tentativa de compra depois de `failed` ou `expired`.