Throne
OpenAPI Postman Gerar API key Voltar pro gateway

Referência

Changelog

O que mudou na API e na documentação, com data.

Ver em Markdown

Como ler#

Toda mudança na API é um acréscimo: campos novos nas respostas, códigos novos ou páginas novas. Nada que já funciona deixa de funcionar sem aviso aqui. Ignore os campos que você não conhece. O formato do webhook transaction.paid (versão 2026-05-01) não mudou.

2026-11-03#

Pix

  • Campo novo retry_same_key no 502 acquirer_error de POST /transactions, só no Pix. Ele vem com true quando a emissão não se confirmou e a cobrança pode existir na adquirente. Nesse caso, repita a mesma chamada, com a mesma Idempotency-Key e o mesmo corpo, e nunca com uma chave nova: ela pode gerar um segundo código pagável para o mesmo pedido. Sem o campo, nada foi criado e a chave nova continua sendo o certo. A exceção é o 502 sem o campo que chega na repetição de um 502 com o campo: ele não descarta a cobrança da primeira tentativa, então fale antes com o suporte.
  • Com "retry_same_key": true, a chave fica livre só para a repetição do mesmo corpo. Com outro corpo (outro valor, outro comprador), a resposta é 422 idempotency_key_mismatch e a chamada não chega à adquirente.
  • Depois de um 502 acquirer_error do Pix, a mesma chave não fica mais presa em 409 idempotency_key_processing por 24 horas: a repetição da mesma chamada roda de novo.
  • No cartão nada muda. O retry_same_key não vem em nenhuma resposta de cartão, e o checkout (POST /elements/checkout) segue a regra de repetição de sempre.

Pix com a Shadow Pix

  • Página nova: Pix com a Shadow Pix, para a conta atendida por essa adquirente. A integração é a mesma do guia de Pix: mesmos endpoints, mesmo corpo, mesmo webhook. O que muda: cobrança só de R$ 10,00 a R$ 5.000,00, timeout de 60 segundos na criação, código pagável no banco por cerca de 2 dias e saque com mínimo de R$ 10,00 na adquirente.
  • O 502 sem retry_same_key também sai quando a adquirente mostra que a chave já está ligada a uma cobrança de outro pedido. Nenhuma cobrança do seu pedido existe lá, e a mesma chave devolve sempre este erro: use uma chave nova. Veja o que fazer num 502.
  • Na repetição de um 502 com retry_same_key, se o comprador já tinha pago aquele código, a resposta é 201 com status: "pending" e payment_data.qr_code_payload vazio. A venda foi registrada: não mostre QR Code e libere o pedido pelo transaction.paid ou por um GET com status: "paid".

Documentação

  • Erros, Comece aqui e Cobrar com Pix separam o 502 com e sem retry_same_key. A referência da API (OpenAPI e coleção do Postman) ganha o campo, os dois exemplos da resposta 502 de POST /transactions e o qr_code_payload vazio da cobrança já paga.
  • Versão da referência (info.version do OpenAPI): 1.13.0.

2026-10-27#

