O que é igual às outras adquirentes#
A integração é a mesma do guia de cartão: 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.
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 |
| 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#
- Preenche número, validade, CVV e nome impresso no cartão.
- Clica em pagar. O elemento mostra "processando" até a resposta.
- Aprovado: a confirmação aparece na hora e o elemento dispara
throne-elements:paid. - 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.
Nota 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
overflowescondido. - Sem
sandboxem volta do elemento. Se não der para tirar, use a lista mínima de Throne Elements.
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) |
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.
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 parapaid. - 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.
Checklist#
- Checkout criado no servidor, com
Idempotency-Keynova 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
failedouexpired.