Cartão com a ShadowBank

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

Para usar a ShadowBank, mande "acquirer": "shadowbank" na criação do checkout. Se a ShadowBank for a padrão da sua conta, o campo é opcional. A ShadowBank é habilitada pelo suporte, conta a conta. Veja Escolher a adquirente.

Nome e e-mail do comprador são obrigatórios na criação. Mande customer.name (até 120 caracteres) e customer.email (e-mail válido, até 180). Sem eles, ou fora desses tamanhos, a chamada volta 422 customer_required_for_shadowbank e nada é criado. O elemento nunca pergunta nome nem e-mail ao comprador: colete os dois na sua página antes de chamar a API. A regra vale sempre que a venda fica com a ShadowBank, inclusive sem o campo acquirer, quando ela é a padrão da conta. Nas outras adquirentes, customer continua opcional. O exemplo abaixo já manda os dois campos.

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": "eur", "acquirer": "shadowbank", "customer": { "name": "Lena Fischer", "email": "lena@example.de" } }'

A resposta 201 traz "acquirer": "shadowbank", e a venda fica na ShadowBank 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": "eur") 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.

No checkout comum (Throne Elements), a ShadowBank não faz recorrência nem upsell em um clique e não atende o Checkout Brasil. Com "acquirer": "shadowbank", o campo recurrence volta 422 recurrence_not_supported, o one_click_from volta one_click: false, sem erro, e o POST /elements/checkout/br volta 422 acquirer_not_enabled.

Na integração direta, que é outra modalidade e precisa de liberação à parte, as duas coisas funcionam: cobrança recorrente e upsell em um clique, e o upsell também pode ser recorrente. O que não existe lá é o parcelamento — a cobrança é sempre à vista.

Resumo#

Limites#

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 ShadowBank 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 ShadowBank, um código pede tratamento próprio: timeout é espera, não recusa.

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 'attempts_exhausted':
    case 'expired':
    case 'ended':
      // este checkout acabou: ofereça outro meio ou crie um checkout novo
      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 ShadowBank 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 ShadowBank 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": "shadowbank" (ou a ShadowBank como padrão da conta), Idempotency-Key nova por venda e timeout de 60 segundos.
• customer.name e customer.email (e-mail válido) enviados na criação, coletados na sua página antes de chamar a API.
• Moeda do comprador em currency, sem ajustar o valor no seu site.
• Máximo da ShadowBank 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.
• 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.