Cartão, recorrência na Vortex

  • Integração direta na ShadowBank: modalidade nova, sem o Throne Elements. O seu servidor tokeniza o cartão em POST /api/v1/vault/shadowbank/cards e cobra em POST /api/v1/shadowbank/payments, na moeda do comprador. Aceita cobrança recorrente e upsell em um clique (POST /api/v1/shadowbank/upsell), e o upsell também pode ser recorrente. Sempre à vista. Liberada caso a caso, à parte das integrações diretas da Eminence e da Vortex. O checkout iframe da ShadowBank não muda em nada, e o webhook continua o mesmo. Guia: Server-to-server na ShadowBank.
  • A Vortex passa a fazer cobrança recorrente. No POST /elements/checkout com "acquirer": "vortex", mande recurrence com cycle (um dos sete, de weekly a yearly) e max_payments opcional: a resposta 201 traz recurrence_id, cycle e next_charge_at, e as cobranças seguintes saem sozinhas, no mesmo cartão. O 422 recurrence_not_supported não vale mais para a Vortex.
  • Cada cobrança de ciclo é uma venda, com transaction_id próprio e o transaction.paid no formato de sempre. O webhook não ganha campo novo. Cobrança de ciclo recusada não cria venda: a recorrência fica past_due.
  • A assinatura só começa a valer quando a primeira cobrança aprova. Na Vortex a aprovação nem sempre é imediata: enquanto a venda está em análise, a recorrência fica em pending e nenhuma cobrança seguinte sai. Se a análise reprovar, nada é assinado.
  • Consulta e cancelamento continuam em GET /recurrences, GET /recurrences/{id} e POST /recurrences/{id}/cancel, com as permissões que já existem.
  • A moeda segue a regra de sempre: você cobra na moeda do seu comprador e a cotação é fixada na criação. Os ciclos seguintes cobram o mesmo valor fixado.
  • A integração direta por API também aceita recurrence (POST /api/v1/vortex/payments), com recurrence_id, cycle e next_charge_at na resposta. Ciclo fora dos sete: 422 invalid_cycle. O 422 recurrence_not_supported continua existindo nesse endpoint, mas agora só quando a cobrança recorrente não está disponível na adquirente.

Documentação

Cartão

  • Vortex: adquirente nova. Mande "acquirer": "vortex" na criação do checkout para usá-la, ou peça ao suporte para deixá-la como padrão da sua conta. A integração é a mesma de sempre: POST /elements/checkout na moeda do comprador, Throne Elements na página, webhook transaction.paid. Campos, respostas, moedas e formato do webhook não mudam.
  • Na Vortex, customer.name (até 120 caracteres) e customer.email (e-mail válido, até 180) são obrigatórios na criação. Sem eles, 422 customer_required_for_vortex e nada é criado. O elemento não pergunta nome nem e-mail ao comprador: colete os dois na sua página antes de chamar a API.
  • A aprovação na Vortex nem sempre é imediata. O banco autoriza na hora, mas a venda ainda passa por uma análise de risco antes de virar paga. Nesse intervalo ela fica pending e o transaction.paid chega quando a análise libera. Não trate pending como falha.
  • A Vortex é à vista e não atende o Checkout Brasil. O upsell em um clique dela chegou depois, na integração direta: veja a entrada de 2026-10-29.

Documentação

  • Página nova: Cartão com a Vortex.
  • vortex entra nos campos acquirer de POST /elements/checkout, na resposta da consulta e em GET /elements/acquirers.
  • Versão da referência (info.version do OpenAPI): 1.10.0.

Cartão, integração direta na Vortex

  • A integração direta por API agora existe também na Vortex. Duas chamadas: POST /api/v1/vault/vortex/cards tokeniza o cartão no seu servidor e POST /api/v1/vortex/payments cobra com esse token, sem o Throne Elements. Guia novo: Server-to-server na Vortex.
  • Ao contrário da integração direta da Eminence, aqui você cobra na moeda do seu comprador, as mesmas 48 do checkout, e currency é obrigatório.
  • customer.name e customer.email são obrigatórios também nesta modalidade. Sem eles, 422 customer_required_for_vortex.
  • Códigos novos no passo 2: currency_not_supported, fx_unavailable (com Retry-After) e amount_out_of_range, que traz min_amount_cents, max_amount_cents e currency sempre na moeda que você enviou.
  • A liberação é por adquirente: quem já usa a integração direta da Eminence precisa pedir a da Vortex à parte. Com a Vortex habilitada na conta e sem essa liberação, continua valendo o checkout comum.
  • Versão da referência (info.version do OpenAPI): 1.11.0.

2026-10-26#

