# Cartão com a Sterling

> Regras e comportamento do checkout quando a venda passa pela Sterling (acquirer sterling).

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

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

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

## Resumo

| Item | Na Sterling |
|---|---|
| Verificação do banco | Não tem hoje: o resultado sai na hora |
| 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`) |
| 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 |

## Limites

| Limite | Na Sterling |
|---|---|
| Mínimo por venda | Varia com a moeda e com a cotação do dia, ou o mínimo próprio da Sterling, 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 resultado aparece em poucos segundos, dentro do próprio elemento.
3. Aprovado: o elemento mostra a confirmação e dispara `throne-elements:paid`.
4. Recusado: o elemento mostra o motivo, quantas tentativas restam e um botão para tentar de novo. A venda continua `pending`.

No computador, no celular e no navegador de app (Instagram, Facebook e outros), o pagamento acontece todo dentro do elemento, sem janela nova. Os eventos chegam à sua página nos três casos.

Se a verificação do banco for ligada nesta adquirente no futuro, ela vai aparecer **dentro do próprio checkout**, sem janela nova. Por isso, não fixe a altura do container.

## Requisitos da página

- 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).
- `Accept-Language` na criação, se o público não fala português (veja abaixo).

## Pagamento em análise

Às vezes o pagamento entra em análise antifraude. O comprador vê "Pagamento em análise" e a venda fica `pending` até a decisão:

- aprovado, vira `paid` e o webhook `transaction.paid` é enviado;
- reprovado, vira `failed`.

Não libere o pedido enquanto não chegar `transaction.paid`.

## Idioma das mensagens de recusa

O texto de recusa que o comprador vê (e que chega em `e.detail.message`) segue o header `Accept-Language` da chamada do seu servidor que criou o checkout: português por padrão, inglês com `en` e espanhol com `es`. Para público fora do Brasil, envie o header na criação:

```bash
curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Language: en" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount_cents": 4990, "currency": "usd", "acquirer": "sterling" }'
```

O restante da tela segue o país do comprador, independentemente desse header. Para decidir o que fazer, use `e.detail.code`, que não muda com o idioma.

## Erros do elemento

Além dos códigos comuns, a Sterling pode enviar `token` em `throne-elements:error`: o cartão não passou na validação inicial. O comprador pode corrigir os dados e tentar de novo, e essa falha não consome tentativa. A tabela completa 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."

## 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 |
| Sterling 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)) |

## Quando chega o webhook

Como o resultado sai na hora, o webhook `transaction.paid` costuma sair logo depois da aprovação. Numa venda que entra em análise, ele sai quando a análise aprova. 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. 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`. Não há etapa de defesa pela API.
- 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.
- [ ] `Accept-Language` na criação, se o público não fala português.
- [ ] Container sem altura fixa e sem `sandbox`.
- [ ] Pedido liberado só com `transaction.paid` (assinatura validada).
- [ ] Novo checkout para cada nova tentativa de compra depois de `failed` ou `expired`.