# Cartão com a Eminence

> Regras e comportamento do checkout quando a venda passa pela Eminence (acquirer eminence): verificação do banco dentro do elemento, navegador de app, pagamento em análise, códigos de erro e webhook.

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

## 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 Eminence.

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

```bash
curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout \
  --max-time 60 \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount_cents": 4990, "currency": "chf", "acquirer": "eminence", "customer": { "name": "Luca Meier", "email": "luca@example.ch" } }'
```

A resposta `201` traz `"acquirer": "eminence"`, e a venda fica na Eminence até o fim: pagamento, estorno e contestação.

**A moeda funciona exatamente como nas outras adquirentes.** Você manda o valor na moeda do comprador (por exemplo, `"currency": "chf"`) e ele paga nessa moeda. A cotação que credita o seu saldo é fixada na criação, e o webhook traz `currency`, `native_amount_cents` e `fx_rate` no mesmo formato. Detalhes em [Moedas e limites](/docs/cartao/moeda).

## Resumo

| Item | Na Eminence |
|---|---|
| Verificação do banco | Pode pedir; a tela do banco aparece **dentro do próprio elemento**, sem janela nova. Na maior parte das compras o banco não pede nada |
| Navegador de app (Instagram, Facebook, Google, TikTok) | Tudo dentro do elemento; os eventos chegam normalmente |
| Eventos na sua página | Em todos os caminhos: computador, celular e navegador de app |
| Valor máximo por venda | Varia com a moeda e com a cotação do dia. Veja [Limites](#limites) |
| Tentativas por checkout | 5, contadas no servidor. Recarregar a página não devolve tentativas |
| Validade do checkout | 24 horas |
| Fechamento por recusa | Na 5ª recusa, ou 10 minutos depois de uma recusa sem nova tentativa (`failed`). Uma recusa depois da análise antifraude ou de uma confirmação demorada fecha na hora |
| Parcelas | À vista |
| Idioma do checkout | Pelo país do comprador; Brasil e Portugal veem em inglês. `?nl=` no `checkout_url` mostra outro idioma, para teste |
| Idioma da mensagem de recusa | O mesmo do checkout, pelo país do comprador (ou pelo `?nl=`), na tela e em `e.detail.message`. Não é preciso enviar `Accept-Language` na criação |
| Códigos em `throne-elements:error` | `declined`, `attempts_exhausted`, `token`, `network`, `timeout`, `limit`, `expired`, `ended` |

## Limites

| Limite | Na Eminence |
|---|---|
| Mínimo por venda | Varia com a moeda e com a cotação do dia, ou o mínimo próprio da Eminence, 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` |

Se a Eminence não aceitar o valor da venda no cartão, o checkout fecha como `failed` na hora e a página recebe `limit` em `throne-elements:error`.

## Como o comprador paga

### Em qualquer aparelho

1. Preenche número, validade, CVV e nome impresso no cartão.
2. Clica em pagar.
3. Na maior parte das compras o banco não pede nada: o resultado sai em poucos segundos, dentro do próprio elemento.
4. Aprovado: o elemento mostra a confirmação e dispara `throne-elements:paid`.
5. Recusado: o elemento mostra o motivo, quantas tentativas restam e um botão para tentar de novo. A venda continua `pending`.

### Quando o banco pede verificação

Alguns bancos pedem uma confirmação da compra (código por SMS, aplicativo do banco, pergunta de segurança). Na Eminence ela aparece **dentro do próprio elemento**, sem janela nova e sem sair da sua página. Quando o comprador conclui, o resultado aparece ali mesmo e os eventos chegam normalmente.

- O elemento cresce para mostrar a tela do banco e depois o resultado. Por isso, **não fixe a altura do container**.
- O comprador pode sair da verificação pelo botão **Cancelar**. Nada é cobrado por isso. A nova tentativa fica liberada quando o banco encerra a verificação pendente, o que pode levar alguns minutos; nesse intervalo o elemento avisa que está aguardando o banco.
- A tela do banco segue o banco: idioma, desenho e tempo são dele.

### Em navegador de app

Instagram, Facebook, o app do Google, TikTok e outros apps abrem links num navegador próprio, que não abre uma segunda janela. Na Eminence isso não faz diferença: a verificação acontece dentro do elemento, o comprador termina na sua página e `throne-elements:paid` chega como no computador. Mesmo assim, libere o pedido pelo webhook ou pelo `GET`, nunca só pelo evento da página.

### O que o comprador vê

- **O endereço.** Nada muda: o comprador fica na sua página do começo ao fim, inclusive durante a verificação do banco.
- **A confirmação do banco.** Quando o banco pede, a tela dele aparece dentro do elemento. Vale avisar ao lado do botão de pagar, para o comprador não estranhar.
- **A fatura.** Na fatura do cartão, a compra aparece sem o nome da sua loja.

Textos sugeridos para o aviso:

```text Inglês
Secure payment. Your bank may ask you to confirm this purchase right here, on this page.
```

```text Alemão
Sichere Zahlung. Ihre Bank kann Sie bitten, diesen Kauf direkt hier auf dieser Seite zu bestätigen.
```

```text Espanhol
Pago seguro. Tu banco puede pedirte que confirmes esta compra aquí mismo, en esta página.
```

## Requisitos da página

- **Não fixe a altura do container** e não esconda o `overflow`: a verificação do banco e o resultado crescem o elemento.
- 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).
- **O clique no botão de pagar precisa ser do comprador.** Não dispare o pagamento por código.
- Se o seu site usa Content-Security-Policy, libere `https://app.thronecorporate.com` em `script-src` e em `img-src`, e em `frame-src` libere esse domínio e o domínio do `checkout_url`, como em [Throne Elements](/docs/cartao/elements#boas-praticas).

## Pagamento em análise

Às vezes o pagamento entra em análise antifraude, ou a confirmação demora a sair. O comprador vê "Pagamento em análise", sem formulário, e a venda fica `pending` até a decisão:

- aprovado, vira `paid` e o webhook `transaction.paid` é enviado;
- reprovado na análise antifraude ou recusado depois de uma confirmação demorada, vira `failed` na hora, mesmo com tentativas sobrando.

Se a decisão demorar, o elemento avisa que a confirmação pode levar alguns minutos e envia `timeout` em `throne-elements:error`. Isso não é recusa. Não libere o pedido enquanto não chegar `transaction.paid`, e não cancele o pedido só pelo `timeout`.

## Erros e o que fazer

Na criação do checkout:

| Situação | Resposta | O que fazer |
|---|---|---|
| Valor acima do máximo da Eminence | `422 invalid_amount`, com `max_amount_cents` e `alternatives` | Não repita. Crie com o `acquirer` de uma das `alternatives` ou divida o pedido |
| Valor abaixo do mínimo | `422 invalid_amount`, com `min_amount_cents` | Aumente o valor |
| Eminence não habilitada na conta | `422 acquirer_not_enabled`, com as habilitadas no `message` | Use uma das habilitadas, ou fale com o suporte para habilitar a Eminence |
| Eminence em pausa, instável ou sem capacidade | `503 temporarily_unavailable`, com `Retry-After` e `"retryable": true` | 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, em `throne-elements:error` (`e.detail.code`):

| `code` | O que aconteceu | O que fazer |
|---|---|---|
| `declined` | O banco não autorizou | O comprador pode tentar de novo ou usar outro cartão. Vale sugerir que ele libere compras online e internacionais no app do banco |
| `attempts_exhausted` | O checkout fechou: acabaram as 5 tentativas, ou a recusa veio depois da análise antifraude ou de uma confirmação demorada | Ofereça outro meio de pagamento ou um checkout novo |
| `token` | Os dados do cartão não passaram na validação | O comprador confere os dados e tenta de novo. Quando a validação falha no próprio elemento, nenhuma tentativa é gasta; quando a Eminence recusa os dados depois do envio, a tentativa conta |
| `network` | Falha de conexão do comprador, ou o formulário não carregou | O comprador pode tentar de novo |
| `timeout` | A confirmação está demorando e o pagamento segue em análise, ou o comprador cancelou ou não concluiu a verificação do banco e ela ainda não foi encerrada | Espere o webhook ou consulte `GET /transactions/{id}`. Não é recusa; não crie outro checkout por isso |
| `limit` | A Eminence não aceita o valor desta venda no cartão. O checkout fecha como `failed` | Crie um checkout novo com outra adquirente habilitada, ou ofereça outro meio de pagamento |
| `expired`, `ended` | O checkout passou da validade ou foi encerrado | Crie um checkout novo |

A tabela completa dos códigos, nas seis adquirentes, está em [Throne Elements](/docs/cartao/elements#codigos-de-erro). Duas tentativas ao mesmo tempo no mesmo checkout (duas abas ou duplo clique) não geram cobrança dupla: a segunda recebe "Já existe um pagamento em andamento. Aguarde." e o elemento acompanha o pagamento que já está em andamento.

### Tratar os eventos na página

Na Eminence, dois códigos pedem um tratamento próprio: `timeout` é espera, não recusa; `limit` é troca de adquirente, não nova tentativa.

```js
window.addEventListener('throne-elements:paid', (e) => {
  // e.detail.transaction_id: mostre o "obrigado". A liberação do pedido vem pelo webhook.
});

window.addEventListener('throne-elements:error', (e) => {
  switch (e.detail.code) {
    case 'timeout':
      // o pagamento segue em análise: mostre "estamos confirmando" e espere o webhook
      break;
    case 'limit':
    case 'attempts_exhausted':
    case 'expired':
    case 'ended':
      // este checkout acabou: ofereça outro meio ou crie um checkout novo (no limit, com outra adquirente)
      break;
    default:
      // declined, token, network: o próprio elemento já oferece a nova tentativa
      break;
  }
});
```

## Quando chega o webhook

Quando o banco não pede verificação, o resultado sai na hora e o webhook `transaction.paid` costuma sair logo depois da aprovação. Quando pede, ele sai depois que o comprador conclui a verificação. Numa venda que entra em análise, ele sai quando a análise aprova. Se a confirmação da Eminence se perder no caminho, a conferência automática do Throne a recupera alguns minutos depois. Não cancele o pedido por falta de webhook antes da validade de 24 horas; na dúvida, consulte `GET /transactions/{id}`.

O webhook é o mesmo das outras adquirentes: `currency` e `native_amount_cents` com a venda na moeda do comprador, `amount_cents` com o valor creditado no seu saldo e `fx_rate` com a cotação fixada na criação. Veja [Webhooks](/docs/webhooks#quando-o-webhook-chega).

## Depois da venda

- **Estorno**: não é feito pela API; fale com o suporte. O estorno total deixa a venda `refunded`. O parcial mantém `paid`, com os valores reduzidos.
- **Contestação**: o Throne debita da sua carteira o valor líquido da venda, e ela 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. Para ver como o comprador de outro país enxerga o checkout, abra o `checkout_url` da resposta com `?nl=` e o código do idioma (por exemplo, `?nl=de` para alemão): o formulário, os números e as telas do elemento saem nesse idioma. A tela do próprio banco, na verificação, segue o banco. Teste também dentro do navegador do Instagram ou do Facebook, no celular: na Eminence o resultado aparece na sua página e o evento chega. Os erros que dá para provocar sem custo e o roteiro completo estão em [Como testar](/docs/testar).

## Checklist

- [ ] Checkout criado no servidor, com `"acquirer": "eminence"` (ou a Eminence como padrão da conta), `Idempotency-Key` nova por venda e timeout de 60 segundos.
- [ ] Moeda do comprador em `currency`, sem ajustar o valor no seu site.
- [ ] Máximo da Eminence conferido na moeda do seu público, com plano para `422 invalid_amount` (outra adquirente ou pedido dividido).
- [ ] Container sem altura fixa e sem `sandbox` em volta do elemento (ou com a lista mínima).
- [ ] Aviso ao lado do botão de que o banco pode pedir a confirmação ali mesmo.
- [ ] Tratamento de `e.detail.code` em `throne-elements:error`, com `timeout` tratado como espera e `limit` como troca de adquirente.
- [ ] Pedido liberado só com `transaction.paid` (assinatura validada) ou com o `GET`.
- [ ] Novo checkout para cada nova tentativa de compra depois de `failed` ou `expired`.