Cartão

  • Integração direta (server-to-server, só Eminence) corrigida. Até hoje as duas chamadas não completavam uma cobrança: nenhuma venda chegou a ser processada por esta modalidade. Quem testou antes deve seguir o contrato abaixo, que é o definitivo.
  • POST /api/v1/vault/eminence/cards passa a exigir Authorization: Bearer com a permissão transactions:write e deve ser chamado do seu servidor. O corpo continua number, exp_month, exp_year, cvv e holder_name (agora obrigatório). A resposta é card_token, brand, last4, exp_month, exp_year e expires_at (token de uso único, até 7 dias). Erros: invalid_card (com field), card_not_supported, scope_required, partner_api_not_enabled, acquirer_not_enabled, rate_limit_exceeded e temporarily_unavailable.
  • POST /api/v1/eminence/payments responde 201 sempre que a venda é criada, com status paid, pending ou failed, além de decline_code, retryable e card. Recusa não é mais 422 declined: vem 201 com status: "failed" e o motivo em acquirer_message. customer.name passa a ser obrigatório, o mínimo passa a R$ 5,00 (422 amount_out_of_range), só à vista, e chaves internas em metadata são recusadas (422 metadata_reserved_key). Erros antes da criação da venda não prendem mais a Idempotency-Key.
  • Estorno da integração direta é pelo suporte, como no cartão comum. A descrição da página antiga dizia "pelo painel"; o correto é pelo suporte.

Documentação

  • Integração direta (parceiros) reescrita com o contrato acima, a tabela de como ler a resposta, os erros reais, os limites e os tempos. A referência da API (OpenAPI e coleção do Postman) acompanha.
  • Versão da referência (info.version do OpenAPI): 1.9.0.

2026-10-22#

Cartão

  • ShadowBank: nome e e-mail do comprador passam a ser obrigatórios na criação do checkout (customer.name e customer.email, com e-mail válido). Sem eles, 422 customer_required_for_shadowbank e nada é criado. O elemento continua sem perguntar nome nem e-mail: colete os dois na sua página antes de chamar a API. Nas outras adquirentes, customer segue opcional. Guia: Cartão com a ShadowBank.
  • A adquirente passa a se chamar ShadowBank. O valor shadowbank do campo acquirer, os endpoints e o webhook não mudam; só o nome exibido (name em GET /elements/acquirers) passa a vir ShadowBank.

Documentação

  • Cartão com a ShadowBank ganha a regra de nome e e-mail, a linha do erro novo e o item no checklist. Erros ganha customer_required_for_shadowbank. A referência da API (OpenAPI e coleção do Postman) ganha o código na lista de erros do POST /elements/checkout e a regra na descrição do campo customer.
  • Versão da referência (info.version do OpenAPI): 1.8.1.

2026-10-21#

Cartão

  • Server-to-server, só Eminence: alternativa ao Throne Elements, para gateway, subadquirente ou agregador que já tem o próprio checkout de cartão. Dois endpoints novos, embaixo da mesma URL base da API: POST /vault/eminence/cards, sem Authorization, tokeniza o cartão em TLS e devolve um card_token de uso único (5 minutos); POST /eminence/payments, com Authorization: Bearer, cobra na Eminence com o card_token e devolve authorized em tempo real. Consulta pelo GET /transactions/{id} que já existe; estorno pelo painel, como no cartão comum. Habilitação caso a caso: fale com o suporte. Nas outras cinco adquirentes a integração continua sendo o Throne Elements. Guia: Server-to-server (parceiros).
  • Erros novos: partner_api_not_enabled, invalid_card_token, expired_card_token, invalid_card (vault), vault_unavailable. acquirer_not_enabled, invalid_amount, declined e rate_limited seguem o mesmo contrato do cartão comum.
  • ShadowBank: adquirente nova, com o valor shadowbank no campo acquirer do POST /elements/checkout. Mesmo endpoint, mesmo Throne Elements, mesmo webhook transaction.paid. Sem verificação do banco, tudo dentro do elemento, 5 tentativas, à vista, nas 48 moedas. Não faz recorrência nem upsell em um clique e não atende o Checkout Brasil. Habilitada pelo suporte, conta a conta. Guia: Cartão com a ShadowBank.
  • shadowbank entra nos valores aceitos de acquirer, na lista do 422 invalid_acquirer e na resposta de GET /elements/acquirers das contas em que estiver habilitada. Integrações que não mandam shadowbank não mudam.

