Cartão com a Eminence

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

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.

Resumo#

Limites#

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:

Secure payment. Your bank may ask you to confirm this purchase right here, on this page.

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

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

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:

Na página, em throne-elements:error (e.detail.code):

A tabela completa dos códigos, nas seis adquirentes, 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." 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.

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.

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.

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.