Throne
OpenAPI Postman Gerar API key Voltar pro gateway

Começar

Checklist de verificação

Roteiro para conferir, passo a passo, se a integração está pronta para vender.

Ver em Markdown

Como usar#

Cada item diz o que conferir e como ver o resultado. Faça na ordem, com a chave de produção e valores baixos. Não existe ambiente de testes: veja Como testar.

Chave e conta#

  • GET /balance com a sua chave responde 200. Um 401 mostra o motivo no campo detail.
  • A chave secreta fica só no seu servidor, nunca no navegador nem no aplicativo.
  • Toda chamada manda Accept: application/json.
  • O cliente HTTP tem timeout: 60 segundos em POST /elements/checkout e POST /elements/checkout/br, e 20 segundos nas demais (por quê).

Criar o checkout de cartão#

  • GET /elements/acquirers?currency= com a moeda do seu público lista as adquirentes habilitadas, a padrão e os limites de valor atuais.
  • POST /elements/checkout responde 201. Confira na resposta: transaction_id, acquirer com a adquirente esperada e expires_at.
  • A Idempotency-Key é gerada antes da chamada e gravada junto do pedido. Num timeout, a repetição usa a mesma chave.
  • O checkout é criado no clique de compra, e o transaction_id é reaproveitado se o mesmo comprador voltar em até 24 horas.

Página de pagamento#

  • O elemento aparece com o data-id certo e sem altura fixa.
  • Sem sandbox em volta do elemento, ou com a lista mínima de Throne Elements.
  • Na NovaCorp, na Eminence, na Apex, na ShadowBank e na Vortex, o checkout_url aberto com ?nl=de mostra o formulário em alemão.
  • O pagamento de um valor baixo, com o seu cartão, termina com throne-elements:paid na página.
  • Ao lado do botão de pagar, um aviso diz que o banco pode pedir a confirmação da compra: na NovaCorp, numa página segura; na Eminence, ali mesmo, dentro do elemento.

Checkout Brasil (se você usa)#

  • A página abre em português, com o campo CPF, e um CPF inválido não deixa pagar.
  • Com appearance, o botão sai com o texto e as cores pedidos, e você conferiu os avisos low_contrast em warnings.

Confirmação da venda#

  • O webhook transaction.paid chega no seu servidor e a assinatura X-Throne-Signature confere.
  • GET /transactions/{id} mostra status: "paid", currency, native_amount_cents e fx_rate.
  • O pedido é liberado pelo webhook ou pelo GET, nunca só pelo evento da página.
  • A conversão da campanha é enviada pelo seu servidor ao receber transaction.paid (como).
  • O histórico de entregas, em Entregas de webhook, mostra a entrega com 2xx.

Erros#

  • Um valor abaixo do mínimo ("amount_cents": 50, "currency": "usd") volta 422 invalid_amount, e a sua tela mostra uma mensagem ao comprador sem repetir a chamada.
  • Um valor acima do max_amount_cents volta 422 invalid_amount, e a sua integração usa alternatives ou divide o pedido.
  • 503 temporarily_unavailable espera o Retry-After e repete com chave nova, poucas vezes.
  • 502 checkout_failed com "retryable": false não é repetido.
  • No painel, em Documentação da API, a lista Últimas chamadas da API mostra as chamadas acima, com o status e o código de erro.
  • Abra a sua página dentro do navegador do Instagram ou do Facebook, no celular, e pague um valor baixo. A aba vai para a página segura de pagamento e termina lá.
  • Mesmo sem evento na página, o seu servidor recebe transaction.paid e libera o pedido.
  • A conversão dessa venda aparece na plataforma de anúncios, enviada pelo servidor.