Documentação

  • Página nova Server-to-server (parceiros), com os dois endpoints, exemplos cURL, tabela de erros e checklist. Cartão: como funciona e Cartão com a Eminence ganham um aviso curto apontando para ela. A referência da API (OpenAPI e coleção do Postman) ganha os paths POST /vault/eminence/cards e POST /eminence/payments, com request e response schemas e a tabela de erros.
  • Página nova Cartão com a ShadowBank e coluna nova em Comparar adquirentes. A referência da API (OpenAPI e coleção do Postman) ganha shadowbank no campo acquirer.
  • Versão da referência (info.version do OpenAPI): 1.8.0.

2026-10-20#

Cartão

  • Checkout Brasil, aparência pela API: campo opcional appearance no POST /elements/checkout/br, com o texto do botão, o valor no botão, as cores, o arredondamento, a altura e a largura do botão e uma moldura em volta dos campos. Fora da regra, 422 invalid_appearance, com o caminho da chave em field. Aviso novo low_contrast em warnings. Sem o campo, nada muda. Se você já mandava um campo appearance no Checkout Brasil, ele era ignorado e passa a valer. Veja Aparência.
  • O POST /elements/checkout não muda: appearance continua ignorado nele.

Documentação

  • A referência da API (OpenAPI e coleção do Postman) passa a trazer o que já funcionava desde 2026-10-18: os endpoints GET /recurrences, GET /recurrences/{id} e POST /recurrences/{id}/cancel, os campos one_click_from e recurrence no corpo do POST /elements/checkout, os campos one_click, one_click_card, recurrence_id, cycle e next_charge_at na resposta 201 e os códigos invalid_cycle, recurrence_not_supported e cancel_failed. Nada mudou na API por isso.
  • O timeout de 60 segundos vale também para o POST /elements/checkout/br, como o guia do Checkout Brasil já dizia. Limites e tempos, Comece aqui e o Checklist passam a dizer o mesmo.
  • Versão da referência (info.version do OpenAPI): 1.6.0.

2026-10-19#

Cartão

  • Checkout Brasil: endpoint novo POST /elements/checkout/br, para o comprador brasileiro. Mesmo corpo do POST /elements/checkout (amount_cents, currency e customer opcional), mesma resposta 201, mesmo Throne Elements, mesmos eventos e mesmo webhook transaction.paid. A página sai sempre em português, pede o CPF do comprador junto com o cartão e abre para comprador de qualquer país. Funciona nas adquirentes habilitadas para o Checkout Brasil na conta; peça ao suporte para habilitar. Os campos one_click_from e recurrence não existem neste endpoint: se vierem, 422 field_not_supported. Sem adquirente habilitada para o Checkout Brasil, ou com acquirer pedindo uma que não atende, 422 acquirer_not_enabled. Página nova: Checkout Brasil.
  • O POST /elements/checkout não muda: as integrações que já estão no ar continuam com a mesma requisição, a mesma resposta e o mesmo webhook.

Documentação

  • Página nova na seção Cartão: Checkout Brasil. A referência da API ganha o caminho POST /elements/checkout/br, e Erros ganha o código field_not_supported.
  • Versão da referência (info.version do OpenAPI): 1.5.0.

2026-10-18#

