{"openapi":"3.1.0","info":{"title":"Throne API","version":"1.13.0","summary":"Pix, cartão em 48 moedas, internacional, saldo, saques e webhooks assinados.","description":"Referência de todos os endpoints da API do Throne. Para o passo a passo de cada integração, veja os [guias](https://app.thronecorporate.com/docs). Em texto puro: [/llms.txt](https://app.thronecorporate.com/llms.txt) e [/docs/llms-full.txt](https://app.thronecorporate.com/docs/llms-full.txt).\n\n**URL base:** `https://app.thronecorporate.com/api/v1` (o caminho sempre começa com `/api/v1`).\n\n**Autenticação:** `Authorization: Bearer <public_key>:<secret_key>`, em texto, sem base64. Gere as chaves em [Chaves de API](https://app.thronecorporate.com/painel/api-keys). A chave secreta aparece uma vez só.\n\n**Não existe ambiente de testes separado.** Chaves `pk_test_` funcionam como as de produção: o cartão é cobrado e o saque é pago de verdade.\n\n**Idempotency-Key:** obrigatório em todo `POST` que cria algo (8 a 128 caracteres, um UUID v4 por operação). Mesma chave e mesmo corpo depois de um sucesso devolve a resposta original, com `Idempotent-Replay: true`. Sem resposta (falha de conexão, timeout ou resposta sem o JSON da API): repita com a mesma chave. Depois de um `4xx`, ou de um `502` ou `503` com o JSON da API: nada foi criado, use uma chave nova. A exceção é o `502 acquirer_error` de `POST /transactions` com `retry_same_key: true`: a cobrança pode ter sido criada, então repita com a mesma chave e o mesmo corpo, nunca com uma nova. Depois de um `500`: confira no painel se algo foi criado antes de usar uma chave nova. Tabela completa em [como repetir com segurança](https://app.thronecorporate.com/docs/comecar#como-repetir-uma-chamada-com-seguranca).\n\n**Timeout:** 60 segundos em `POST /elements/checkout` e em `POST /elements/checkout/br`, e 20 segundos nas demais chamadas. Limites e `Retry-After` em [Limites e tempos](https://app.thronecorporate.com/docs/limites).\n\n**Campos novos:** respostas e webhooks podem ganhar campos a qualquer momento, sempre como acréscimo. Ignore o que não conhece. Mudanças com data em [Changelog](https://app.thronecorporate.com/docs/changelog).\n\n**Valores:** sempre inteiros em centavos (`amount_cents`). No cartão, na menor unidade da moeda enviada.\n\n**Erros:** erro de campo volta `422 {message, errors}`; erro de regra volta `{error, message}`. Decida pelo campo `error`. Lista em [Erros](https://app.thronecorporate.com/docs/errors).","contact":{"name":"Suporte Throne","url":"https://app.thronecorporate.com/painel"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://app.thronecorporate.com/api/v1","description":"API pública"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Pix","description":"Cobrança Pix com QR Code e copia e cola, confirmada pelo webhook `transaction.paid`. Guia: [Cobrar com Pix](https://app.thronecorporate.com/docs/pix)."},{"name":"Cartão","description":"Checkout de cartão embutido na sua página (Throne Elements), na moeda do comprador, com a cotação do seu saldo fixada na criação. Adquirentes: Sterling, Imperium, NovaCorp, Eminence, Apex, ShadowBank e Vortex. Com mais de uma habilitada na conta, cada chamada escolhe a sua pelo campo `acquirer`. Campos e respostas são os mesmos nas sete; o comportamento do checkout muda por adquirente. Guia: [Cartão: como funciona](https://app.thronecorporate.com/docs/cartao). Guia: [Comparar adquirentes](https://app.thronecorporate.com/docs/cartao/comparar). Guia: [Checkout Brasil](https://app.thronecorporate.com/docs/cartao/brasil)."},{"name":"Cartão (server-to-server, Eminence)","description":"Integração direta na adquirente Eminence: o seu servidor tokeniza o cartão e cobra pela API, sem o Throne Elements. Para quem já tem o próprio checkout de cartão. Habilitação caso a caso. Guia: [Server-to-server (parceiros)](https://app.thronecorporate.com/docs/cartao/server-to-server)."},{"name":"Cartão (server-to-server, Vortex)","description":"Integração direta na adquirente Vortex: o seu servidor tokeniza o cartão e cobra pela API, na moeda do comprador, sem o Throne Elements. Nome e e-mail do comprador são obrigatórios. Habilitação caso a caso, à parte da Eminence. Guia: [Server-to-server na Vortex](https://app.thronecorporate.com/docs/cartao/vortex-direto)."},{"name":"Cartão (server-to-server, ShadowBank)","description":"Integração direta na adquirente ShadowBank: o seu servidor tokeniza o cartão e cobra pela API, na moeda do comprador, sem o Throne Elements. Aceita cobrança recorrente e upsell em um clique, e o upsell também pode ser recorrente. Sempre à vista. Só o nome do comprador é obrigatório. Habilitação caso a caso, à parte da Eminence e da Vortex. Guia: [Server-to-server na ShadowBank](https://app.thronecorporate.com/docs/cartao/shadowbank-direto)."},{"name":"Recorrências","description":"Consulta e cancelamento das recorrências de cartão, a cobrança que se repete sozinha no ciclo pedido na criação. Permissões que já existem: `transactions:read` para ler e `transactions:write` para cancelar. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias)."},{"name":"Internacional (Paycore)","description":"Botão de pagamento internacional embutido por iframe, com carteira digital ou cartão internacional. Guia: [Internacional (Paycore)](https://app.thronecorporate.com/docs/internacional)."},{"name":"Links de pagamento","description":"Página de pagamento pronta para compartilhar. Cada pagamento vira uma cobrança Pix. Guia: [Links de pagamento](https://app.thronecorporate.com/docs/pix#links-de-pagamento)."},{"name":"Transações","description":"Consulta de uma cobrança Pix, checkout de cartão ou internacional pelo id."},{"name":"Saldo","description":"Saldo Pix da conta, o mesmo que pode ser sacado pela API. Guia: [Saldo e saques](https://app.thronecorporate.com/docs/saques)."},{"name":"Saques","description":"Saque por Pix ou cripto. Exige a permissão `withdrawals:write`, IPs de saque cadastrados e o código do autenticador. **Sem ambiente de testes: o saque sai de verdade.** Guia: [Saldo e saques](https://app.thronecorporate.com/docs/saques)."},{"name":"Saúde","description":"Verificação pública da API, sem autenticação."}],"x-tagGroups":[{"name":"Receber","tags":["Pix","Cartão","Cartão (server-to-server, Eminence)","Cartão (server-to-server, Vortex)","Cartão (server-to-server, ShadowBank)","Recorrências","Internacional (Paycore)","Links de pagamento","Transações"]},{"name":"Conta","tags":["Saldo","Saques"]},{"name":"Sistema","tags":["Saúde"]}],"paths":{"/health":{"get":{"tags":["Saúde"],"summary":"Verificar a API","security":[],"responses":{"200":{"description":"API respondendo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"ok","env":"production","time":"2026-10-03T14:50:00Z"}}}}}}},"/balance":{"get":{"tags":["Saldo"],"summary":"Consultar saldo","description":"Saldo Pix da conta (permissão `balance:read`). O dinheiro de vendas no cartão e no internacional fica numa carteira separada, acompanhada pelo painel, e não aparece aqui.","responses":{"200":{"description":"Saldo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"},"example":{"balance_cents":543210,"pending_balance_cents":0,"reserved_cents":50000,"available_cents":543210,"currency":"BRL"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/transactions":{"post":{"tags":["Pix"],"summary":"Criar cobrança Pix","description":"Cria uma cobrança Pix (permissão `transactions:write`). A resposta traz o copia e cola em `payment_data.qr_code_payload` e a imagem do QR Code em `payment_data.qr_code_image_base64` (PNG em base64 puro).\n\nA cobrança nasce `pending` e vira `paid` quando o pagamento é confirmado. Libere o pedido só com o webhook `transaction.paid` ou com `GET /transactions/{id}` mostrando `paid`. Um Pix pago depois de `expires_at` ainda pode ser confirmado; não existe webhook de expiração.\n\nLimite: 10 cobranças por segundo por conta. Para cartão, use `POST /elements/checkout`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePixRequest"},"examples":{"minimo":{"summary":"Pix de R$ 49,90, só o obrigatório","value":{"payment_method":"pix","amount_cents":4990,"customer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}}},"produto_fisico":{"summary":"Produto físico, com itens e entrega","value":{"payment_method":"pix","amount_cents":29800,"customer":{"name":"Maria Compradora","document":"98765432100","email":"maria@exemplo.com","phone":"+5511988887777"},"items":[{"title":"Camisa Polo, Azul, M","sku":"POLO-AZUL-M","quantity":2,"unit_amount_cents":9900},{"title":"Boné Preto","sku":"BONE-PRETO","quantity":1,"unit_amount_cents":10000}],"shipping_address":{"recipient_name":"Maria Compradora","zip_code":"04567000","street":"Rua das Flores","number":"250","city":"São Paulo","state":"SP","country":"BR","shipping_method":"standard"},"metadata":{"loja_pedido_id":"PED-1042"}}}}}}},"responses":{"201":{"description":"Cobrança criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Campo inválido (`{message, errors}`) ou regra: `invalid_request` (por exemplo, abaixo de R$ 1,00), `pix_not_enabled` (o recebimento por Pix não está habilitado nesta conta; nada foi criado), `items_total_mismatch`, `split_invalid` ou `idempotency_key_mismatch`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/Error"}]},"examples":{"pix_not_enabled":{"summary":"Recebimento por Pix não habilitado","value":{"error":"pix_not_enabled","message":"O recebimento por Pix não está habilitado nesta conta. Cartão e saques continuam disponíveis."}},"invalid_request":{"summary":"Regra de valor ou método","value":{"error":"invalid_request","message":"Valor mínimo de cobrança: R$ 1,00."}},"items_total_mismatch":{"value":{"error":"items_total_mismatch","message":"Sum dos items (1000) não bate com amount_cents (1500). Verifique quantity × unit_amount_cents."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"A adquirente não gerou o Pix. Nada fica gravado no Throne e a Idempotency-Key é liberada (com `retry_same_key: true`, só para a repetição do mesmo corpo: outro corpo recebe 422 idempotency_key_mismatch). Com `retry_same_key: true` o desfecho é incerto: a cobrança pode ter sido criada na adquirente, então repita a chamada com a mesma Idempotency-Key e o mesmo corpo da primeira tentativa, e nunca com uma chave nova, que pode gerar uma segunda cobrança para o mesmo pedido. Sem o campo, nada foi criado para este pedido: a adquirente recusou antes de criar, ou mostrou que a chave já está ligada a uma cobrança de outro pedido, que a mesma chave devolveria sempre. Tente de novo em instantes, com uma chave nova. A exceção é o 502 sem o campo na repetição de um 502 com `retry_same_key: true`: ele não descarta a cobrança da primeira tentativa, então fale com o suporte antes de usar uma chave nova.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["acquirer_error"]},"message":{"type":"string"},"retry_same_key":{"type":"boolean","description":"Só vem com `true`: a cobrança pode ter sido criada. Repita com a mesma Idempotency-Key e o mesmo corpo da primeira tentativa."}}},"examples":{"incerto":{"summary":"Pode ter sido criada: repita com a mesma chave","value":{"error":"acquirer_error","message":"A cobrança pode ter sido criada e não foi confirmada. Repita esta chamada com a mesma Idempotency-Key e o mesmo corpo da primeira tentativa. Não use uma chave nova para este pedido: ela pode gerar uma segunda cobrança.","retry_same_key":true}},"recusado":{"summary":"Nada foi criado","value":{"error":"acquirer_error","message":"Não foi possível gerar a cobrança agora. Tente de novo em instantes, com uma Idempotency-Key nova."}}}}}}}}},"/transactions/{id}":{"get":{"tags":["Transações"],"summary":"Consultar transação","description":"Consulta uma cobrança Pix, um checkout de cartão ou um checkout internacional (permissão `transactions:read`). Use o id exatamente como veio na criação (`id` no Pix, `transaction_id` no cartão e no internacional).\n\nNo cartão e no internacional, enquanto a venda não é paga, `amount_cents`, `fee_cents` e `net_amount_cents` valem 0 e `fx_rate` é nulo. Bandeira e final do cartão vêm só no webhook `transaction.paid`. A API não tem listagem de transações.","parameters":[{"$ref":"#/components/parameters/TransactionId"}],"responses":{"200":{"description":"Transação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/elements/checkout":{"post":{"tags":["Cartão"],"summary":"Criar checkout de cartão (Throne Elements)","description":"Cria um checkout de cartão para embutir na sua página (permissão `transactions:write`). Mande o valor **na moeda do comprador**: é nela que ele paga. A cotação que credita o seu saldo é fixada na criação e volta como `fx_rate` na venda paga.\n\nNa sua página:\n\n```html\n<div data-throne-elements data-id=\"TRANSACTION_ID\" data-color=\"#7c3aed\" data-theme=\"light\" data-radius=\"10\"></div>\n<script src=\"https://app.thronecorporate.com/throne-elements.js\" async></script>\n```\n\nO checkout pede ao comprador só número, validade, CVV e nome impresso no cartão. O idioma segue o país do comprador. A cobrança é à vista. A criação fala com a adquirente: use timeout de 60 segundos no seu cliente HTTP.\n\n**Adquirente.** O campo opcional `acquirer` (`sterling`, `imperium`, `novacorp`, `eminence`, `apex`, `shadowbank` ou `vortex`) escolhe a adquirente desta venda entre as habilitadas na conta; assim a mesma conta usa uma adquirente em cada site. Sem o campo, vale a padrão da conta (em contas com o roteamento por valor ligado, outra habilitada que aceite o valor, quando ele passa do máximo da padrão). Adquirente não habilitada = `422 acquirer_not_enabled`. Com o campo, o Throne nunca troca por outra. A resposta traz `acquirer` com a que ficou com a venda. As habilitadas e os limites de cada uma estão em `GET /elements/acquirers`.\n\n**Por adquirente** (detalhes no guia de cada uma):\n\n- **Sterling**: sem verificação do banco; tudo dentro do elemento; 5 tentativas; fecha como `failed` na 5ª recusa ou 10 minutos depois de uma recusa sem nova tentativa.\n- **Imperium**: sem verificação do banco; tudo dentro do elemento; uma recusa pode levar até 25 segundos; 5 tentativas; fecha como `failed` na 5ª recusa ou 10 minutos depois de uma recusa sem nova tentativa.\n- **NovaCorp**: janela de verificação do banco; em navegador de app (Instagram, Facebook) a própria aba vai para a página segura de pagamento e nenhum evento chega à sua página; 6 tentativas por checkout; fecha como `failed` na 6ª recusa ou a partir de 10 minutos depois da última recusa, com o comprador fora da página.\n- **Eminence**: a verificação do banco, quando ele pede, aparece dentro do próprio elemento, sem janela; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5ª recusa ou 10 minutos depois de uma recusa sem nova tentativa, e na hora numa recusa depois da análise antifraude ou de uma confirmação demorada, ou quando a Eminence não aceita o valor da venda (`limit` na página).\n- **Apex**: sem verificação do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5ª recusa ou 10 minutos depois de uma recusa sem nova tentativa, e na hora quando a Apex não aceita o valor da venda (`limit` na página); uma reprovação na análise antifraude conta como recusa.\n- **ShadowBank**: sem verificação do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5ª recusa ou 10 minutos depois de uma recusa sem nova tentativa; uma reprovação na análise antifraude conta como recusa; `customer.name` (até 120 caracteres) e `customer.email` (e-mail válido, até 180) são obrigatórios na criação (sem eles, ou fora desses tamanhos, `422 customer_required_for_shadowbank`).\n- **Vortex**: sem verificação do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; à vista; a autorização do banco é imediata, mas a venda ainda passa por uma análise de risco antes de virar paga, e nesse intervalo fica `pending` (o `transaction.paid` chega quando a análise libera); uma reprovação na análise conta como recusa; `customer.name` (até 120 caracteres) e `customer.email` (e-mail válido, até 180) são obrigatórios na criação (sem eles, ou fora desses tamanhos, `422 customer_required_for_vortex`).\n\n**Upsell em um clique e recorrência.** Dois campos opcionais: `one_click_from` (o `transaction_id` de uma venda sua, paga) cobra um segundo produto sem pedir o cartão de novo, e `recurrence` (`cycle` e `max_payments` opcional) cria a cobrança que se repete sozinha. Os dois dependem da adquirente. O upsell em um clique depende também de a sua conta estar habilitada para ele (habilitação por conta, pelo suporte): sem a habilitação, ou na adquirente que não aceita, `one_click_from` volta `one_click: false`, sem erro. Na adquirente que não faz cobrança recorrente, `recurrence` volta `422 recurrence_not_supported`, com as que aceitam no `message` (ou o pedido para falar com o suporte, quando nenhuma habilitada na sua conta aceita). Os campos da resposta (`one_click`, `one_click_card`, `recurrence_id`, `cycle` e `next_charge_at`) aparecem só quando a chamada manda o campo. Guias: [Upsell em um clique](https://app.thronecorporate.com/docs/cartao/oneclick) e [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).\n\n**Valores.**\n\n- 48 moedas. Em JPY, KRW, VND, CLP, HUF, TWD e PYG, `amount_cents` é a unidade inteira.\n- O mínimo e o máximo por venda dependem da adquirente e variam com a moeda e com a cotação do dia. Fora deles, `422 invalid_amount` com `min_amount_cents` ou `max_amount_cents` na moeda enviada e, acima do máximo, `alternatives`. Não repita o mesmo valor na mesma adquirente. `GET /elements/acquirers?currency=` mostra os limites atuais.\n\n**Falhas.** `503 temporarily_unavailable` (adquirente em pausa, instável ou sem capacidade): espere o `Retry-After` e repita com uma chave nova, ou use outra adquirente habilitada. `502 checkout_failed`: nada foi criado; repita com chave nova só se `retryable` for `true`. Sem resposta (timeout): repita com a mesma chave.\n\n- Uma recusa com tentativas sobrando mantém a venda `pending`; o fechamento por recusa vira `failed`, pela regra de cada adquirente acima. O checkout vale 24 horas e vira `expired` depois disso.\n- O único webhook do cartão é `transaction.paid`, com `currency` e `native_amount_cents` (a venda na moeda do comprador), `amount_cents` (o valor creditado no seu saldo, em reais) e `fx_rate` (a cotação fixada na criação, texto com 8 casas).\n\nGuias: [Cartão: como funciona](https://app.thronecorporate.com/docs/cartao), [Comparar adquirentes](https://app.thronecorporate.com/docs/cartao/comparar), [Moedas e limites](https://app.thronecorporate.com/docs/cartao/moeda) e [Erros](https://app.thronecorporate.com/docs/errors).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckoutRequest"},"examples":{"moeda_da_conta":{"summary":"Venda em BRL (49,90), a moeda da sua conta","value":{"amount_cents":4990,"currency":"brl","customer":{"name":"Maria Souza","email":"maria@exemplo.com"}}},"moeda_estrangeira":{"summary":"US$ 49,90: o comprador paga em dólar","value":{"amount_cents":4990,"currency":"usd","customer":{"name":"Emma Walker","email":"emma@example.com"}}},"franco_suico":{"summary":"CHF 49,90: o comprador suíço paga em francos","value":{"amount_cents":4990,"currency":"chf","customer":{"name":"Luca Meier","email":"luca@example.ch"}}},"escolher_adquirente":{"summary":"Escolher a adquirente desta venda (NovaCorp)","value":{"amount_cents":4990,"currency":"chf","acquirer":"novacorp"}},"eminence":{"summary":"Escolher a adquirente desta venda (Eminence)","value":{"amount_cents":4990,"currency":"chf","acquirer":"eminence","customer":{"name":"Luca Meier","email":"luca@example.ch"}}},"apex":{"summary":"Escolher a adquirente desta venda (Apex)","value":{"amount_cents":4990,"currency":"chf","acquirer":"apex","customer":{"name":"Luca Meier","email":"luca@example.ch"}}},"shadowbank":{"summary":"Escolher a adquirente desta venda (ShadowBank)","value":{"amount_cents":4990,"currency":"eur","acquirer":"shadowbank","customer":{"name":"Lena Fischer","email":"lena@example.de"}}},"vortex":{"summary":"Escolher a adquirente desta venda (Vortex)","value":{"amount_cents":4990,"currency":"eur","acquirer":"vortex","customer":{"name":"Lena Fischer","email":"lena@example.de"}}},"iene":{"summary":"¥ 5.000: moeda sem casa decimal","value":{"amount_cents":5000,"currency":"jpy"}},"recorrencia":{"summary":"R$ 49,90 por mês, até 12 cobranças (Apex)","value":{"amount_cents":4990,"currency":"brl","acquirer":"apex","recurrence":{"cycle":"monthly","max_payments":12},"customer":{"name":"Ana Souza","email":"ana@exemplo.com"}}},"recorrencia_vortex":{"summary":"€ 49,90 por mês, até 12 cobranças (Vortex)","value":{"amount_cents":4990,"currency":"eur","acquirer":"vortex","recurrence":{"cycle":"monthly","max_payments":12},"customer":{"name":"Lena Fischer","email":"lena@example.de"}}},"um_clique":{"summary":"Upsell em um clique depois de uma venda paga (Apex)","value":{"amount_cents":2990,"currency":"brl","acquirer":"apex","one_click_from":"a1b2c3d4-e5f6-4789-abcd-ef0123456789"}}}}}},"responses":{"201":{"description":"Checkout criado. Use `transaction_id` no `data-id` do Throne Elements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckoutCreated"},"example":{"transaction_id":"ae3bf1da-0c9b-4818-9140-c6432152c23e","status":"pending","checkout_url":"https://pay.example.com/checkout/0f1e2d3c4b5a69788796a5b4c3d2e1f0","acquirer":"novacorp","display":{"currency":"CHF","amount_cents":4990},"expires_at":"2026-10-08T14:20:00Z"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Campo inválido (`{message, errors}`) ou regra: `currency_not_supported`, `fx_unavailable` (com `Retry-After: 60`), `invalid_amount` (com `max_amount_cents` ou `min_amount_cents`, `currency` e `alternatives`), `card_not_enabled`, `invalid_acquirer`, `acquirer_not_enabled`, `customer_required_for_shadowbank` ou `customer_required_for_vortex` (na ShadowBank e na Vortex, sem `customer.name` ou `customer.email`, com e-mail inválido ou fora dos tamanhos: `name` com até 120 caracteres e `email` válido com até 180), `invalid_cycle` (`recurrence.cycle` fora dos sete ciclos, com a lista no `message`), `recurrence_not_supported` (a adquirente da chamada não faz cobrança recorrente) ou `idempotency_key_mismatch` ou `idempotency_key_other_endpoint`. Nada é criado.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/CardCheckoutError"}]},"examples":{"invalid_amount_maximo":{"summary":"Acima do máximo da adquirente","value":{"error":"invalid_amount","message":"Valor acima do máximo aceito nesta adquirente: CHF 318,90.","max_amount_cents":31890,"currency":"CHF","alternatives":["sterling"]}},"invalid_amount":{"summary":"Abaixo do mínimo","value":{"error":"invalid_amount","message":"Valor abaixo do mínimo aceito: CHF 0,80."}},"fx_unavailable":{"value":{"error":"fx_unavailable","message":"Esta moeda está indisponível no momento. Tente de novo em alguns minutos."}},"card_not_enabled":{"value":{"error":"card_not_enabled","message":"Cartão não habilitado nesta conta. Fale com o suporte."}},"acquirer_not_enabled":{"value":{"error":"acquirer_not_enabled","message":"A adquirente imperium não está habilitada nesta conta. Habilitadas: sterling, novacorp."}},"customer_required_for_shadowbank":{"summary":"ShadowBank sem nome ou e-mail do comprador","value":{"error":"customer_required_for_shadowbank","message":"Nome e e-mail do comprador são obrigatórios nesta modalidade."}},"customer_required_for_vortex":{"summary":"Vortex sem nome ou e-mail do comprador","value":{"error":"customer_required_for_vortex","message":"Nome e e-mail do comprador são obrigatórios nesta modalidade."}},"invalid_acquirer":{"value":{"error":"invalid_acquirer","message":"Adquirente desconhecida (\"nova\"). Envie uma destas: sterling, imperium, novacorp, eminence, apex, shadowbank, vortex."}},"invalid_cycle":{"summary":"Ciclo fora dos sete","value":{"error":"invalid_cycle","message":"Ciclo de recorrência inválido (\"mensal\"). Envie um destes: weekly, biweekly, monthly, bimonthly, quarterly, semiannually, yearly."}},"recurrence_not_supported":{"summary":"Adquirente sem cobrança recorrente","value":{"error":"recurrence_not_supported","message":"Esta adquirente não faz cobrança recorrente. Mande o campo acquirer com uma destas: apex, vortex."}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"description":"O checkout não foi criado. `retryable: false` quando a adquirente recusou a criação (não repita igual); `true` numa falha passageira de conexão (repita com uma Idempotency-Key nova).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryableError"},"examples":{"recusado":{"summary":"Não repita","value":{"error":"checkout_failed","message":"Não foi possível criar o checkout.","retryable":false}},"passageiro":{"summary":"Repita com chave nova","value":{"error":"checkout_failed","message":"Não foi possível criar o checkout.","retryable":true}}}}}},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/elements/checkout/br":{"post":{"tags":["Cartão"],"summary":"Criar Checkout Brasil (cartão em português, com CPF)","description":"Cria um checkout de cartão para o comprador brasileiro (permissão `transactions:write`), para embutir na sua página com o mesmo Throne Elements do checkout comum. 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. O nome e o CPF digitados vão para a adquirente na autorização.\n\nO corpo é o mesmo de `POST /elements/checkout`: `amount_cents`, `currency` e `customer` opcional, mais `appearance` (veja abaixo). Os campos `one_click_from` e `recurrence` não existem aqui: se vierem, `422 field_not_supported` e nada é criado. `metadata` e itens não são aceitos.\n\n**Adquirente.** A venda vai para a adquirente habilitada para o Checkout Brasil na sua conta. O campo `acquirer` é opcional e só aceita uma que atenda o Checkout Brasil; outra volta `422 acquirer_not_enabled`. Sem nenhuma habilitada, o mesmo `422 acquirer_not_enabled`, com a mensagem pedindo para falar com o suporte. O roteamento fixado na conta e o roteamento por valor não valem neste endpoint. A resposta traz `acquirer` com a que ficou com a venda, e o comportamento da página depois do clique em pagar é o dessa adquirente, como no checkout comum.\n\n**CPF.** O comprador digita o CPF na página; ele é conferido antes do envio e vai para a adquirente junto com o cartão e o nome. O Throne não guarda o CPF digitado, e ele não volta na consulta nem no webhook. O `customer.document` da criação continua opcional e segue a regra do checkout comum.\n\n**Aparência.** `appearance` ajusta a página na criação: texto do botão, valor no botão, cores, formato, tamanho e moldura. Toda chave é opcional; a que não vier segue o padrão e os atributos `data-color` e `data-radius` do elemento. Fora da regra, `422 invalid_appearance`, com o caminho da chave em `field`; contraste baixo aceito vira o aviso `low_contrast` em `warnings`. Guia: [Aparência](https://app.thronecorporate.com/docs/cartao/brasil#aparencia).\n\nMoedas, limites, tentativas, validade de 24 horas, eventos do Throne Elements, status e webhook `transaction.paid`: iguais ao checkout comum. Use timeout de 60 segundos no seu cliente HTTP.\n\nGuia: [Checkout Brasil](https://app.thronecorporate.com/docs/cartao/brasil).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckoutBrRequest"},"examples":{"reais":{"summary":"R$ 97,00, só o obrigatório","value":{"amount_cents":9700,"currency":"brl"}},"com_comprador":{"summary":"R$ 97,00 com os dados do comprador","value":{"amount_cents":9700,"currency":"brl","customer":{"name":"Maria Souza","email":"maria@exemplo.com"}}},"aparencia":{"summary":"R$ 97,00 com texto, cor e moldura","value":{"amount_cents":9700,"currency":"brl","appearance":{"button":{"text":"Finalizar compra","background_color":"#15803d"},"frame":{"border_width":1,"padding":24,"shadow":"md"}}}}}}}},"responses":{"201":{"description":"Checkout criado. Use `transaction_id` no `data-id` do Throne Elements. Os campos são os do checkout comum, sem os do upsell em um clique e os da recorrência. `acquirer` traz a adquirente que ficou com a venda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckoutBrCreated"},"example":{"transaction_id":"c4d7a2b1-6e3f-4a9c-8b5d-2f1e0a9c7b63","status":"pending","checkout_url":"https://pay.example.com/checkout/5a4b3c2d1e0f99887766554433221100","display":{"currency":"BRL","amount_cents":9700},"expires_at":"2026-10-20T14:20:00Z"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Campo inválido (`{message, errors}`) ou regra: `acquirer_not_enabled` (nenhuma adquirente habilitada para o Checkout Brasil na conta, ou `acquirer` pediu uma que não atende), `field_not_supported` (`one_click_from` ou `recurrence` no corpo), `invalid_appearance` (com o caminho da chave em `field`), `currency_not_supported`, `fx_unavailable` (com `Retry-After: 60`), `invalid_amount` (com `max_amount_cents` ou `min_amount_cents`, `currency` e `alternatives`), `card_not_enabled`, `invalid_acquirer` ou `idempotency_key_mismatch` ou `idempotency_key_other_endpoint`. Nada é criado.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/CardCheckoutBrError"}]},"examples":{"acquirer_not_enabled_conta":{"summary":"Nenhuma adquirente habilitada para o Checkout Brasil","value":{"error":"acquirer_not_enabled","message":"O Checkout Brasil não está habilitado para nenhuma adquirente da sua conta. Fale com o suporte."}},"acquirer_not_enabled_campo":{"summary":"O campo acquirer pediu uma adquirente que não atende","value":{"error":"acquirer_not_enabled","message":"A adquirente pedida não está habilitada para o Checkout Brasil na sua conta."}},"field_not_supported":{"summary":"one_click_from ou recurrence no corpo","value":{"error":"field_not_supported","message":"O campo one_click_from não é aceito no Checkout Brasil. Remova o campo e repita a chamada."}},"invalid_appearance":{"summary":"Chave de appearance que não existe","value":{"error":"invalid_appearance","message":"appearance.button.color não existe. Em appearance.button valem: text, show_amount, background_color, text_color, radius, height e full_width.","field":"appearance.button.color"}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"description":"O checkout não foi criado. `retryable: false` quando a adquirente recusou a criação (não repita igual); `true` numa falha passageira de conexão (repita com uma Idempotency-Key nova).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryableError"},"examples":{"recusado":{"summary":"Não repita","value":{"error":"checkout_failed","message":"Não foi possível criar o checkout.","retryable":false}},"passageiro":{"summary":"Repita com chave nova","value":{"error":"checkout_failed","message":"Não foi possível criar o checkout.","retryable":true}}}}}},"503":{"description":"A adquirente do Checkout Brasil está em pausa, instável ou sem capacidade de criação no momento, ou o checkout não pôde ser concluído agora. Nada foi criado. Espere o `Retry-After` (segundos) e repita com uma Idempotency-Key nova. Aqui a resposta não sugere outra adquirente.","headers":{"Retry-After":{"description":"Segundos para esperar antes de repetir.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryableError"},"examples":{"pausa":{"summary":"Adquirente em pausa ou instável","value":{"error":"temporarily_unavailable","message":"A adquirente escolhida está temporariamente indisponível. Tente em instantes.","retryable":true}},"passageiro":{"summary":"Falha passageira ao concluir","value":{"error":"temporarily_unavailable","message":"Não foi possível concluir o checkout agora. Tente de novo em instantes.","retryable":true}}}}}}}}},"/vault/eminence/cards":{"post":{"tags":["Cartão (server-to-server, Eminence)"],"summary":"Tokenizar o cartão (integração direta Eminence)","description":"Primeira chamada da integração direta: troca o cartão por um `card_token` de uso único, para cobrar com `POST /eminence/payments` no passo 2.\n\n**Com a sua chave de API** (permissão `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integração direta liberada na conta, `422 partner_api_not_enabled`.\n\n**Validade do token:** uso único, até 7 dias (`expires_at`). Aceita cartões de crédito Visa, Mastercard, Elo, American Express e Hipercard.\n\nGuia: [Integração direta (parceiros)](https://app.thronecorporate.com/docs/cartao/server-to-server).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreateRequest"},"example":{"number":"5555666677778884","exp_month":12,"exp_year":2030,"cvv":"123","holder_name":"LUCA MEIER"}}}},"responses":{"201":{"description":"Cartão tokenizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreated"},"example":{"card_token":"9f0d4a1c7e2b48b1a3d0f6c89e2a4b7c","brand":"mastercard","last4":"8884","exp_month":12,"exp_year":2030,"expires_at":"2026-11-02T15:12:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`scope_required`: a chave não tem a permissão `transactions:write`. `seller_not_approved`: a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"422":{"description":"`invalid_card`: número, validade, CVV ou nome inválidos (o campo `field` diz qual). `card_not_supported`: bandeira ou tipo de cartão não aceito. `partner_api_not_enabled` ou `acquirer_not_enabled`: fale com o suporte.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_card","card_not_supported","partner_api_not_enabled","acquirer_not_enabled"]},"message":{"type":"string"}}}}}},"429":{"description":"Limite de requisições por segundo. Aguarde 1 segundo e repita.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"}}}}}},"503":{"description":"Tokenização indisponível no momento. Repita em alguns segundos.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"message":{"type":"string"}}}}}}}}},"/eminence/payments":{"post":{"tags":["Cartão (server-to-server, Eminence)"],"summary":"Cobrar na Eminence (integração direta)","description":"Segunda chamada da integração direta: cobra na Eminence com o `card_token` do passo 1 (permissão `transactions:write`), à vista e em reais. A resposta já traz o resultado.\n\n**Venda criada responde sempre `201`** com o `status`: `paid` (aprovado, já na carteira), `pending` (em análise ou em confirmação: aguarde o webhook ou consulte; não cobre de novo) ou `failed` (recusado ou não processado, nada cobrado; `retryable` diz se vale uma nova cobrança). Erros `4xx`, `429` e `503` antes da cobrança significam que nada foi criado.\n\n**Habilitação caso a caso.** Sem a liberação na conta, `422 partner_api_not_enabled`. Sem a Eminence habilitada, `422 acquirer_not_enabled`. [Fale com o suporte](https://app.thronecorporate.com/painel) para liberar.\n\nA venda é uma transação comum do Throne: consulte pelo `GET /transactions/{id}` e acompanhe pelo webhook `transaction.paid`. Estorno pelo suporte. A parte financeira é a mesma do cartão pelo Throne Elements.\n\nGuia: [Integração direta (parceiros)](https://app.thronecorporate.com/docs/cartao/server-to-server).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EminencePartnerPaymentRequest"},"example":{"amount_cents":4990,"card_token":"9f0d4a1c7e2b48b1a3d0f6c89e2a4b7c","customer":{"name":"Ana Souza","email":"ana@exemplo.com"},"description":"Assinatura mensal","metadata":{"order_id":"ORD-2026-00001"}}}}},"responses":{"201":{"description":"Cobrança criada (o resultado está em `status`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EminencePartnerPaymentCreated"},"example":{"transaction_id":"ae3bf1da-0c9b-4818-9140-c6432152c23e","status":"paid","authorized":true,"acquirer":"eminence","acquirer_message":"Pagamento autorizado.","decline_code":null,"retryable":false,"card":{"brand":"mastercard","last4":"8884"},"amount_cents":4990,"currency":"BRL","created_at":"2026-10-26T15:12:00Z"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"A chave sem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"Permissão faltando","value":{"error":"scope_required","message":"Esta credencial não tem o scope necessário: transactions:write."}},"seller_not_approved":{"summary":"Conta não aprovada","value":{"error":"seller_not_approved","message":"Conta não liberada para cobrar. Fale com o suporte."}}}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Nada foi criado. `validation_failed` (com `errors`), `partner_api_not_enabled`, `acquirer_not_enabled`, `invalid_card_token`, `amount_out_of_range` (com `min_amount_cents` e `max_amount_cents`), `metadata_reserved_key` ou `idempotency_key_mismatch`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EminencePartnerPaymentError"},"examples":{"partner_api_not_enabled":{"summary":"Integração direta não liberada","value":{"error":"partner_api_not_enabled","message":"Modalidade de parceiro não habilitada nesta conta. Fale com o suporte."}},"acquirer_not_enabled":{"summary":"Eminence não habilitada","value":{"error":"acquirer_not_enabled","message":"A Eminence não está habilitada nesta conta."}},"amount_out_of_range":{"summary":"Fora da faixa","value":{"error":"amount_out_of_range","message":"Valor fora da faixa aceita: de R$ 5,00 a R$ 50.000,00.","min_amount_cents":500,"max_amount_cents":5000000}},"metadata_reserved_key":{"summary":"Chave reservada","value":{"error":"metadata_reserved_key","message":"A chave \"throne_x\" é reservada ou inválida em metadata. Use outro nome."}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/vault/vortex/cards":{"post":{"tags":["Cartão (server-to-server, Vortex)"],"summary":"Tokenizar o cartão (integração direta Vortex)","description":"Primeira chamada da integração direta na Vortex: troca o cartão por um `card_token` de uso único, para cobrar com `POST /vortex/payments` no passo 2.\n\n**Com a sua chave de API** (permissão `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integração direta da Vortex liberada na conta, `422 partner_api_not_enabled`. A liberação é por adquirente: a da Eminence não vale aqui.\n\n**Validade do token:** uso único, até 7 dias (`expires_at`).\n\nGuia: [Server-to-server na Vortex](https://app.thronecorporate.com/docs/cartao/vortex-direto).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreateRequest"},"example":{"number":"4000000000000010","exp_month":12,"exp_year":2030,"cvv":"123","holder_name":"LENA FISCHER"}}}},"responses":{"201":{"description":"Cartão tokenizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreated"},"example":{"card_token":"ac1c3b53b22d47e2baa7b81662dc3a82","brand":"visa","last4":"0010","exp_month":12,"exp_year":2030,"expires_at":"2026-11-03T06:35:06Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`scope_required`: a chave não tem a permissão `transactions:write`. `seller_not_approved`: a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"422":{"description":"`invalid_card`: número, validade, CVV ou nome inválidos (o campo `field` diz qual). `partner_api_not_enabled` ou `acquirer_not_enabled`: fale com o suporte.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_card","partner_api_not_enabled","acquirer_not_enabled"]},"message":{"type":"string"}}}}}},"429":{"description":"Limite de requisições por segundo. Aguarde 1 segundo e repita.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"}}}}}},"503":{"description":"Tokenização indisponível no momento. Repita em alguns segundos.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"message":{"type":"string"}}}}}}}}},"/vault/shadowbank/cards":{"post":{"tags":["Cartão (server-to-server, ShadowBank)"],"summary":"Tokenizar o cartão (integração direta ShadowBank)","description":"Primeira chamada da integração direta na ShadowBank: troca o cartão por um `card_token`, para cobrar com `POST /shadowbank/payments` no passo 2.\n\n**Com a sua chave de API** (permissão `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integração direta da ShadowBank liberada na conta, `422 partner_api_not_enabled`. A liberação é por adquirente: a da Eminence e a da Vortex não valem aqui.\n\n**Validade do token:** até 7 dias (`expires_at`), e nunca depois do fim do mês de validade do cartão.\n\n**O bloco `customer` é opcional e recomendado.** Dele só o nome chega à adquirente; o resto serve para que o mesmo comprador caia sempre no mesmo cadastro do lado dela quando voltar a comprar — e é isso que dá ao upsell em um clique um cartão para reencontrar. Mande o mesmo `customer` que você vai mandar na cobrança.\n\nGuia: [Server-to-server na ShadowBank](https://app.thronecorporate.com/docs/cartao/shadowbank-direto).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreateRequest"},"example":{"number":"5555555555554444","exp_month":11,"exp_year":2031,"cvv":"737","holder_name":"MARIA S SOUZA","customer":{"name":"Maria Souza","email":"maria@exemplo.com"}}}}},"responses":{"201":{"description":"Cartão tokenizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardVaultCreated"},"example":{"card_token":"sbt_7b58f4a1600bd9419cb20b7f111bc831","brand":"mastercard","last4":"4444","exp_month":11,"exp_year":2031,"expires_at":"2026-11-09T03:00:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`scope_required`: a chave não tem a permissão `transactions:write`. `seller_not_approved`: a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"422":{"description":"`invalid_card`: número, validade, CVV ou nome inválidos (o campo `field` diz qual). `partner_api_not_enabled` ou `acquirer_not_enabled`: fale com o suporte.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_card","partner_api_not_enabled","acquirer_not_enabled"]},"message":{"type":"string"}}}}}},"429":{"description":"Limite de requisições por segundo. Aguarde 1 segundo e repita.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"}}}}}},"503":{"description":"Tokenização indisponível no momento. Repita em alguns segundos.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"message":{"type":"string"}}}}}}}}},"/shadowbank/payments":{"post":{"tags":["Cartão (server-to-server, ShadowBank)"],"summary":"Cobrar no cartão (integração direta ShadowBank)","description":"Segunda chamada da integração direta na ShadowBank: cobra o `card_token` do passo 1. Você cobra na **moeda do seu comprador** e a cotação que credita o seu saldo é fixada aqui.\n\n**Só o nome do comprador é obrigatório** (`customer.name`, até 120 caracteres). O e-mail é opcional: esta adquirente cobra sem ele. Sem o nome, `422 customer_required_for_shadowbank` e nada é criado.\n\n**Sempre à vista.** `installments` só aceita `1`.\n\n**Contrato da resposta.** Antes de a venda nascer, erro `4xx`/`503` e a `Idempotency-Key` fica livre. Depois que ela nasce, **sempre `201`**, com o `status` real: `paid` (aprovado), `pending` (em análise ou indefinido — **não repita**) ou `failed` (recusado; `retryable` diz se pode tentar de novo com um token novo).\n\n`pending` é desfecho normal, não erro: a cobrança pode cair em análise da adquirente e fechar depois, pelo webhook.\n\n**Cobrança recorrente:** mande `recurrence` e esta cobrança vira a primeira de uma assinatura. A adquirente guarda o cartão e cobra os ciclos seguintes sozinha, a partir do ciclo 2 — o comprador nunca é cobrado duas vezes no mesmo dia. A assinatura só abre se esta cobrança for aprovada.\n\n**Upsell em um clique:** não é aqui. Use `POST /shadowbank/upsell` com a venda de origem em `parent_transaction_id`; `one_click_from` nesta rota volta `422 field_not_supported`.\n\nGuia: [Server-to-server na ShadowBank](https://app.thronecorporate.com/docs/cartao/shadowbank-direto).","parameters":[{"$ref":"#/components/schemas/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents","currency","card_token","customer"],"properties":{"amount_cents":{"type":"integer","minimum":1,"description":"Valor na menor unidade da moeda."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Uma das 48 moedas aceitas."},"card_token":{"type":"string","description":"O token do passo 1."},"installments":{"type":"integer","enum":[1],"description":"Sempre 1: esta modalidade cobra à vista."},"description":{"type":"string","maxLength":255},"customer":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","maxLength":180,"description":"Opcional nesta adquirente."}}},"metadata":{"type":"object","description":"Até 20 chaves de texto, número ou booleano."},"recurrence":{"type":"object","required":["cycle"],"properties":{"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"max_payments":{"type":"integer","minimum":2,"maximum":120,"description":"Contando a primeira cobrança. Sem ele, a assinatura não tem fim."}}}}},"examples":{"avulsa":{"summary":"R$ 25,00 à vista","value":{"amount_cents":2500,"currency":"BRL","card_token":"sbt_7b58f4a1600bd9419cb20b7f111bc831","description":"Plano Pro","customer":{"name":"Maria Souza","email":"maria@exemplo.com"}}},"recorrente":{"summary":"R$ 25,00 por mês, até 12 cobranças","value":{"amount_cents":2500,"currency":"BRL","card_token":"sbt_7b58f4a1600bd9419cb20b7f111bc831","customer":{"name":"Maria Souza"},"recurrence":{"cycle":"monthly","max_payments":12}}}}}}},"responses":{"201":{"description":"Venda criada (o `status` traz o resultado real)","content":{"application/json":{"schema":{"type":"object"},"example":{"transaction_id":"a960cd5a-a166-4e16-8e28-72a64b4013ed","status":"paid","authorized":true,"amount_cents":2500,"currency":"BRL","installments":1,"message":"Pagamento aprovado.","created_at":"2026-11-02T01:15:35-03:00","card":{"brand":"mastercard","last4":"4444"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"A chave não tem `transactions:write`, ou a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"`invalid_card_token`: token fora do formato, inexistente ou expirado — gere outro. `customer_required_for_shadowbank`: sem `customer.name`. `field_not_supported`: você mandou `one_click_from` (use `POST /shadowbank/upsell`). `card_data_not_allowed`: dado de cartão em `metadata`. Nada é criado em nenhum destes.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["validation_failed","invalid_card_token","customer_required_for_shadowbank","currency_not_supported","fx_unavailable","amount_out_of_range","partner_api_not_enabled","acquirer_not_enabled","metadata_reserved_key","card_data_not_allowed","field_not_supported","invalid_cycle","recurrence_not_supported"]},"message":{"type":"string"}}}}}},"429":{"description":"Limite de requisições por segundo da conta.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"}}}}}},"503":{"description":"Adquirente pausada, disjuntor aberto ou muitas cobranças em voo. Nada foi criado.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["temporarily_unavailable","busy"]},"message":{"type":"string"}}}}}}}}},"/shadowbank/upsell":{"post":{"tags":["Cartão (server-to-server, ShadowBank)"],"summary":"Upsell em um clique (integração direta ShadowBank)","description":"Cobra o **mesmo cartão** de uma venda que já foi paga, sem pedir o cartão ao comprador de novo e **sem `card_token` nenhum**. Você manda só o `transaction_id` da venda de origem, em `parent_transaction_id`.\n\nPrecisa, além da integração direta liberada, do **upsell em um clique habilitado na conta** — é por conta, não por adquirente. Sem ele, `403 one_click_not_enabled`.\n\n**O upsell pode ser recorrente:** mande `recurrence` e ele vira a primeira cobrança de uma assinatura, igual à cobrança comum.\n\n**O que a venda de origem precisa ser:** sua, paga, na ShadowBank, dentro da janela do um clique (2 horas por padrão), com o cartão guardado e abaixo do limite de upsells por venda (5). Qualquer um desses faltando é `409`, e várias dessas situações respondem a MESMA coisa de propósito — a resposta não conta nada a mais sobre a venda de origem do que você já sabe.\n\n**O valor tem um teto próprio:** o menor entre um limite absoluto e vinte vezes o valor da venda de origem. Ele existe porque o comprador não digita nada nesta cobrança.\n\n**Campos que esta rota não tem:** `card_token`, `customer`, `installments` e `one_click_from`. Qualquer um deles é `422 field_not_supported`, com o nome em `field` — nunca descartado em silêncio.\n\nGuia: [Server-to-server na ShadowBank](https://app.thronecorporate.com/docs/cartao/shadowbank-direto#upsell-em-um-clique).","parameters":[{"$ref":"#/components/schemas/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parent_transaction_id","amount_cents","currency"],"properties":{"parent_transaction_id":{"type":"string","maxLength":64,"description":"O `transaction_id` da venda de origem, nunca o id da adquirente."},"amount_cents":{"type":"integer","minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3},"description":{"type":"string","maxLength":255},"metadata":{"type":"object"},"recurrence":{"type":"object","required":["cycle"],"properties":{"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"max_payments":{"type":"integer","minimum":2,"maximum":120}}}}},"examples":{"avulso":{"summary":"R$ 15,00 no mesmo cartão","value":{"parent_transaction_id":"a960cd5a-a166-4e16-8e28-72a64b4013ed","amount_cents":1500,"currency":"BRL","description":"Garantia estendida"}},"recorrente":{"summary":"R$ 20,00 por mês, até 6 cobranças","value":{"parent_transaction_id":"a960cd5a-a166-4e16-8e28-72a64b4013ed","amount_cents":2000,"currency":"BRL","description":"Clube mensal","recurrence":{"cycle":"monthly","max_payments":6}}}}}}},"responses":{"201":{"description":"Upsell criado (o `status` traz o resultado real)","content":{"application/json":{"schema":{"type":"object"},"example":{"transaction_id":"7fb09848-911d-45ee-97ee-2d0847c2d3eb","status":"paid","authorized":true,"amount_cents":1500,"currency":"BRL","installments":1,"one_click":true,"message":"Pagamento aprovado.","created_at":"2026-11-02T01:24:35-03:00","card":{"brand":"visa","last4":"1881"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`one_click_not_enabled`: o upsell em um clique não está habilitado na conta (é por conta, não por adquirente).","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["one_click_not_enabled","scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"409":{"description":"A venda de origem não serve. Nada foi cobrado.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["parent_not_found","parent_not_paid","parent_refunded","parent_charged_back","parent_too_old","upsell_limit_reached","parent_other_acquirer","one_click_unavailable"]},"message":{"type":"string"}}}}}},"422":{"description":"`field_not_supported`: você mandou `card_token`, `customer`, `installments` ou `one_click_from` (o nome vem em `field`). `amount_out_of_range`: acima do teto do upsell.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["validation_failed","field_not_supported","amount_out_of_range","currency_not_supported","fx_unavailable","partner_api_not_enabled","acquirer_not_enabled","metadata_reserved_key","card_data_not_allowed","invalid_cycle","recurrence_not_supported"]},"message":{"type":"string"}}}}}},"429":{"description":"Limite de requisições por segundo da conta.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"}}}}}},"503":{"description":"`busy`: outro upsell desta venda de origem está em andamento, ou muitos em voo. Nada foi criado.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["temporarily_unavailable","busy"]},"message":{"type":"string"}}}}}}}}},"/vortex/payments":{"post":{"tags":["Cartão (server-to-server, Vortex)"],"summary":"Cobrar na Vortex (integração direta)","description":"Segunda chamada da integração direta na Vortex: cobra com o `card_token` do passo 1 (permissão `transactions:write`), **na moeda do seu comprador**, à vista. A resposta já traz o resultado.\n\n**Nome e e-mail do comprador são obrigatórios** (`customer.name` até 120 caracteres, `customer.email` válido até 180). Sem eles, `422 customer_required_for_vortex` e nada é criado. **O `customer.ip` também é obrigatório**: é o IP de onde o comprador está, nunca o do seu servidor, e sem ele a chamada volta `422 customer_ip_required_for_vortex`. Mande também o `customer.document` quando o comprador tiver um: os dois entram na análise de risco da adquirente e aumentam a aprovação.\n\n**Venda criada responde sempre `201`** com o `status`: `paid` (aprovado, já na carteira), `pending` (autorizado pelo banco e em análise de risco: aguarde o webhook ou consulte; não cobre de novo) ou `failed` (recusado ou não processado, nada cobrado; `retryable` diz se vale uma nova cobrança). Erros `4xx`, `429` e `503` antes da cobrança significam que nada foi criado.\n\n**A aprovação nem sempre é imediata.** Na Vortex o banco autoriza na hora e a venda ainda passa por análise de risco. Nesse intervalo o `status` é `pending`, e isso é normal.\n\n**Recorrência.** `recurrence` com `cycle` (um dos sete) e `max_payments` opcional, de 2 a 120, contando esta cobrança: esta é a primeira e as seguintes saem sozinhas, no mesmo cartão. A resposta `201` traz `recurrence_id`, `cycle` e `next_charge_at`. A assinatura só passa a valer quando esta cobrança aprova, e aqui a aprovação nem sempre é imediata: até lá a recorrência fica em `pending`. `recurrence_id` nulo quer dizer que a assinatura não abriu e não haverá cobranças seguintes. Ciclo fora dos sete: `422 invalid_cycle`, nada criado. Consulta e cancelamento em `/recurrences`. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).\n\n**Habilitação caso a caso**, à parte da Eminence. Sem a liberação, `422 partner_api_not_enabled`. Sem a Vortex habilitada, `422 acquirer_not_enabled`.\n\nA venda é uma transação comum do Throne: consulte pelo `GET /transactions/{id}` e acompanhe pelo webhook `transaction.paid`. Estorno pelo suporte.\n\nGuia: [Server-to-server na Vortex](https://app.thronecorporate.com/docs/cartao/vortex-direto).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents","currency","card_token","customer"],"properties":{"amount_cents":{"type":"integer","minimum":1,"description":"Valor na menor unidade da moeda enviada."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Uma das 48 moedas do checkout, maiúsculas ou minúsculas."},"card_token":{"type":"string","description":"O token do passo 1. Uso único."},"customer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","maxLength":180},"phone":{"type":"string","maxLength":30},"ip":{"type":"string","description":"IP do comprador. Melhora a análise de risco."},"document":{"type":"string","maxLength":20}}},"description":{"type":"string","maxLength":255},"metadata":{"type":"object","description":"Até 20 chaves com valores simples. Chaves reservadas são recusadas."},"recurrence":{"type":"object","required":["cycle"],"description":"Opcional. Recorrência: esta cobrança é a primeira e as seguintes saem sozinhas, no mesmo cartão. A assinatura só passa a valer quando esta cobrança aprova. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","properties":{"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"],"description":"Ciclo das cobranças. Outro valor: `422 invalid_cycle`, com a lista no `message`.","example":"monthly"},"max_payments":{"type":"integer","minimum":2,"maximum":120,"description":"Opcional. Teto de cobranças, contando esta. Sem ele, a recorrência segue até você cancelar.","example":12}}}}},"example":{"amount_cents":4990,"currency":"eur","card_token":"ac1c3b53b22d47e2baa7b81662dc3a82","customer":{"name":"Lena Fischer","email":"lena@exemplo.de","phone":"+4915112345678","ip":"91.64.12.33"},"description":"Plano anual","metadata":{"order_id":"ORD-2026-00001"}}}}},"responses":{"201":{"description":"Cobrança criada (o resultado está em `status`)","content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["paid","pending","failed"]},"authorized":{"type":"boolean"},"acquirer":{"type":"string","enum":["vortex"]},"acquirer_message":{"type":"string"},"decline_code":{"type":["string","null"]},"retryable":{"type":"boolean"},"card":{"type":"object","properties":{"brand":{"type":["string","null"]},"last4":{"type":["string","null"]}}},"amount_cents":{"type":"integer","description":"O valor que você cobrou, na moeda enviada."},"currency":{"type":"string","description":"A moeda que você enviou."},"created_at":{"type":"string","format":"date-time"},"recurrence_id":{"type":["string","null"],"pattern":"^rec_[0-9a-f]{24}$","description":"Só quando a chamada manda `recurrence`: a recorrência, para consultar e cancelar em `/recurrences/{id}`. Nulo, com `cycle` e `next_charge_at` nulos: a cobrança foi criada, mas a assinatura não abriu e não haverá cobranças seguintes."},"cycle":{"type":["string","null"],"description":"Só com `recurrence`: o ciclo gravado."},"next_charge_at":{"type":["string","null"],"format":"date-time","description":"Só com `recurrence`: estimativa da próxima cobrança, em UTC. Para liberar e cortar acesso, use o `transaction.paid` de cada cobrança."}}},"example":{"transaction_id":"ae3bf1da-0c9b-4818-9140-c6432152c23e","status":"paid","authorized":true,"acquirer":"vortex","acquirer_message":"Pagamento autorizado.","decline_code":null,"retryable":false,"card":{"brand":"visa","last4":"0010"},"amount_cents":4990,"currency":"EUR","created_at":"2026-10-27T06:35:09Z"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`scope_required`: a chave não tem a permissão `transactions:write`. `seller_not_approved`: a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Nada foi criado. `customer_required_for_vortex`: faltou nome ou e-mail do comprador. `customer_ip_required_for_vortex`: faltou o `customer.ip`, que é o IP de onde o comprador está. `currency_not_supported`: moeda fora das 48. `fx_unavailable`: cotação indisponível, espere o `Retry-After`. `amount_out_of_range`: a resposta traz `min_amount_cents`, `max_amount_cents` e `currency`, na moeda que você enviou. `invalid_card_token`: tokenize de novo. `invalid_cycle`: o `recurrence.cycle` não é um dos sete ciclos, e a lista vem no `message`. `recurrence_not_supported`: a cobrança recorrente não está disponível nesta adquirente no momento; fale com o suporte. `one_click_not_supported`: o campo `one_click_from` do checkout comum não existe nesta rota. O upsell em um clique tem rota própria, o `POST /vortex/upsell`.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["customer_required_for_vortex","customer_ip_required_for_vortex","currency_not_supported","fx_unavailable","amount_out_of_range","partner_api_not_enabled","acquirer_not_enabled","invalid_card_token","invalid_cycle","recurrence_not_supported","one_click_not_supported","metadata_reserved_key","validation_failed"]},"message":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/vortex/upsell":{"post":{"tags":["Cartão (server-to-server, Vortex)"],"summary":"Upsell em um clique na Vortex (integração direta)","description":"Cobra um segundo produto no **mesmo cartão** de uma venda já paga, sem pedir o cartão outra vez ao comprador e **sem `card_token`** (permissão `transactions:write`). É a oferta do pós-compra: o comprador clica uma vez.\n\n**Não existe `card_token` nesta rota, e é esse o ponto.** Também não existem `customer` nem `installments`: o comprador é o da venda de origem e o upsell é sempre à vista. Qualquer um desses campos no corpo volta `422 field_not_supported` e nada é criado — de propósito, para você não receber um `201` achando que mandou um cartão.\n\n**O upsell pode ser RECORRENTE.** Mande o mesmo campo `recurrence` da cobrança comum e este upsell passa a ser a primeira cobrança de uma assinatura, no mesmo cartão, enquanto a venda de origem continua única. A resposta ganha `recurrence_id`, `cycle` e `next_charge_at`. A assinatura só passa a valer quando este upsell for aprovado, e aqui a aprovação nunca é imediata: até lá a recorrência fica `pending`. Ciclo fora dos sete volta `422 invalid_cycle` e nada é criado nem cobrado.\n\n**`pending` é o desfecho normal, e já significa cobrado.** Nesta adquirente o banco autoriza na hora e a venda ainda passa por análise de risco; no upsell há um motivo a mais: o processador confirma a cobrança sem devolver o número do pedido dela, que chega depois, no aviso. Então espere o `transaction.paid` e **não repita a chamada** — repetir cobra de novo. Se o seu cliente HTTP desistir antes da resposta, consulte a venda ou repita a **mesma** chamada com a **mesma** `Idempotency-Key`.\n\n**A venda de origem** tem de ser da sua conta, `paid`, sem estorno e sem contestação, da Vortex, dentro de **120 minutos** do pagamento, com no máximo **5 upsells**, e cobrada pela integração direta da Vortex **depois de 28/10/2026** (antes disso o cartão não era guardado). Fora dessas regras, `409` com o motivo. Upsell de upsell funciona: aponte o `parent_transaction_id` para o primeiro.\n\n**Habilitação à parte.** Ter a integração direta liberada não basta: o upsell em um clique é liberado conta por conta. Sem isso, `403 one_click_not_enabled`.\n\nSó na integração direta: no checkout hospedado da Vortex o campo `one_click_from` continua respondendo `one_click: false`.\n\nA venda é uma transação comum do Throne: consulte pelo `GET /transactions/{id}` e acompanhe pelo webhook `transaction.paid`, que **não ganha campo novo** — amarre o upsell ao funil pelo `transaction_id` que esta chamada devolve. Estorno pelo suporte.\n\nGuia: [Server-to-server na Vortex](https://app.thronecorporate.com/docs/cartao/vortex-direto#upsell-em-um-clique).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parent_transaction_id","amount_cents","currency"],"properties":{"parent_transaction_id":{"type":"string","maxLength":64,"description":"O `transaction_id` da venda de origem, o mesmo que você recebeu na cobrança dela. Nunca um id do processador.","example":"e1b9c0a4-7f3d-4e21-9a8b-3c5d6e7f8a90"},"amount_cents":{"type":"integer","minimum":1,"description":"Valor do upsell na menor unidade da moeda enviada. Independente do valor da venda de origem."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Uma das 48 moedas do checkout, maiúsculas ou minúsculas. Não precisa ser a mesma da venda de origem."},"description":{"type":"string","maxLength":255},"metadata":{"type":"object","description":"Até 20 chaves com valores simples. Chaves reservadas são recusadas."},"recurrence":{"type":"object","required":["cycle"],"description":"Opcional. O upsell passa a se repetir: a venda de origem continua única e este upsell é a primeira cobrança da assinatura. A assinatura só passa a valer quando este upsell for aprovado, e aqui a aprovação nunca é imediata. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","properties":{"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"],"description":"Ciclo das cobranças. Outro valor: `422 invalid_cycle`, com a lista no `message`, e nada é criado nem cobrado.","example":"monthly"},"max_payments":{"type":"integer","minimum":2,"maximum":120,"description":"Opcional. Teto de cobranças, contando este upsell. Sem ele, a recorrência segue até você cancelar.","example":12}}}}},"example":{"parent_transaction_id":"e1b9c0a4-7f3d-4e21-9a8b-3c5d6e7f8a90","amount_cents":4700,"currency":"usd","description":"Plano anual","metadata":{"order_id":"ORD-2026-00001-up1"}}}}},"responses":{"201":{"description":"Upsell criado (o resultado está em `status`)","content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid","description":"A venda do upsell. É por este id que você a amarra ao funil."},"status":{"type":"string","enum":["paid","pending","failed"],"description":"`pending` é o normal aqui, e já significa cobrado: espere o webhook e não repita."},"authorized":{"type":"boolean"},"acquirer":{"type":"string","enum":["vortex"]},"acquirer_message":{"type":"string"},"decline_code":{"type":["string","null"],"description":"Com `failed`: `one_click_unavailable` (a venda de origem não tem cartão guardado), `declined` (o processador recusou), `unavailable` ou `processing_unavailable` (nada foi cobrado, pode repetir com chave nova) ou `invalid_request`."},"retryable":{"type":"boolean","description":"Só é `true` quando nada foi cobrado."},"card":{"type":"object","properties":{"brand":{"type":["string","null"]},"last4":{"type":["string","null"]}},"description":"A bandeira e os quatro últimos dígitos do cartão guardado."},"amount_cents":{"type":"integer","description":"O valor que você cobrou, na moeda enviada."},"currency":{"type":"string","description":"A moeda que você enviou."},"one_click":{"type":"boolean","description":"Sempre `true` nesta rota."},"created_at":{"type":"string","format":"date-time"},"recurrence_id":{"type":["string","null"],"pattern":"^rec_[0-9a-f]{24}$","description":"Só quando a chamada manda `recurrence`: a recorrência, para consultar e cancelar em `/recurrences/{id}`. Nulo, com `cycle` e `next_charge_at` nulos: o upsell foi criado, mas a assinatura não abriu e não haverá cobranças seguintes."},"cycle":{"type":["string","null"],"description":"Só com `recurrence`: o ciclo gravado."},"next_charge_at":{"type":["string","null"],"format":"date-time","description":"Só com `recurrence`: estimativa da próxima cobrança, em UTC. Para liberar e cortar acesso, use o `transaction.paid` de cada cobrança."}}},"example":{"transaction_id":"9f2c1d7e-4a8b-4c3d-8e9f-1a2b3c4d5e6f","status":"pending","authorized":false,"acquirer":"vortex","acquirer_message":"Pagamento em análise. O resultado chega pelo webhook e pela consulta da venda.","decline_code":null,"retryable":false,"card":{"brand":"visa","last4":"0010"},"amount_cents":4700,"currency":"USD","one_click":true,"created_at":"2026-10-28T18:04:11Z"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Nada foi criado. `one_click_not_enabled`: o upsell em um clique não está liberado nesta conta (é à parte da integração direta); fale com o suporte. `scope_required`: a chave não tem a permissão `transactions:write`. `seller_not_approved`: a conta não está aprovada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["one_click_not_enabled","scope_required","seller_not_approved"]},"message":{"type":"string"}}}}}},"409":{"description":"Nada foi criado; é a venda de origem que não serve. `parent_not_found`: não existe venda sua com esse `parent_transaction_id`. `parent_not_paid`: ela ainda não está paga, espere o `transaction.paid` dela. `parent_refunded` e `parent_charged_back`: ela foi estornada ou contestada. `parent_too_old`: passou dos 120 minutos desde o pagamento. `upsell_limit_reached`: ela já tem 5 upsells. `parent_other_acquirer`: ela é de outra adquirente, e o upsell cai na mesma dela. O `409` de `Idempotency-Key` em processamento também usa este código HTTP.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["parent_not_found","parent_not_paid","parent_refunded","parent_charged_back","parent_too_old","upsell_limit_reached","parent_other_acquirer","one_click_not_supported","one_click_unavailable"]},"message":{"type":"string"}}}}}},"422":{"description":"Nada foi criado. `invalid_cycle`: o `recurrence.cycle` não é um dos sete, e a lista vem no `message`. `recurrence_not_supported`: a cobrança recorrente não está disponível nesta adquirente no momento. `field_not_supported`: você mandou `card_token`, `customer`, `installments` ou `one_click_from`, e nenhum existe nesta rota. `validation_failed`: campo inválido, com `errors` listando cada um. `currency_not_supported`: moeda fora das 48. `fx_unavailable`: cotação indisponível, espere o `Retry-After`. `amount_out_of_range`: a resposta traz `min_amount_cents`, `max_amount_cents` e `currency`, na moeda que você enviou. `metadata_reserved_key`: troque o nome da chave.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["field_not_supported","validation_failed","acquirer_not_enabled","partner_api_not_enabled","currency_not_supported","fx_unavailable","amount_out_of_range","metadata_reserved_key","invalid_cycle","recurrence_not_supported"]},"message":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/elements/acquirers":{"get":{"tags":["Cartão"],"summary":"Listar as adquirentes de cartão da conta","description":"As adquirentes de cartão habilitadas nesta conta, com o valor para mandar no campo `acquirer` do `POST /elements/checkout`. `default: true` marca a que vale quando o campo não é enviado. `available: false` marca uma adquirente em pausa ou indisponível no momento. Com `?currency=`, cada item traz `limits` com o mínimo e o máximo por venda nessa moeda, pela cotação do momento (valores indicativos: a criação confere de novo). Lista vazia: a conta não tem cartão habilitado. Permissão `transactions:write`, a mesma de criar o checkout.","parameters":[{"name":"currency","in":"query","required":false,"description":"Moeda em que você quer ver os limites (uma das 48 do checkout), maiúsculas ou minúsculas. Sem ela, a resposta não traz `limits`.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"chf"}}],"responses":{"200":{"description":"Adquirentes habilitadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardAcquirerList"},"example":{"data":[{"acquirer":"sterling","name":"Sterling","default":true,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":500000}},{"acquirer":"novacorp","name":"NovaCorp","default":false,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":31890}},{"acquirer":"eminence","name":"Eminence","default":false,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":500000}},{"acquirer":"apex","name":"Apex","default":false,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":500000}},{"acquirer":"shadowbank","name":"ShadowBank","default":false,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":500000}},{"acquirer":"vortex","name":"Vortex","default":false,"available":true,"limits":{"currency":"CHF","min_amount_cents":80,"max_amount_cents":500000}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"A moeda de `?currency=` não está entre as 48 aceitas.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["currency_not_supported"]},"message":{"type":"string"}}}}}}}}},"/recurrences":{"get":{"tags":["Recorrências"],"summary":"Listar recorrências","description":"As recorrências da conta, as mais recentes primeiro (permissão `transactions:read`), em `data`, com a paginação em `meta`. `per_page` vai de 1 a 100 (padrão 25); fora da faixa, vale o limite mais perto. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","parameters":[{"name":"per_page","in":"query","required":false,"description":"Itens por página, de 1 a 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"page","in":"query","required":false,"description":"Página, a partir de 1.","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Recorrências da conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurrenceList"},"example":{"data":[{"recurrence_id":"rec_7f3a9c1e5b2d4a6f8c0e1b3d","status":"active","cycle":"monthly","amount_cents":4990,"currency":"BRL","native_amount_cents":4990,"max_payments":12,"charges_count":3,"last_charge_at":"2026-12-18T18:07:22Z","next_charge_at":"2027-01-18T15:00:00Z","product_name":null,"origin_transaction_id":"a1b2c3d4-e5f6-4789-abcd-ef0123456789","canceled_at":null,"created_at":"2026-10-18T18:04:11Z"}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/recurrences/{id}":{"get":{"tags":["Recorrências"],"summary":"Consultar recorrência","description":"Uma recorrência da conta (permissão `transactions:read`). Quem diz se ela ainda cobra é `status`. `charges_count` e `last_charge_at` contam as cobranças desta recorrência que existem na sua conta. `next_charge_at` é uma estimativa: libere e corte acesso pelo `transaction.paid` de cada cobrança. Recorrência de outra conta responde `404`. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","parameters":[{"$ref":"#/components/parameters/RecurrenceId"}],"responses":{"200":{"description":"Recorrência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recurrence"},"example":{"recurrence_id":"rec_7f3a9c1e5b2d4a6f8c0e1b3d","status":"active","cycle":"monthly","amount_cents":4990,"currency":"BRL","native_amount_cents":4990,"max_payments":12,"charges_count":3,"last_charge_at":"2026-12-18T18:07:22Z","next_charge_at":"2027-01-18T15:00:00Z","product_name":null,"origin_transaction_id":"a1b2c3d4-e5f6-4789-abcd-ef0123456789","canceled_at":null,"created_at":"2026-10-18T18:04:11Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/recurrences/{id}/cancel":{"post":{"tags":["Recorrências"],"summary":"Cancelar recorrência","description":"Para as cobranças seguintes (permissão `transactions:write`). Com `200`, a recorrência não cobra mais, e a resposta traz a recorrência. Pedir o cancelamento de uma recorrência que já tinha parado também responde `200`, sem efeito. Não estorna e não mexe em venda nenhuma. Não usa `Idempotency-Key`: repetir é seguro. Sem `200`, o cancelamento não foi confirmado e a resposta é `cancel_failed`: enquanto não vier `200`, trate a recorrência como ativa. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","parameters":[{"$ref":"#/components/parameters/RecurrenceId"}],"responses":{"200":{"description":"A recorrência depois do pedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recurrence"},"example":{"recurrence_id":"rec_7f3a9c1e5b2d4a6f8c0e1b3d","status":"canceled","cycle":"monthly","amount_cents":4990,"currency":"BRL","native_amount_cents":4990,"max_payments":12,"charges_count":3,"last_charge_at":"2026-12-18T18:07:22Z","next_charge_at":null,"product_name":null,"origin_transaction_id":"a1b2c3d4-e5f6-4789-abcd-ef0123456789","canceled_at":"2027-01-02T13:40:05Z","created_at":"2026-10-18T18:04:11Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"`cancel_failed`: esta recorrência não é cancelada pela API. Nada mudou nela; fale com o suporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurrenceError"},"example":{"error":"cancel_failed","message":"Não foi possível cancelar esta recorrência. Fale com o suporte."}}}},"503":{"description":"`cancel_failed`: o cancelamento não foi confirmado agora. Repita a mesma chamada em instantes, até receber `200`; enquanto não vier `200`, trate a recorrência como ativa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurrenceError"},"example":{"error":"cancel_failed","message":"Não foi possível cancelar agora. Tente de novo em instantes."}}}}}}},"/global/checkout":{"post":{"tags":["Internacional (Paycore)"],"summary":"Criar checkout internacional","description":"Cria um checkout internacional (permissão `transactions:write`). Embuta o `checkout_url` da resposta num `iframe` seu, com `?embed=1` e, se quiser, `color`, `theme` e `radius`, e com `allow=\"payment\"`. O script `throne-elements.js` não serve para este trilho.\n\nA página avisa a sua por `postMessage` (`throne-elements:ready`, `paid`, `error` e `resize` com `height`). A cotação que credita o seu saldo é fixada na aprovação, não na criação. Uma recusa mantém a venda `pending` e o comprador tenta de novo. `payment_method` vem sempre `credit_card`.\n\nGuia: [Internacional (Paycore)](https://app.thronecorporate.com/docs/internacional).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalCheckoutRequest"},"example":{"amount_cents":2000,"currency":"usd","customer":{"name":"John Carter","email":"john@example.com"}}}}},"responses":{"201":{"description":"Checkout criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalCheckoutCreated"},"example":{"transaction_id":"5f0a2c1e-8d3b-4c7a-9e21-6b4d8f2a1c90","status":"pending","checkout_url":"https://app.thronecorporate.com/global/5f0a2c1e-8d3b-4c7a-9e21-6b4d8f2a1c90"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Campo inválido ou regra: `global_not_enabled`, `unsupported_currency` (com `supported`), `currency_not_enabled` (com `enabled`), `amount_too_small` (com `minimum`) ou `idempotency_key_mismatch`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["global_not_enabled","unsupported_currency","currency_not_enabled","amount_too_small","idempotency_key_mismatch"]},"message":{"type":"string"},"supported":{"type":"array","items":{"type":"string"}},"enabled":{"type":"array","items":{"type":"string"}},"minimum":{"type":"integer"}}}]}}}}}}},"/payment-links":{"get":{"tags":["Links de pagamento"],"summary":"Listar links de pagamento","description":"Os 100 links mais recentes (permissão `payment_links:read`).","responses":{"200":{"description":"Links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Links de pagamento"],"summary":"Criar link de pagamento","description":"Cria uma página de pagamento pronta (permissão `payment_links:write`). Compartilhe o campo `url` da resposta. Cada pagamento feito pelo link é uma cobrança Pix e gera `transaction.paid`. Com o recebimento por Pix desabilitado na conta, a resposta é `422 pix_not_enabled` e o link não é criado; um link já criado mostra \"Link indisponível\" ao comprador até o recebimento ser habilitado de novo.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentLinkRequest"},"example":{"description":"Consultoria de 1 hora","amount_cents":15000,"max_uses":1}}}},"responses":{"201":{"description":"Link criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Campo inválido (`{message, errors}`) ou regra: `pix_not_enabled` (o recebimento por Pix não está habilitado nesta conta; o link não é criado) ou `idempotency_key_mismatch`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/Error"}]},"examples":{"pix_not_enabled":{"summary":"Recebimento por Pix não habilitado","value":{"error":"pix_not_enabled","message":"O recebimento por Pix não está habilitado nesta conta. Cartão e saques continuam disponíveis."}}}}}}}}},"/payment-links/{id}":{"get":{"tags":["Links de pagamento"],"summary":"Consultar link de pagamento","parameters":[{"$ref":"#/components/parameters/PaymentLinkId"}],"responses":{"200":{"description":"Link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/payment-links/{id}/revoke":{"post":{"tags":["Links de pagamento"],"summary":"Desativar link de pagamento","parameters":[{"$ref":"#/components/parameters/PaymentLinkId"}],"responses":{"200":{"description":"Link desativado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"O link já estava desativado.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["already_revoked"]},"message":{"type":"string"}}}}}}}}},"/withdrawals":{"post":{"tags":["Saques"],"summary":"Pedir saque (Pix ou cripto)","description":"**Sem ambiente de testes: qualquer chave com esta permissão, inclusive `pk_test_`, transfere dinheiro de verdade.**\n\nExige: permissão `withdrawals:write` (desligada por padrão), o IP do servidor nos IPs de saque da chave e o `totp_code` do autenticador do dono da conta. O saque sai do saldo Pix (`GET /balance`).\n\n- Mínimo padrão R$ 50,00 (a conta pode ter outro), máximo R$ 500.000,00, limite diário por conta e 1 pedido por minuto.\n- A taxa sai de dentro do valor: o destino recebe `net_amount_cents`.\n- Status: `requested`, `processing`, `completed` ou `failed` (no `failed`, o valor inteiro volta para o saldo).\n- Os webhooks `withdrawal.completed` e `withdrawal.failed` nem sempre saem: consulte `GET /withdrawals/{id}`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawalRequest"},"examples":{"pix":{"summary":"Saque Pix para CPF","value":{"amount_cents":50000,"totp_code":"123456","destination":{"key":"12345678909","key_type":"cpf"}}},"cripto":{"summary":"Saque em USDT (TRC20)","value":{"amount_cents":100000,"totp_code":"123456","destination":{"address":"TXYZ1234567890abcdefghijklmnopqrs","network":"USDT_TRC20"}}}}}}},"responses":{"201":{"description":"Saque aceito (`status: requested`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"$ref":"#/components/responses/IdempotencyKeyRequired"},"401":{"description":"Credencial inválida ou código do autenticador errado.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["unauthorized","invalid_two_factor"]},"message":{"type":"string"}}}}}},"403":{"description":"Sem a permissão `withdrawals:write`, IP fora dos IPs de saque ou conta não liberada.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["scope_required","withdrawal_ip_not_authorized","seller_not_approved"]},"message":{"type":"string"}}}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"422":{"description":"Campo inválido ou regra: `insufficient_balance`, `invalid_request` (valor abaixo do mínimo, acima do máximo ou menor que a taxa) ou `idempotency_key_mismatch`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/Error"}]}}}},"429":{"description":"Mais de 1 pedido por minuto ou limite diário atingido.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limited","daily_limit_exceeded"]},"message":{"type":"string"}}}}}}}}},"/withdrawals/{id}":{"get":{"tags":["Saques"],"summary":"Consultar saque","description":"Permissão `withdrawals:read`. `failure_reason` vem em linguagem pronta para mostrar ao seu cliente. A API não tem listagem de saques.","parameters":[{"$ref":"#/components/parameters/WithdrawalId"}],"responses":{"200":{"description":"Saque","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"webhooks":{"transaction.paid":{"post":{"summary":"Pagamento confirmado (Pix, cartão e internacional)","description":"Assinado no header `X-Throne-Signature`: HMAC-SHA256, em hexadecimal, do corpo cru com o secret do endereço. Responda 2xx em até 3 segundos; sem 2xx, são até 10 tentativas no total (a primeira e mais 9). Deduplique por `type` + id do recurso (o `event_id` muda por endereço).","parameters":[{"name":"X-Throne-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"hex(HMAC-SHA256(corpo cru, secret do endereço))"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTransactionPaid"}}}},"responses":{"200":{"description":"Recebido. Qualquer 2xx confirma a entrega."}}}},"withdrawal.completed":{"post":{"summary":"Saque pago","description":"Assinado no header `X-Throne-Signature`: HMAC-SHA256, em hexadecimal, do corpo cru com o secret do endereço. Responda 2xx em até 3 segundos; sem 2xx, são até 10 tentativas no total (a primeira e mais 9). Deduplique por `type` + id do recurso (o `event_id` muda por endereço).","parameters":[{"name":"X-Throne-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"hex(HMAC-SHA256(corpo cru, secret do endereço))"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithdrawalCompleted"}}}},"responses":{"200":{"description":"Recebido. Qualquer 2xx confirma a entrega."}}}},"withdrawal.failed":{"post":{"summary":"Saque não pago (o valor voltou para o saldo)","description":"Assinado no header `X-Throne-Signature`: HMAC-SHA256, em hexadecimal, do corpo cru com o secret do endereço. Responda 2xx em até 3 segundos; sem 2xx, são até 10 tentativas no total (a primeira e mais 9). Deduplique por `type` + id do recurso (o `event_id` muda por endereço).","parameters":[{"name":"X-Throne-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"hex(HMAC-SHA256(corpo cru, secret do endereço))"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithdrawalFailed"}}}},"responses":{"200":{"description":"Recebido. Qualquer 2xx confirma a entrega."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pk_live_xxx:sk_live_xxx","description":"Bearer com `<public_key>:<secret_key>`, separadas por dois-pontos e em texto (sem base64)."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"env":{"type":"string"},"time":{"type":"string","format":"date-time"}}},"Balance":{"type":"object","properties":{"balance_cents":{"type":"integer","description":"Saldo Pix livre (igual a `available_cents`)."},"pending_balance_cents":{"type":"integer","description":"Saldo ainda pendente."},"reserved_cents":{"type":"integer","description":"Valor preso em saques em andamento."},"available_cents":{"type":"integer","description":"Saldo livre para saque pela API."},"currency":{"type":"string","enum":["BRL"]}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar."}}},"RetryableError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["checkout_failed","temporarily_unavailable"],"description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar."},"retryable":{"type":"boolean","description":"`true`: vale repetir com uma Idempotency-Key nova (depois do `Retry-After`, quando houver). `false`: não repita igual."}}},"CardCheckoutError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["currency_not_supported","fx_unavailable","invalid_amount","card_not_enabled","invalid_acquirer","acquirer_not_enabled","customer_required_for_shadowbank","customer_required_for_vortex","invalid_cycle","recurrence_not_supported","idempotency_key_mismatch","idempotency_key_other_endpoint"],"description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar. Em `invalid_amount`, já traz o limite na moeda enviada."},"max_amount_cents":{"type":"integer","description":"Em `invalid_amount` acima do máximo da adquirente, quando o máximo é conhecido: o máximo na moeda enviada, na menor unidade, pela cotação do momento."},"min_amount_cents":{"type":"integer","description":"Em `invalid_amount` abaixo do mínimo: o mínimo na moeda enviada, na menor unidade, pela cotação do momento."},"currency":{"type":"string","description":"Moeda de `max_amount_cents` ou `min_amount_cents`, em maiúsculas."},"alternatives":{"type":"array","items":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"]},"description":"Em `invalid_amount`: outras adquirentes habilitadas na conta que aceitam o valor. Vazia quando nenhuma aceita."}}},"ValidationErrorResponse":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"example":{"message":"O campo customer.email é obrigatório.","errors":{"customer.email":["O campo customer.email é obrigatório."]}}},"PixCustomer":{"type":"object","required":["name","document","email"],"properties":{"name":{"type":"string","minLength":3,"maxLength":255,"example":"Maria Souza"},"document":{"type":"string","minLength":11,"maxLength":20,"description":"CPF (11) ou CNPJ (14), só números.","example":"12345678909"},"email":{"type":"string","format":"email","example":"maria@exemplo.com"},"phone":{"type":"string","maxLength":20,"example":"+5511999998888"},"birth_date":{"type":"string","format":"date","example":"1990-05-15"},"address":{"type":"object","properties":{"zip_code":{"type":"string","maxLength":9},"street":{"type":"string","maxLength":200},"number":{"type":"string","maxLength":20},"complement":{"type":"string","maxLength":100},"neighborhood":{"type":"string","maxLength":100},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2,"description":"UF"},"country":{"type":"string","minLength":2,"maxLength":2}}}}},"ShippingAddress":{"type":"object","required":["recipient_name","zip_code","street","number","city","state"],"properties":{"recipient_name":{"type":"string","maxLength":255},"recipient_phone":{"type":"string","maxLength":20},"zip_code":{"type":"string","maxLength":9},"street":{"type":"string","maxLength":200},"number":{"type":"string","maxLength":20},"complement":{"type":"string","maxLength":100},"neighborhood":{"type":"string","maxLength":100},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"country":{"type":"string","minLength":2,"maxLength":2},"shipping_method":{"type":"string","enum":["standard","express","pickup"]}}},"Item":{"type":"object","required":["title","quantity","unit_amount_cents"],"properties":{"title":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":500},"sku":{"type":"string","maxLength":64},"quantity":{"type":"integer","minimum":1},"unit_amount_cents":{"type":"integer","minimum":1},"category":{"type":"string","maxLength":100},"image_url":{"type":"string","format":"uri","maxLength":500}}},"Split":{"type":"object","required":["recipient_seller_id","type"],"properties":{"recipient_seller_id":{"type":"integer","description":"Conta do Throne que recebe a parte. Não pode ser a sua."},"type":{"type":"string","enum":["fixed","percentage"]},"amount_cents":{"type":"integer","minimum":100,"description":"Obrigatório em `fixed`."},"percent_basis_points":{"type":"integer","minimum":1,"maximum":10000,"description":"Obrigatório em `percentage`. 1500 = 15%."}}},"CreatePixRequest":{"type":"object","required":["payment_method","amount_cents","customer"],"properties":{"payment_method":{"type":"string","enum":["pix"]},"amount_cents":{"type":"integer","minimum":100,"maximum":5000000,"description":"Centavos, de R$ 1,00 a R$ 50.000,00.","example":4990},"customer":{"$ref":"#/components/schemas/PixCustomer"},"expires_at":{"type":"string","format":"date-time","description":"Prazo exibido ao comprador. Padrão: 1 hora. Um Pix pago depois ainda pode ser confirmado."},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Item"},"description":"A soma de quantity × unit_amount_cents precisa ser igual a amount_cents."},"shipping_address":{"$ref":"#/components/schemas/ShippingAddress"},"metadata":{"type":"object","additionalProperties":true,"description":"Objeto livre que volta na consulta e no webhook. Use chaves com um prefixo seu."},"splits":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/Split"}}}},"PaymentData":{"type":["object","null"],"description":"Só no Pix.","properties":{"qr_code_payload":{"type":"string","description":"Copia e cola. Vem vazio na cobrança que já estava paga quando foi registrada, o que pode acontecer na repetição de um `502` com `retry_same_key`: não mostre QR Code e libere o pedido pelo `transaction.paid` ou por um `GET` com `status: \"paid\"`."},"qr_code_image_base64":{"type":["string","null"],"description":"PNG em base64 puro (monte `data:image/png;base64,...`). Se vier null com o payload preenchido, gere o QR a partir do payload."},"expires_at":{"type":"string","description":"Prazo em ISO 8601 com fuso."}}},"Transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","paid","failed","expired","refunded","chargeback"]},"payment_method":{"type":"string","enum":["pix","credit_card"]},"amount_cents":{"type":"integer","description":"Valor bruto no seu saldo, em reais (a moeda da sua conta). No cartão e no internacional, preenchido quando a venda é paga (antes, 0)."},"fee_cents":{"type":"integer"},"net_amount_cents":{"type":"integer","description":"O que entra na sua carteira."},"currency":{"type":"string","description":"Moeda em que a venda foi criada, em maiúsculas: a moeda em que o comprador paga. Pix: BRL."},"native_amount_cents":{"type":"integer","description":"A venda na moeda de `currency`, como você criou."},"fx_rate":{"type":["number","null"],"description":"Cotação usada para creditar o seu saldo (reais por 1 unidade de `currency`), fixada na criação no cartão e na aprovação no internacional. Nulo antes do pagamento e em venda de cartão criada em BRL; 1 em venda internacional criada em BRL."},"paid_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"No Pix, o prazo da cobrança. No cartão pode vir nulo: use o `expires_at` da resposta de criação."},"payment_data":{"$ref":"#/components/schemas/PaymentData"},"customer":{"type":["object","null"],"description":"Dados do comprador como enviados na criação."},"shipping_address":{"type":["object","null"]},"items":{"type":["array","null"],"items":{"type":"object"}},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"TransactionDetail":{"allOf":[{"$ref":"#/components/schemas/Transaction"},{"type":"object","properties":{"acquirer":{"type":["string","null"],"enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex",null],"description":"Só na consulta. Adquirente da venda de cartão (nome público). Nulo no Pix e no internacional."}}}]},"CardCheckoutRequest":{"type":"object","required":["amount_cents","currency"],"properties":{"amount_cents":{"type":"integer","minimum":50,"maximum":100000000,"description":"Na menor unidade da moeda (US$ 49,90 = 4990). Em JPY, KRW, VND, CLP, HUF, TWD e PYG, a unidade inteira. O mínimo e o máximo por venda dependem da adquirente e variam com a moeda e com a cotação do dia (veja `GET /elements/acquirers?currency=`); fora deles, `422 invalid_amount` com o limite na moeda enviada. Em moedas de valor baixo, o limite do campo (100.000.000 unidades) pode chegar antes.","example":4990},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Moeda do comprador, maiúsculas ou minúsculas: é nela que ele paga. Mande o valor como está no seu site, sem ajustar nada. Aceitas (48): brl, usd, eur, gbp, chf, aud, cad, nzd, jpy, sgd, hkd, mxn, ars, clp, cop, pen, uyu, pyg, bob, dop, gtq, crc, pab, aed, sar, zar, nok, sek, dkk, pln, czk, huf, ron, try, ils, krw, inr, cny, thb, myr, idr, php, twd, vnd, ngn, egp, kes, mad.","example":"usd"},"customer":{"type":"object","description":"Opcional, salvo na ShadowBank e na Vortex. O checkout pede ao comprador só os dados do cartão; o que você mandar fica registrado na venda e volta no webhook. Fora da ShadowBank, nenhum campo daqui gera 422: o que vier fora do formato é ajustado ou descartado, com aviso em `warnings` na resposta 201. Na ShadowBank e na Vortex (`acquirer: shadowbank` ou `acquirer: vortex`, ou uma delas como padrão da conta), `name` e `email` são obrigatórios: `name` com até 120 caracteres e `email` válido com até 180. Sem eles, ou fora desses tamanhos, `422 customer_required_for_shadowbank` ou `422 customer_required_for_vortex`, e nada é criado. O elemento nunca pergunta nome nem e-mail ao comprador; colete os dois na sua página antes da criação.","properties":{"name":{"type":"string","maxLength":255,"description":"Vai pré-preenchido no nome do cartão."},"email":{"type":"string","format":"email"},"document":{"type":"string","minLength":5,"maxLength":20,"description":"CPF, CNPJ ou passaporte. Pontos, traços e barra são aceitos. Sem `document_type`: 11 dígitos = CPF, 14 = CNPJ, o resto = passaporte. Fora do formato: descartado, com aviso em `warnings`."},"document_type":{"type":"string","enum":["cpf","cnpj","passport"]},"phone":{"type":"object","properties":{"country_code":{"type":"string","example":"55"},"area_code":{"type":"string","example":"11"},"number":{"type":"string","example":"999998888"}}},"address":{"type":"object","properties":{"line_1":{"type":"string","maxLength":120},"line_2":{"type":"string","maxLength":60},"zip_code":{"type":"string","maxLength":16},"city":{"type":"string","maxLength":60},"state":{"type":"string","maxLength":40},"country":{"type":"string","minLength":2,"maxLength":2}}}}},"acquirer":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"],"description":"Opcional. Escolhe a adquirente desta venda entre as habilitadas na conta (veja `GET /elements/acquirers`). Sem o campo, vale a padrão da conta. Com o campo, o Throne nunca troca por outra. Adquirente não habilitada: `422 acquirer_not_enabled`.","example":"novacorp"},"one_click_from":{"type":"string","maxLength":64,"description":"Opcional. Upsell em um clique: o `transaction_id` de uma venda sua, paga, da mesma adquirente. Só abre em um clique com a sua conta habilitada para o upsell em um clique (habilitação por conta, pelo suporte). A resposta diz em `one_click` se o checkout abre em um clique; qualquer recusa vira `one_click: false`, sem erro, e o comprador digita o cartão. Guia: [Upsell em um clique](https://app.thronecorporate.com/docs/cartao/oneclick).","example":"a1b2c3d4-e5f6-4789-abcd-ef0123456789"},"recurrence":{"type":"object","required":["cycle"],"description":"Opcional. Recorrência: a cobrança se repete sozinha no cartão, no ciclo pedido, e a primeira cobrança é a venda deste checkout. Adquirente que não faz cobrança recorrente: `422 recurrence_not_supported`. Em adquirente cuja aprovação não é imediata, a assinatura só passa a valer quando a primeira cobrança aprova: até lá a recorrência fica em `pending`, com `next_charge_at` como estimativa. Guia: [Recorrência](https://app.thronecorporate.com/docs/cartao/recorrencias).","properties":{"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"],"description":"Ciclo das cobranças. Outro valor: `422 invalid_cycle`, com a lista no `message`.","example":"monthly"},"max_payments":{"type":"integer","minimum":2,"maximum":120,"description":"Opcional. Teto de cobranças, contando a primeira. Sem ele, a recorrência segue até você cancelar.","example":12}}}}},"CardCheckoutCreated":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid","description":"Use no `data-id` do Throne Elements e no `GET /transactions/{id}`."},"status":{"type":"string","enum":["pending"]},"checkout_url":{"type":"string","format":"uri","description":"Checkout hospedado. Host e formato não são contratuais; use como veio. O recomendado é embutir com o Throne Elements."},"acquirer":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"],"description":"Adquirente que ficou com a venda: a pedida em `acquirer` ou, sem o campo, a padrão da conta (ou a escolhida pelo roteamento por valor, quando ligado na conta)."},"display":{"type":"object","properties":{"currency":{"type":"string"},"amount_cents":{"type":"integer"}},"description":"Moeda e valor que você mandou. Opcional: contas com integração antiga podem não receber."},"expires_at":{"type":"string","format":"date-time","description":"Fim da validade do checkout, em UTC (ISO 8601). Depois disso, a venda não paga vira `expired`. Opcional: contas com integração antiga podem não receber."},"warnings":{"type":"array","items":{"type":"object","description":"Aviso sobre um campo opcional de `customer` que foi ajustado ou descartado.","properties":{"field":{"type":"string","description":"Campo ajustado, por exemplo `customer.phone.number`."},"code":{"type":"string","description":"Código fixo do aviso."},"message":{"type":"string","description":"Texto de apoio; pode mudar."}}},"description":"Só quando houver aviso. Serve para log: a venda foi criada."},"one_click":{"type":"boolean","description":"Só quando a chamada manda `one_click_from`. `true`: o checkout abre em um clique, com o cartão da venda de origem. `false`: o comprador digita o cartão, e a venda acontece do mesmo jeito."},"one_click_card":{"type":"object","description":"Só com `one_click: true`: bandeira e final do cartão, para a sua página.","properties":{"brand":{"type":"string","example":"mastercard"},"last4":{"type":"string","example":"2006"}}},"recurrence_id":{"type":["string","null"],"pattern":"^rec_[0-9a-f]{24}$","description":"Só quando a chamada manda `recurrence`: a recorrência, para consultar e cancelar em `/recurrences/{id}`. Nulo, com `next_charge_at` nulo: a venda foi criada, mas a assinatura não abriu e não haverá cobranças seguintes. Não repita a chamada com a mesma `Idempotency-Key`."},"cycle":{"type":["string","null"],"description":"Só com `recurrence`: o ciclo gravado."},"next_charge_at":{"type":["string","null"],"format":"date-time","description":"Só com `recurrence`: estimativa da próxima cobrança, em UTC. Para liberar e cortar acesso, use o `transaction.paid` de cada cobrança."}}},"Recurrence":{"type":"object","properties":{"recurrence_id":{"type":"string","pattern":"^rec_[0-9a-f]{24}$","description":"Identificador da recorrência, o mesmo `recurrence_id` da criação."},"status":{"type":"string","enum":["pending","active","past_due","canceled","ended"],"description":"`pending`: esperando a primeira cobrança. `active`: cobrando no ciclo. `past_due`: a última cobrança foi recusada; volta para `active` quando uma aprovar. `canceled`: não cobra mais. `ended`: chegou a `max_payments`."},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"amount_cents":{"type":"integer","description":"Valor de cada cobrança em reais, pela cotação fixada na criação."},"currency":{"type":"string","description":"Moeda em que você criou, em maiúsculas."},"native_amount_cents":{"type":"integer","description":"Valor de cada cobrança na moeda de `currency`."},"max_payments":{"type":["integer","null"],"description":"Teto de cobranças, contando a primeira. Nulo: sem teto."},"charges_count":{"type":"integer","description":"Cobranças desta recorrência que existem na sua conta."},"last_charge_at":{"type":["string","null"],"format":"date-time","description":"Data da última dessas cobranças."},"next_charge_at":{"type":["string","null"],"format":"date-time","description":"Estimativa da próxima cobrança, em UTC. Nula em `pending` (até a primeira cobrança ser confirmada) e quando a recorrência não cobra mais (`canceled` e `ended`). Para liberar e cortar acesso, use o `transaction.paid` de cada cobrança."},"product_name":{"type":["string","null"],"description":"Fica nulo: a criação do checkout não recebe nome de produto."},"origin_transaction_id":{"type":["string","null"],"format":"uuid","description":"A venda da primeira cobrança: o `transaction_id` da criação."},"canceled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","description":"Vem em toda resposta e, hoje, sempre vazio (`{}`): a criação do checkout não recebe `metadata`."}}},"RecurrenceList":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recurrence"}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"}}}}},"RecurrenceError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["cancel_failed"],"description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar."}}},"CardVaultCreateRequest":{"type":"object","required":["number","exp_month","exp_year","cvv","holder_name"],"properties":{"number":{"type":"string","minLength":13,"maxLength":19,"description":"Número do cartão, só dígitos (espaços e hífens são ignorados). Não é gravado em disco nem em log.","example":"5555666677778884"},"exp_month":{"type":"integer","minimum":1,"maximum":12,"example":12},"exp_year":{"type":"integer","description":"Ano com quatro dígitos (2030) ou dois (30).","example":2030},"cvv":{"type":"string","minLength":3,"maxLength":4,"description":"Três dígitos (quatro no American Express).","example":"123"},"holder_name":{"type":"string","maxLength":64,"description":"Nome impresso no cartão.","example":"LUCA MEIER"}}},"CardVaultCreated":{"type":"object","required":["card_token","last4","exp_month","exp_year","expires_at"],"properties":{"card_token":{"type":"string","description":"Token de uso único. Cada cobrança pede um token novo.","example":"9f0d4a1c7e2b48b1a3d0f6c89e2a4b7c"},"brand":{"type":"string","nullable":true,"description":"Bandeira do cartão.","example":"mastercard"},"last4":{"type":"string","description":"Últimos quatro dígitos.","example":"8884"},"exp_month":{"type":"integer","example":12},"exp_year":{"type":"integer","example":2030},"expires_at":{"type":"string","format":"date-time","description":"Até quando o token pode ser usado (no máximo 7 dias)."}}},"EminencePartnerPaymentRequest":{"type":"object","required":["amount_cents","card_token","customer"],"properties":{"amount_cents":{"type":"integer","minimum":500,"description":"Em centavos de real (R$ 49,90 = 4990). Mínimo R$ 5,00.","example":4990},"currency":{"type":"string","enum":["BRL","brl"],"description":"Só BRL. Opcional.","example":"BRL"},"card_token":{"type":"string","description":"Token devolvido pelo `POST /vault/eminence/cards`. Uso único.","example":"9f0d4a1c7e2b48b1a3d0f6c89e2a4b7c"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Opcional, de 1 a 12. Sem o campo, à vista. Os juros do parcelamento são do comprador e ficam com a adquirente: o Throne liquida pelo `amount_cents` que você mandou, então o seu líquido é o mesmo de uma venda à vista. O número é conferido na adquirente ANTES de cobrar; cartão que não oferece aquele número volta `422 installments_unavailable` e nada é cobrado. Cobrança recorrente é sempre à vista.","example":6},"customer":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120,"description":"Nome do comprador."},"email":{"type":"string","format":"email"},"document":{"type":"string","maxLength":20,"description":"CPF ou CNPJ, só dígitos."},"phone":{"type":"string","maxLength":30,"description":"Telefone com DDD, só dígitos."}}},"description":{"type":"string","maxLength":255,"description":"Volta em `metadata.description` na consulta e no webhook."},"metadata":{"type":"object","maxProperties":20,"additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Até 20 chaves com valores simples. Chaves de uso interno (como as com prefixo `throne_`) são recusadas com `metadata_reserved_key`."}}},"EminencePartnerPaymentCreated":{"type":"object","required":["transaction_id","status","authorized","acquirer","acquirer_message","retryable","amount_cents","currency","created_at"],"properties":{"transaction_id":{"type":"string","format":"uuid","description":"Id público da venda. Use no `GET /transactions/{id}` e para casar com o webhook."},"status":{"type":"string","enum":["paid","pending","failed"],"description":"`paid`: aprovado. `pending`: em análise ou em confirmação (aguarde o webhook ou consulte; não cobre de novo). `failed`: recusado ou não processado, nada cobrado."},"authorized":{"type":"boolean","description":"`true` só quando aprovado."},"acquirer":{"type":"string","enum":["eminence"]},"acquirer_message":{"type":"string","description":"Texto pronto para mostrar ao comprador. Pode mudar; decida pelo `status`."},"decline_code":{"type":"string","nullable":true,"description":"Código da recusa (padrão das bandeiras, como `51`) ou `invalid_card_token`, `card_not_supported`, `amount_limit`, `processing_unavailable`."},"retryable":{"type":"boolean","description":"`true` quando vale criar uma nova cobrança (token novo e `Idempotency-Key` nova)."},"card":{"type":"object","nullable":true,"properties":{"brand":{"type":"string"},"last4":{"type":"string"}}},"amount_cents":{"type":"integer","description":"Valor da cobrança em centavos de real."},"currency":{"type":"string","enum":["BRL"]},"created_at":{"type":"string","format":"date-time","description":"Criação da venda, ISO 8601 UTC."}}},"EminencePartnerPaymentError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["validation_failed","partner_api_not_enabled","acquirer_not_enabled","invalid_card_token","amount_out_of_range","metadata_reserved_key","idempotency_key_mismatch"],"description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar."},"errors":{"type":"object","description":"Em `validation_failed`: os campos com problema."},"min_amount_cents":{"type":"integer","description":"Em `amount_out_of_range`."},"max_amount_cents":{"type":"integer","description":"Em `amount_out_of_range`."}}},"CardAcquirerList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["acquirer","name","default"],"properties":{"acquirer":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"],"description":"Valor para o campo `acquirer` do checkout."},"name":{"type":"string","example":"NovaCorp"},"default":{"type":"boolean","description":"A que vale quando o checkout não manda `acquirer`."},"available":{"type":"boolean","description":"`false` quando a adquirente está em pausa ou indisponível no momento: criar nela responde `503 temporarily_unavailable`."},"limits":{"type":["object","null"],"description":"Só com `?currency=`. Mínimo e máximo por venda na moeda pedida, pela cotação do momento. Indicativos: a criação confere de novo. Nulo quando a cotação da moeda está indisponível agora.","properties":{"currency":{"type":"string","example":"CHF"},"min_amount_cents":{"type":"integer","description":"Mínimo por venda, na menor unidade da moeda."},"max_amount_cents":{"type":"integer","description":"Máximo por venda, na menor unidade da moeda."}}}}}}}},"GlobalCheckoutRequest":{"type":"object","required":["amount_cents","currency"],"properties":{"amount_cents":{"type":"integer","minimum":1,"description":"Na menor unidade da moeda; mínimo 50 (em JPY, HUF e TWD, a unidade inteira, mínimo 1).","example":2000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Maiúsculas ou minúsculas. Aceitas (22): AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD, USD.","example":"usd"},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}}}},"GlobalCheckoutCreated":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]},"checkout_url":{"type":"string","format":"uri","description":"Endereço para o seu iframe (acrescente `?embed=1`)."}}},"CreatePaymentLinkRequest":{"type":"object","required":["description","amount_cents"],"properties":{"description":{"type":"string","maxLength":500},"amount_cents":{"type":"integer","minimum":100,"maximum":5000000},"customer_required":{"type":"boolean","default":true},"max_uses":{"type":"integer","minimum":1,"maximum":100000},"expires_at":{"type":"string","format":"date-time","description":"Data futura."},"redirect_url_success":{"type":"string","format":"uri","maxLength":500},"redirect_url_expired":{"type":"string","format":"uri","maxLength":500},"metadata":{"type":"object","additionalProperties":true}}},"PaymentLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"short_code":{"type":"string"},"url":{"type":"string","format":"uri","description":"Endereço para compartilhar."},"description":{"type":"string"},"amount_cents":{"type":"integer"},"amount_brl":{"type":"string","example":"R$ 150,00"},"customer_required":{"type":"boolean"},"max_uses":{"type":["integer","null"]},"used_count":{"type":"integer"},"expires_at":{"type":["string","null"],"format":"date-time"},"redirect_url_success":{"type":["string","null"]},"redirect_url_expired":{"type":["string","null"]},"revoked":{"type":"boolean"},"revoked_at":{"type":["string","null"],"format":"date-time"},"usable":{"type":"boolean","description":"Se o link ainda aceita pagamento."},"metadata":{"type":["object","null"]},"created_at":{"type":"string","format":"date-time"}}},"CreateWithdrawalRequest":{"type":"object","required":["amount_cents","totp_code","destination"],"properties":{"amount_cents":{"type":"integer","minimum":1000,"maximum":50000000,"description":"Centavos. Mínimo padrão R$ 50,00 (5000); a conta pode ter outro mínimo. Máximo R$ 500.000,00.","example":50000},"totp_code":{"type":"string","minLength":6,"maxLength":6,"description":"Texto (entre aspas) com os 6 dígitos do autenticador do dono da conta: TOTP padrão de 30 segundos. Numa repetição por falha de conexão, reenvie o MESMO código.","example":"012345"},"destination":{"type":"object","description":"Pix (`key` + `key_type`) ou cripto (`address` + `network`).","properties":{"key":{"type":"string","description":"Chave Pix. CPF e CNPJ só com números."},"key_type":{"type":"string","enum":["cpf","cnpj","email","phone","evp"],"description":"phone no formato +5511999998888; evp é a chave aleatória com hífens."},"address":{"type":"string","description":"Carteira cripto."},"network":{"type":"string","enum":["BTC","ETH","USDT_TRC20","USDT_ERC20"]}}}}},"Withdrawal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["pix","crypto"]},"status":{"type":"string","enum":["requested","processing","completed","failed"]},"amount_cents":{"type":"integer","description":"Debitado do saldo."},"fee_cents":{"type":"integer"},"net_amount_cents":{"type":"integer","description":"O que o destino recebe."},"requested_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"failure_reason":{"type":["string","null"],"description":"Motivo em linguagem pronta para o seu cliente."}}},"WebhookTransactionPaid":{"type":"object","required":["event_id","type","version","created_at","data"],"properties":{"event_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["transaction.paid"]},"version":{"type":"string","example":"2026-05-01"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["paid"]},"payment_method":{"type":"string","enum":["pix","credit_card"]},"amount_cents":{"type":"integer","description":"Valor bruto no seu saldo, em reais (a moeda da sua conta)."},"fee_cents":{"type":"integer"},"net_amount_cents":{"type":"integer","description":"O que entra de fato, já descontada a taxa."},"paid_at":{"type":"string","format":"date-time"},"card_brand":{"type":["string","null"],"description":"Cartão e internacional. Minúsculo (visa, mastercard...)."},"card_last4":{"type":["string","null"]},"currency":{"type":["string","null"],"description":"Cartão e internacional: a moeda em que a venda foi criada e em que o comprador paga."},"native_amount_cents":{"type":["integer","null"],"description":"Cartão e internacional: a venda na moeda de `currency`."},"fx_rate":{"type":["string","null"],"description":"Cotação usada para creditar o seu saldo, fixada na criação (no internacional, na aprovação), como texto decimal com 8 casas (ex.: \"6.26000000\"). Nulo em venda de cartão criada em BRL."},"customer":{"type":["object","null"]},"shipping_address":{"type":["object","null"]},"items":{"type":["array","null"],"items":{"type":"object"}},"metadata":{"type":"object"}}}}},"WebhookWithdrawalCompleted":{"type":"object","required":["event_id","type","version","created_at","data"],"properties":{"event_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["withdrawal.completed"]},"version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"withdrawal_id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer"},"completed_at":{"type":"string","format":"date-time"}}}}},"WebhookWithdrawalFailed":{"type":"object","required":["event_id","type","version","created_at","data"],"properties":{"event_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["withdrawal.failed"]},"version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"withdrawal_id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer"},"reason":{"type":"string","description":"Pode vir técnico. Para o seu cliente, use `failure_reason` do `GET /withdrawals/{id}`."}}}}},"CardCheckoutBrRequest":{"type":"object","required":["amount_cents","currency"],"properties":{"amount_cents":{"type":"integer","minimum":50,"maximum":100000000,"description":"Na menor unidade da moeda (US$ 49,90 = 4990). Em JPY, KRW, VND, CLP, HUF, TWD e PYG, a unidade inteira. O mínimo e o máximo por venda dependem da adquirente e variam com a moeda e com a cotação do dia (veja `GET /elements/acquirers?currency=`); fora deles, `422 invalid_amount` com o limite na moeda enviada. Em moedas de valor baixo, o limite do campo (100.000.000 unidades) pode chegar antes.","example":4990},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Moeda do comprador, maiúsculas ou minúsculas: é nela que ele paga. Mande o valor como está no seu site, sem ajustar nada. Aceitas (48): brl, usd, eur, gbp, chf, aud, cad, nzd, jpy, sgd, hkd, mxn, ars, clp, cop, pen, uyu, pyg, bob, dop, gtq, crc, pab, aed, sar, zar, nok, sek, dkk, pln, czk, huf, ron, try, ils, krw, inr, cny, thb, myr, idr, php, twd, vnd, ngn, egp, kes, mad.","example":"usd"},"customer":{"type":"object","description":"Opcional. O checkout pede ao comprador só os dados do cartão; o que você mandar fica registrado na venda e volta no webhook. Nenhum campo daqui gera 422: o que vier fora do formato é ajustado ou descartado, com aviso em `warnings` na resposta 201.","properties":{"name":{"type":"string","maxLength":255,"description":"Vai pré-preenchido no nome do cartão."},"email":{"type":"string","format":"email"},"document":{"type":"string","minLength":5,"maxLength":20,"description":"CPF, CNPJ ou passaporte. Pontos, traços e barra são aceitos. Sem `document_type`: 11 dígitos = CPF, 14 = CNPJ, o resto = passaporte. Fora do formato: descartado, com aviso em `warnings`."},"document_type":{"type":"string","enum":["cpf","cnpj","passport"]},"phone":{"type":"object","properties":{"country_code":{"type":"string","example":"55"},"area_code":{"type":"string","example":"11"},"number":{"type":"string","example":"999998888"}}},"address":{"type":"object","properties":{"line_1":{"type":"string","maxLength":120},"line_2":{"type":"string","maxLength":60},"zip_code":{"type":"string","maxLength":16},"city":{"type":"string","maxLength":60},"state":{"type":"string","maxLength":40},"country":{"type":"string","minLength":2,"maxLength":2}}}}},"acquirer":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"],"description":"Opcional. Só uma adquirente habilitada para o Checkout Brasil na sua conta; outra volta `422 acquirer_not_enabled`. Sem o campo, a venda vai para a habilitada para o Checkout Brasil. O roteamento fixado na conta e o roteamento por valor não valem aqui."},"appearance":{"type":["object","null"],"additionalProperties":false,"description":"Opcional. Aparência da página: texto do botão, valor no botão, cores, formato, tamanho e moldura. Toda chave é opcional; ausente ou `null` segue o padrão e os `data-color` e `data-radius` do elemento. Chave que não existe, valor fora da regra ou combinação impossível: `422 invalid_appearance`, com o caminho em `field`. As chaves mandadas ficam gravadas na criação. Guia: [Aparência](https://app.thronecorporate.com/docs/cartao/brasil#aparencia).","properties":{"button":{"type":["object","null"],"additionalProperties":false,"description":"Botão de pagar.","properties":{"text":{"type":["string","null"],"minLength":2,"maxLength":32,"pattern":"^(?=.*[A-Za-zÀ-ÄÇ-ÏÑ-ÖÙ-Üà-äç-ïñ-öù-ü])[A-Za-zÀ-ÄÇ-ÏÑ-ÖÙ-Üà-äç-ïñ-öù-ü !?,'-]+$","example":"Finalizar compra","description":"Texto do botão: letras (com ou sem acento), espaço e `! ? , - '`, com pelo menos uma letra. Número, símbolo de moeda e as palavras real, reais, centavo, centavos, grátis, gratis, gratuito, gratuita, free, zero, cancelar, voltar, fechar e sair não entram: o valor aparece sozinho. Padrão: `Pagar`."},"show_amount":{"type":["boolean","null"],"default":true,"description":"Mostra o valor depois do texto. Com `false`, o botão mostra só o texto e o valor aparece fora dele: logo acima do botão, ou no topo do formulário quando a venda é criada em outra moeda."},"background_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#15803d","description":"Cor do botão. Padrão: o `data-color` do elemento."},"text_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#ffffff","description":"Cor do texto do botão. Só junto de `background_color`, com contraste de 3:1 ou mais (abaixo de 4,5:1, aviso `low_contrast`). Sem ela, a cor sai sozinha."},"radius":{"type":["integer","null"],"minimum":0,"maximum":32,"description":"Arredondamento do botão, em px. Padrão: o dos campos."},"height":{"type":["integer","null"],"minimum":44,"maximum":64,"description":"Altura mínima do botão, em px. Texto longo quebra a linha e o botão cresce.","default":48},"full_width":{"type":["boolean","null"],"default":true,"description":"Com `false`, o botão fica do tamanho do texto, centralizado, com no mínimo 200 px."}}},"fields":{"type":["object","null"],"additionalProperties":false,"description":"Campos do cartão e do CPF.","properties":{"focus_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","description":"Cor de destaque: a borda do campo em foco, o contorno de foco do botão e o indicador da tela de espera. Padrão: `button.background_color`, senão o `data-color`."},"radius":{"type":["integer","null"],"minimum":0,"maximum":32,"description":"Arredondamento dos campos, em px. Padrão: o `data-radius`, senão 10."}}},"frame":{"type":["object","null"],"additionalProperties":false,"description":"Moldura em volta dos campos. Precisa deixar pelo menos 256 px para eles.","properties":{"max_width":{"type":["integer","null"],"minimum":320,"maximum":720,"description":"Largura máxima do checkout, em px.","default":460},"padding":{"type":["integer","null"],"minimum":0,"maximum":40,"description":"Espaço entre a moldura e os campos, em px. Em tela de até 400 px, no máximo 6.","default":0},"border_width":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Espessura da borda, em px. Com só `border_color`, vale 1. Em tela de até 400 px, no máximo 1.","default":0},"border_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","description":"Cor da borda. Padrão: a cor das linhas dos campos."},"radius":{"type":["integer","null"],"minimum":0,"maximum":32,"description":"Arredondamento da moldura, em px.","default":12},"shadow":{"type":["string","null"],"enum":["none","sm","md","lg",null],"default":"none","description":"Sombra da moldura."}}}}}},"description":"O mesmo corpo do `POST /elements/checkout`, sem `one_click_from` e sem `recurrence` (se vierem, `422 field_not_supported`), mais `appearance`. `metadata` e itens não são aceitos."},"CardCheckoutBrError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["currency_not_supported","fx_unavailable","invalid_amount","card_not_enabled","invalid_acquirer","acquirer_not_enabled","idempotency_key_mismatch","idempotency_key_other_endpoint","field_not_supported","invalid_appearance","invalid_installments","installments_currency_unsupported","installments_with_recurrence"],"description":"Código fixo. Decida por ele."},"message":{"type":"string","description":"Texto de apoio; pode mudar. Em `invalid_amount`, já traz o limite na moeda enviada."},"max_amount_cents":{"type":"integer","description":"Em `invalid_amount` acima do máximo da adquirente, quando o máximo é conhecido: o máximo na moeda enviada, na menor unidade, pela cotação do momento."},"min_amount_cents":{"type":"integer","description":"Em `invalid_amount` abaixo do mínimo: o mínimo na moeda enviada, na menor unidade, pela cotação do momento."},"currency":{"type":"string","description":"Moeda de `max_amount_cents` ou `min_amount_cents`, em maiúsculas."},"alternatives":{"type":"array","items":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"]},"description":"No Checkout Brasil vem sempre vazio: acima do máximo, divida o pedido."},"field":{"type":"string","description":"Só em `invalid_appearance`: o caminho da chave recusada, por exemplo `appearance.button.text`."}}},"CardCheckoutBrCreated":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid","description":"Use no `data-id` do Throne Elements e no `GET /transactions/{id}`."},"status":{"type":"string","enum":["pending"]},"checkout_url":{"type":"string","format":"uri","description":"Checkout hospedado. Host e formato não são contratuais; use como veio. O recomendado é embutir com o Throne Elements."},"acquirer":{"type":"string","enum":["sterling","imperium","novacorp","eminence","apex","shadowbank","vortex"],"description":"Adquirente que ficou com a venda: uma habilitada para o Checkout Brasil na sua conta."},"display":{"type":"object","properties":{"currency":{"type":"string"},"amount_cents":{"type":"integer"}},"description":"Moeda e valor que você mandou. Opcional: contas com integração antiga podem não receber."},"expires_at":{"type":"string","format":"date-time","description":"Fim da validade do checkout, em UTC (ISO 8601). Depois disso, a venda não paga vira `expired`. Opcional: contas com integração antiga podem não receber."},"warnings":{"type":"array","items":{"type":"object","description":"Aviso sobre um campo opcional que foi ajustado, descartado ou não aplicado.","properties":{"field":{"type":"string","description":"Campo ajustado, por exemplo `customer.phone.number`."},"code":{"type":"string","description":"Código fixo do aviso: `converted`, `inferred` ou `discarded` (em `customer`) ou `low_contrast` (em `appearance`)."},"message":{"type":"string","description":"Texto de apoio; pode mudar."}}},"description":"Só quando houver aviso. Serve para log: a venda foi criada."}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"De 8 a 128 caracteres (fora disso, 400 idempotency_key_required). Um UUID v4 novo por operação, gerado antes da chamada e guardado com o pedido. Vale 24 horas na conta inteira. Repetir com a mesma chave e o mesmo corpo: depois de um 2xx, devolve a resposta original (`Idempotent-Replay: true`); depois de um 4xx, 409 idempotency_key_race; depois de um 5xx, 409 idempotency_key_processing por até 24 horas (em POST /elements/checkout, um 502 ou 503 libera a chave e a chamada roda de novo; um 500 também, a não ser que a venda tenha chegado a ser criada ou que a chamada tenha sido interrompida no servidor; em POST /transactions, o 502 acquirer_error libera a chave do mesmo jeito, e com retry_same_key: true só para a repetição do mesmo corpo); com a primeira ainda em andamento, 409 idempotency_key_processing. Mesma chave com outro corpo: 422 idempotency_key_mismatch. Sem resposta (falha de conexão, timeout ou resposta sem o JSON da API): repita a MESMA chamada, igual, sem trocar a chave (trocar pode duplicar a cobrança ou o saque). Depois de um 4xx, ou de um 502 ou 503 com o JSON da API: nada foi criado, use uma chave nova. A exceção é o 502 acquirer_error de POST /transactions com retry_same_key: true, em que a cobrança pode ter sido criada: repita com a MESMA chave e o mesmo corpo, nunca com uma nova. Depois de um 500: confira no painel se algo foi criado antes de usar uma chave nova. Tabela completa: https://app.thronecorporate.com/docs/comecar#como-repetir-uma-chamada-com-seguranca","schema":{"type":"string","minLength":8,"maxLength":128,"example":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b"}},"TransactionId":{"name":"id","in":"path","required":true,"description":"Id da transação (UUID em minúsculas), como veio na criação.","schema":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}},"WithdrawalId":{"name":"id","in":"path","required":true,"description":"Id do saque (UUID em minúsculas).","schema":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}},"PaymentLinkId":{"name":"id","in":"path","required":true,"description":"Id do link de pagamento (UUID em minúsculas).","schema":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}},"RecurrenceId":{"name":"id","in":"path","required":true,"description":"Id da recorrência: `rec_` e 24 caracteres, como veio em `recurrence_id`.","schema":{"type":"string","pattern":"^rec_[0-9a-f]{24}$","example":"rec_7f3a9c1e5b2d4a6f8c0e1b3d"}}},"responses":{"Unauthorized":{"description":"Credencial ausente ou inválida. `detail`: `credentials_required`, `malformed_credentials`, `invalid_credentials` ou `ip_not_allowed`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]},"detail":{"type":"string"}}},"example":{"error":"unauthorized","detail":"invalid_credentials"}}}},"Forbidden":{"description":"A chave não tem a permissão do endpoint (`required_scope` diz qual).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["scope_required"]},"message":{"type":"string"},"required_scope":{"type":"string"},"hint":{"type":"string"}}},"example":{"error":"scope_required","message":"Esta credencial não tem o scope necessário: transactions:write.","required_scope":"transactions:write"}}}},"NotFound":{"description":"O recurso não existe ou não é da sua conta."},"IdempotencyKeyRequired":{"description":"Faltou o header `Idempotency-Key`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["idempotency_key_required"]},"message":{"type":"string"}}}}}},"IdempotencyConflict":{"description":"`idempotency_key_processing`: a primeira chamada com esta chave ainda está em andamento; espere alguns segundos e repita a mesma chamada, igual. Se continuar por mais de 2 minutos, a primeira terminou com erro de servidor e a chave fica presa por até 24 horas: confira no painel se algo foi criado antes de usar uma chave nova. Em POST /elements/checkout, um 502 ou 503 libera a chave; um 500 também, a não ser que a venda tenha chegado a ser criada ou que a chamada tenha sido interrompida no servidor. Em POST /transactions, o 502 acquirer_error também libera a chave, e com `retry_same_key: true` só para a repetição do mesmo corpo. `idempotency_key_race`: chamadas simultâneas com a mesma chave, ou chave cuja primeira chamada recebeu 4xx. Depois de um 4xx, nada foi criado: use uma chave nova. Depois de chamadas simultâneas, espere alguns segundos e repita a mesma chamada, igual. `idempotency_key_in_use`: a chave não pode ser usada pela sua conta; use outra. Tabela completa: https://app.thronecorporate.com/docs/comecar#como-repetir-uma-chamada-com-seguranca","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["idempotency_key_processing","idempotency_key_race","idempotency_key_in_use"]},"message":{"type":"string"}}}}}},"ValidationError":{"description":"Campo inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"RateLimited":{"description":"Limite de requisições. Respeite o header `Retry-After` (segundos).","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string"},"retry_after_ms":{"type":"integer"}}}}}},"TooManyRequests":{"description":"Limite de requisições: mais de 10 chamadas por segundo sem credencial válida, do mesmo IP. Nada foi criado. Espere o `Retry-After` (segundos) e repita.","headers":{"Retry-After":{"description":"Segundos para esperar antes de repetir.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"TemporarilyUnavailable":{"description":"A adquirente está em pausa, instável ou sem capacidade de criação no momento. Nada foi criado. Espere o `Retry-After` (segundos) e repita com uma Idempotency-Key nova, ou crie com o `acquirer` de outra adquirente habilitada.","headers":{"Retry-After":{"description":"Segundos para esperar antes de repetir.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryableError"},"example":{"error":"temporarily_unavailable","message":"A adquirente novacorp está temporariamente indisponível. Tente em instantes ou use outra habilitada: sterling.","retryable":true}}}}}},"externalDocs":{"description":"Guias de integração (também em /llms.txt e /docs/llms-full.txt)","url":"https://app.thronecorporate.com/docs"}}