Cartão com a Apex

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

Para usar a Apex, mande "acquirer": "apex" na criação do checkout. Se a Apex 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": "apex", "customer": { "name": "Luca Meier", "email": "luca@example.ch" } }'

A resposta 201 traz "acquirer": "apex", e a venda fica na Apex 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.

A Apex é a única adquirente que aceita recorrência (cobrança que se repete sozinha no cartão) e é onde o upsell em um clique está disponível. As duas coisas são campos opcionais do mesmo POST /elements/checkout: veja Recorrência e Upsell em um clique.

Resumo#

Limites#

Se a Apex 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. O resultado sai em poucos segundos, dentro do próprio elemento. Não há etapa do banco nem janela nova.
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.

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 Apex isso não faz diferença: o pagamento acontece todo 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.
• Nenhuma confirmação do banco. Não há código por mensagem, aplicativo do banco nem pergunta de segurança: o cartão é autorizado na hora. Um aviso ao lado do botão de pagar é opcional.
• A fatura. Na fatura do cartão, a compra aparece sem o nome da sua loja.

Textos sugeridos, se quiser avisar:

Secure payment. You will see the result right here, on this page.

Sichere Zahlung. Das Ergebnis erscheint direkt hier auf dieser Seite.

Pago seguro. Verás el resultado aquí mismo, en esta página.

Requisitos da página#

• Não fixe a altura do container e não esconda o overflow: as telas de resultado e de análise mudam a altura do 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. 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, conta como uma recusa: a tentativa é gasta, o elemento mostra o motivo e, com tentativas sobrando, o comprador pode tentar de novo. A venda continua pending; na 5ª recusa o checkout fecha como failed.

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 Apex, 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#

O resultado sai na hora e 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. Se a confirmação da Apex 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. Teste também dentro do navegador do Instagram ou do Facebook, no celular: na Apex 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": "apex" (ou a Apex 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 Apex 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).
• 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.