Cartão

  • Recorrência na Apex: campo opcional recurrence no POST /elements/checkout, com os ciclos weekly, biweekly, monthly, bimonthly, quarterly, semiannually e yearly, e max_payments opcional de 2 a 120. A resposta 201 ganha recurrence_id, cycle e next_charge_at. Cada cobrança de ciclo é uma venda, com transaction_id próprio e o mesmo webhook transaction.paid. Consulta e cancelamento em GET /recurrences, GET /recurrences/{id} e POST /recurrences/{id}/cancel, com as permissões que já existem (transactions:read e transactions:write): nenhuma chave de API precisa ser gerada de novo. Códigos novos: invalid_cycle e recurrence_not_supported na criação, invalid_status e cancel_failed nos endpoints de recorrência. Página nova: Recorrência.
  • Upsell em um clique: campo opcional one_click_from no POST /elements/checkout, e os campos one_click e one_click_card na resposta 201. Nenhum código de erro novo: qualquer recusa vira one_click: false e o comprador digita o cartão. Habilitação por conta, pelo suporte. Página nova: Upsell em um clique.
  • Sem os campos novos, nada muda: as integrações que já estão no ar continuam com a mesma requisição, a mesma resposta e o mesmo webhook.

Documentação

  • Duas páginas novas na seção Cartão: Upsell em um clique e Recorrência. As páginas de cartão, comparação, Apex, erros, webhooks e o mapa da documentação passam a citar as duas.

2026-10-16#

Cartão

  • Nova adquirente de cartão Apex (acquirer: "apex"). Mesmo endpoint, mesmo Throne Elements, mesmas moedas e mesmo webhook das outras. Sem verificação do banco: o comprador paga dentro do elemento, em qualquer aparelho e também em navegador de app, e os eventos chegam à sua página em todos os caminhos. Guia em Cartão com a Apex; comparação em Comparar adquirentes.
  • GET /elements/acquirers, o campo acquirer do POST /elements/checkout e o acquirer do GET /transactions/{id} passam a aceitar e devolver apex nas contas em que ela estiver habilitada. Peça ao suporte para habilitar.
  • Throne Elements: na Apex, throne-elements:error traz code com declined, attempts_exhausted, token, network, timeout, limit, expired e ended. timeout só acontece quando a análise antifraude demora. A tabela está em Throne Elements.
  • Guias de cartão, erros, status, moeda, webhooks, testes e checklist passam a incluir a Apex.

Documentação

  • Versão da referência (info.version do OpenAPI): 1.4.0.

2026-10-12#

Pix

  • Novo código 422 pix_not_enabled em POST /transactions (Pix) e POST /payment-links: o recebimento por Pix não está habilitado na conta. Nada é criado; cartão e saques por Pix continuam. A conta sem adquirente Pix, que antes respondia 500, responde este mesmo código. Um link de pagamento já criado mostra "Link indisponível" enquanto o recebimento estiver desabilitado. Linhas novas em Erros e em Cobrar com Pix.

Cartão

  • Eminence disponível para qualquer conta: peça ao suporte para habilitar. O guia Cartão com a Eminence foi refeito por inteiro: exemplo de criação com "acquirer": "eminence", os três caminhos de pagamento (computador, celular e navegador de app, todos dentro do elemento), a verificação do banco dentro do elemento, o pagamento em análise, as tabelas de erros na criação e dos códigos em throne-elements:error (com timeout e limit), um exemplo de tratamento dos eventos na página, quando chega o webhook e o checklist.
  • POST /elements/checkout: a referência ganha um exemplo de corpo com "acquirer": "eminence", e GET /elements/acquirers traz a Eminence no exemplo de resposta.

Documentação

  • A página de moedas do cartão passa a se chamar Moedas e limites (mesmo endereço): as 48 moedas, o mínimo e o máximo por moeda e como a cotação do dia muda os limites.
  • Textos sugeridos para o aviso ao lado do botão de pagar (NovaCorp e Eminence) refeitos, agora também em espanhol.
  • Versão da referência (info.version do OpenAPI): 1.3.0.

2026-10-09#

