Cartão com a Sterling

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

Resumo#

Limites#

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.
• 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:

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.

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#

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.

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.