Cartão

  • Nova adquirente de cartão Eminence (acquirer: "eminence"). Mesmo endpoint, mesmo Throne Elements, mesmas moedas e mesmo webhook das outras. A verificação do banco, quando o banco pede, aparece dentro do próprio elemento. Guia em Cartão com a Eminence; comparação em Comparar adquirentes.
  • GET /elements/acquirers, o campo acquirer do POST /elements/checkout e o acquirer do GET /transactions/{id} passam a aceitar e devolver eminence nas contas em que ela estiver habilitada.
  • Throne Elements: na Eminence, throne-elements:error traz code com declined, attempts_exhausted, token, network, timeout, expired, ended e o código novo limit (a Eminence não aceita o valor da venda no cartão e o checkout fecha como failed). A tabela está em Throne Elements.
  • Guias de cartão, erros, status, moeda, webhooks, testes e checklist passam a incluir a Eminence.

2026-10-06#

Cartão

  • POST /elements/checkout: acima do máximo da adquirente, a resposta passa a ser 422 invalid_amount com max_amount_cents, currency e alternatives. Antes, esse caso podia voltar 502 checkout_failed.
  • POST /elements/checkout: abaixo do mínimo, 422 invalid_amount ganha min_amount_cents, currency e alternatives. Uma adquirente pode ter mínimo próprio, maior que o geral.
  • POST /elements/checkout: adquirente em pausa, instável ou sem capacidade responde 503 temporarily_unavailable, com Retry-After e "retryable": true. Nada é criado.
  • POST /elements/checkout: 502 checkout_failed ganha o campo retryable. Com false, não repita.
  • POST /elements/checkout: a resposta 201 ganha expires_at (fim da validade do checkout, em UTC).
  • POST /elements/checkout: os campos de customer deixam de gerar 422. Um campo fora do formato é ajustado ou descartado, e a resposta 201 traz warnings com field, code e message. O telefone aceita +, parênteses, ponto e barra; o país em 3 letras é convertido para 2; um documento só com números, sem 11 nem 14 dígitos, vale como passaporte; um e-mail inválido é descartado. O código invalid_document deixa de acontecer.
  • GET /elements/acquirers: cada adquirente ganha available. Com ?currency=, ganha também limits, com o mínimo e o máximo por venda na moeda pedida.
  • GET /transactions/{id}: ganha acquirer, com a adquirente da venda (nulo no Pix).
  • Roteamento por valor, opcional por conta: sem o campo acquirer, a venda que passa do máximo da adquirente padrão vai para outra habilitada que aceita o valor. Vem desligado; fale com o suporte para ligar.
  • Throne Elements: throne-elements:error ganha o campo code, fixo e em inglês, na Sterling e na NovaCorp.
  • NovaCorp: as 6 tentativas passam a ser contadas por checkout, no servidor. Na 6ª recusa o checkout fecha como failed. Com tentativas sobrando, ele não fecha enquanto o comprador está na página.

Documentação

2026-10-03#

  • POST /elements/checkout: campo opcional acquirer (sterling, imperium ou novacorp) para escolher a adquirente de cada venda. Códigos 422 invalid_acquirer e 422 acquirer_not_enabled.
  • GET /elements/acquirers: lista as adquirentes de cartão habilitadas na conta, com a padrão marcada.
  • A resposta 201 de POST /elements/checkout ganha acquirer.

2026-10-02#

  • Cartão: nova adquirente NovaCorp.

2026-09-25#

  • Cartão: nova adquirente Imperium.

2026-09-17#

  • Cartão: o valor passa a ser enviado na moeda do comprador, que paga nessa moeda; a cotação que credita o seu saldo é fixada na criação e volta como fx_rate. Códigos 422 currency_not_supported e 422 fx_unavailable.

2026-09-16#

  • POST /elements/checkout: campos opcionais do titular em customer (document, document_type, phone e address). Código 422 invalid_document.

2026-08-18#

  • Chamadas com chave válida deixam de ter limite geral de requisições. O limite de 10 por segundo continua para chamadas sem credencial válida.