{"info":{"_postman_id":"a88b9e11-f3f3-a314-c97f-77fb6b80eedb","name":"Throne API","description":"Pix, cart\u00e3o em 48 moedas, internacional, saldo, saques e webhooks assinados.","version":"1.13.0","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json"},"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{public_key}}:{{secret_key}}","type":"string"}]},"variable":[{"key":"base_url","value":"https:\/\/app.thronecorporate.com\/api\/v1","type":"string"},{"key":"public_key","value":"pk_live_xxx","type":"string"},{"key":"secret_key","value":"sk_live_xxx","type":"string"}],"item":[{"name":"Sa\u00fade","item":[{"name":"Verificar a API","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/health","host":["{{base_url}}"],"path":["health"]},"body":null,"description":null},"response":[]}]},{"name":"Saldo","item":[{"name":"Consultar saldo","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/balance","host":["{{base_url}}"],"path":["balance"]},"body":null,"description":"Saldo Pix da conta (permiss\u00e3o `balance:read`). O dinheiro de vendas no cart\u00e3o e no internacional fica numa carteira separada, acompanhada pelo painel, e n\u00e3o aparece aqui."},"response":[]}]},{"name":"Pix","item":[{"name":"Criar cobran\u00e7a Pix","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/transactions","host":["{{base_url}}"],"path":["transactions"]},"body":{"mode":"raw","raw":"{\n    \"payment_method\": \"pix\",\n    \"amount_cents\": 4990,\n    \"customer\": {\n        \"name\": \"Maria Souza\",\n        \"document\": \"12345678909\",\n        \"email\": \"maria@exemplo.com\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Cria uma cobran\u00e7a Pix (permiss\u00e3o `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\u00e7a nasce `pending` e vira `paid` quando o pagamento \u00e9 confirmado. Libere o pedido s\u00f3 com o webhook `transaction.paid` ou com `GET \/transactions\/{id}` mostrando `paid`. Um Pix pago depois de `expires_at` ainda pode ser confirmado; n\u00e3o existe webhook de expira\u00e7\u00e3o.\n\nLimite: 10 cobran\u00e7as por segundo por conta. Para cart\u00e3o, use `POST \/elements\/checkout`."},"response":[]}]},{"name":"Transa\u00e7\u00f5es","item":[{"name":"Consultar transa\u00e7\u00e3o","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/transactions\/:id","host":["{{base_url}}"],"path":["transactions","{id}"]},"body":null,"description":"Consulta uma cobran\u00e7a Pix, um checkout de cart\u00e3o ou um checkout internacional (permiss\u00e3o `transactions:read`). Use o id exatamente como veio na cria\u00e7\u00e3o (`id` no Pix, `transaction_id` no cart\u00e3o e no internacional).\n\nNo cart\u00e3o e no internacional, enquanto a venda n\u00e3o \u00e9 paga, `amount_cents`, `fee_cents` e `net_amount_cents` valem 0 e `fx_rate` \u00e9 nulo. Bandeira e final do cart\u00e3o v\u00eam s\u00f3 no webhook `transaction.paid`. A API n\u00e3o tem listagem de transa\u00e7\u00f5es."},"response":[]}]},{"name":"Cart\u00e3o","item":[{"name":"Criar checkout de cart\u00e3o (Throne Elements)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/elements\/checkout","host":["{{base_url}}"],"path":["elements","checkout"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 4990,\n    \"currency\": \"brl\",\n    \"customer\": {\n        \"name\": \"Maria Souza\",\n        \"email\": \"maria@exemplo.com\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Cria um checkout de cart\u00e3o para embutir na sua p\u00e1gina (permiss\u00e3o `transactions:write`). Mande o valor **na moeda do comprador**: \u00e9 nela que ele paga. A cota\u00e7\u00e3o que credita o seu saldo \u00e9 fixada na cria\u00e7\u00e3o e volta como `fx_rate` na venda paga.\n\nNa sua p\u00e1gina:\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\u00f3 n\u00famero, validade, CVV e nome impresso no cart\u00e3o. O idioma segue o pa\u00eds do comprador. A cobran\u00e7a \u00e9 \u00e0 vista. A cria\u00e7\u00e3o 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\u00e3o da conta (em contas com o roteamento por valor ligado, outra habilitada que aceite o valor, quando ele passa do m\u00e1ximo da padr\u00e3o). Adquirente n\u00e3o 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\u00e3o em `GET \/elements\/acquirers`.\n\n**Por adquirente** (detalhes no guia de cada uma):\n\n- **Sterling**: sem verifica\u00e7\u00e3o do banco; tudo dentro do elemento; 5 tentativas; fecha como `failed` na 5\u00aa recusa ou 10 minutos depois de uma recusa sem nova tentativa.\n- **Imperium**: sem verifica\u00e7\u00e3o do banco; tudo dentro do elemento; uma recusa pode levar at\u00e9 25 segundos; 5 tentativas; fecha como `failed` na 5\u00aa recusa ou 10 minutos depois de uma recusa sem nova tentativa.\n- **NovaCorp**: janela de verifica\u00e7\u00e3o do banco; em navegador de app (Instagram, Facebook) a pr\u00f3pria aba vai para a p\u00e1gina segura de pagamento e nenhum evento chega \u00e0 sua p\u00e1gina; 6 tentativas por checkout; fecha como `failed` na 6\u00aa recusa ou a partir de 10 minutos depois da \u00faltima recusa, com o comprador fora da p\u00e1gina.\n- **Eminence**: a verifica\u00e7\u00e3o do banco, quando ele pede, aparece dentro do pr\u00f3prio elemento, sem janela; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5\u00aa recusa ou 10 minutos depois de uma recusa sem nova tentativa, e na hora numa recusa depois da an\u00e1lise antifraude ou de uma confirma\u00e7\u00e3o demorada, ou quando a Eminence n\u00e3o aceita o valor da venda (`limit` na p\u00e1gina).\n- **Apex**: sem verifica\u00e7\u00e3o do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5\u00aa recusa ou 10 minutos depois de uma recusa sem nova tentativa, e na hora quando a Apex n\u00e3o aceita o valor da venda (`limit` na p\u00e1gina); uma reprova\u00e7\u00e3o na an\u00e1lise antifraude conta como recusa.\n- **ShadowBank**: sem verifica\u00e7\u00e3o do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; fecha como `failed` na 5\u00aa recusa ou 10 minutos depois de uma recusa sem nova tentativa; uma reprova\u00e7\u00e3o na an\u00e1lise antifraude conta como recusa; `customer.name` (at\u00e9 120 caracteres) e `customer.email` (e-mail v\u00e1lido, at\u00e9 180) s\u00e3o obrigat\u00f3rios na cria\u00e7\u00e3o (sem eles, ou fora desses tamanhos, `422 customer_required_for_shadowbank`).\n- **Vortex**: sem verifica\u00e7\u00e3o do banco; tudo dentro do elemento, inclusive em navegador de app; 5 tentativas; \u00e0 vista; a autoriza\u00e7\u00e3o do banco \u00e9 imediata, mas a venda ainda passa por uma an\u00e1lise de risco antes de virar paga, e nesse intervalo fica `pending` (o `transaction.paid` chega quando a an\u00e1lise libera); uma reprova\u00e7\u00e3o na an\u00e1lise conta como recusa; `customer.name` (at\u00e9 120 caracteres) e `customer.email` (e-mail v\u00e1lido, at\u00e9 180) s\u00e3o obrigat\u00f3rios na cria\u00e7\u00e3o (sem eles, ou fora desses tamanhos, `422 customer_required_for_vortex`).\n\n**Upsell em um clique e recorr\u00eancia.** Dois campos opcionais: `one_click_from` (o `transaction_id` de uma venda sua, paga) cobra um segundo produto sem pedir o cart\u00e3o de novo, e `recurrence` (`cycle` e `max_payments` opcional) cria a cobran\u00e7a que se repete sozinha. Os dois dependem da adquirente. O upsell em um clique depende tamb\u00e9m de a sua conta estar habilitada para ele (habilita\u00e7\u00e3o por conta, pelo suporte): sem a habilita\u00e7\u00e3o, ou na adquirente que n\u00e3o aceita, `one_click_from` volta `one_click: false`, sem erro. Na adquirente que n\u00e3o faz cobran\u00e7a 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\u00f3 quando a chamada manda o campo. Guias: [Upsell em um clique](https:\/\/app.thronecorporate.com\/docs\/cartao\/oneclick) e [Recorr\u00eancia](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` \u00e9 a unidade inteira.\n- O m\u00ednimo e o m\u00e1ximo por venda dependem da adquirente e variam com a moeda e com a cota\u00e7\u00e3o do dia. Fora deles, `422 invalid_amount` com `min_amount_cents` ou `max_amount_cents` na moeda enviada e, acima do m\u00e1ximo, `alternatives`. N\u00e3o 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\u00e1vel 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\u00f3 se `retryable` for `true`. Sem resposta (timeout): repita com a mesma chave.\n\n- Uma recusa com tentativas sobrando mant\u00e9m 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 \u00fanico webhook do cart\u00e3o \u00e9 `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\u00e7\u00e3o fixada na cria\u00e7\u00e3o, texto com 8 casas).\n\nGuias: [Cart\u00e3o: 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)."},"response":[]},{"name":"Criar Checkout Brasil (cart\u00e3o em portugu\u00eas, com CPF)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/elements\/checkout\/br","host":["{{base_url}}"],"path":["elements","checkout","br"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 9700,\n    \"currency\": \"brl\"\n}","options":{"raw":{"language":"json"}}},"description":"Cria um checkout de cart\u00e3o para o comprador brasileiro (permiss\u00e3o `transactions:write`), para embutir na sua p\u00e1gina com o mesmo Throne Elements do checkout comum. A p\u00e1gina sai **sempre em portugu\u00eas**, pede o **CPF** do comprador junto com o cart\u00e3o e abre para comprador de qualquer pa\u00eds. O nome e o CPF digitados v\u00e3o para a adquirente na autoriza\u00e7\u00e3o.\n\nO corpo \u00e9 o mesmo de `POST \/elements\/checkout`: `amount_cents`, `currency` e `customer` opcional, mais `appearance` (veja abaixo). Os campos `one_click_from` e `recurrence` n\u00e3o existem aqui: se vierem, `422 field_not_supported` e nada \u00e9 criado. `metadata` e itens n\u00e3o s\u00e3o aceitos.\n\n**Adquirente.** A venda vai para a adquirente habilitada para o Checkout Brasil na sua conta. O campo `acquirer` \u00e9 opcional e s\u00f3 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\u00e3o valem neste endpoint. A resposta traz `acquirer` com a que ficou com a venda, e o comportamento da p\u00e1gina depois do clique em pagar \u00e9 o dessa adquirente, como no checkout comum.\n\n**CPF.** O comprador digita o CPF na p\u00e1gina; ele \u00e9 conferido antes do envio e vai para a adquirente junto com o cart\u00e3o e o nome. O Throne n\u00e3o guarda o CPF digitado, e ele n\u00e3o volta na consulta nem no webhook. O `customer.document` da cria\u00e7\u00e3o continua opcional e segue a regra do checkout comum.\n\n**Apar\u00eancia.** `appearance` ajusta a p\u00e1gina na cria\u00e7\u00e3o: texto do bot\u00e3o, valor no bot\u00e3o, cores, formato, tamanho e moldura. Toda chave \u00e9 opcional; a que n\u00e3o vier segue o padr\u00e3o 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\u00eancia](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)."},"response":[]},{"name":"Listar as adquirentes de cart\u00e3o da conta","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/elements\/acquirers","host":["{{base_url}}"],"path":["elements","acquirers"]},"body":null,"description":"As adquirentes de cart\u00e3o 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\u00e3o \u00e9 enviado. `available: false` marca uma adquirente em pausa ou indispon\u00edvel no momento. Com `?currency=`, cada item traz `limits` com o m\u00ednimo e o m\u00e1ximo por venda nessa moeda, pela cota\u00e7\u00e3o do momento (valores indicativos: a cria\u00e7\u00e3o confere de novo). Lista vazia: a conta n\u00e3o tem cart\u00e3o habilitado. Permiss\u00e3o `transactions:write`, a mesma de criar o checkout."},"response":[]}]},{"name":"Cart\u00e3o (server-to-server, Eminence)","item":[{"name":"Tokenizar o cart\u00e3o (integra\u00e7\u00e3o direta Eminence)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/vault\/eminence\/cards","host":["{{base_url}}"],"path":["vault","eminence","cards"]},"body":{"mode":"raw","raw":"{\n    \"number\": \"5555666677778884\",\n    \"exp_month\": 12,\n    \"exp_year\": 2030,\n    \"cvv\": \"123\",\n    \"holder_name\": \"LUCA MEIER\"\n}","options":{"raw":{"language":"json"}}},"description":"Primeira chamada da integra\u00e7\u00e3o direta: troca o cart\u00e3o por um `card_token` de uso \u00fanico, para cobrar com `POST \/eminence\/payments` no passo 2.\n\n**Com a sua chave de API** (permiss\u00e3o `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integra\u00e7\u00e3o direta liberada na conta, `422 partner_api_not_enabled`.\n\n**Validade do token:** uso \u00fanico, at\u00e9 7 dias (`expires_at`). Aceita cart\u00f5es de cr\u00e9dito Visa, Mastercard, Elo, American Express e Hipercard.\n\nGuia: [Integra\u00e7\u00e3o direta (parceiros)](https:\/\/app.thronecorporate.com\/docs\/cartao\/server-to-server)."},"response":[]},{"name":"Cobrar na Eminence (integra\u00e7\u00e3o direta)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/eminence\/payments","host":["{{base_url}}"],"path":["eminence","payments"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 4990,\n    \"card_token\": \"9f0d4a1c7e2b48b1a3d0f6c89e2a4b7c\",\n    \"customer\": {\n        \"name\": \"Ana Souza\",\n        \"email\": \"ana@exemplo.com\"\n    },\n    \"description\": \"Assinatura mensal\",\n    \"metadata\": {\n        \"order_id\": \"ORD-2026-00001\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Segunda chamada da integra\u00e7\u00e3o direta: cobra na Eminence com o `card_token` do passo 1 (permiss\u00e3o `transactions:write`), \u00e0 vista e em reais. A resposta j\u00e1 traz o resultado.\n\n**Venda criada responde sempre `201`** com o `status`: `paid` (aprovado, j\u00e1 na carteira), `pending` (em an\u00e1lise ou em confirma\u00e7\u00e3o: aguarde o webhook ou consulte; n\u00e3o cobre de novo) ou `failed` (recusado ou n\u00e3o processado, nada cobrado; `retryable` diz se vale uma nova cobran\u00e7a). Erros `4xx`, `429` e `503` antes da cobran\u00e7a significam que nada foi criado.\n\n**Habilita\u00e7\u00e3o caso a caso.** Sem a libera\u00e7\u00e3o 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 \u00e9 uma transa\u00e7\u00e3o comum do Throne: consulte pelo `GET \/transactions\/{id}` e acompanhe pelo webhook `transaction.paid`. Estorno pelo suporte. A parte financeira \u00e9 a mesma do cart\u00e3o pelo Throne Elements.\n\nGuia: [Integra\u00e7\u00e3o direta (parceiros)](https:\/\/app.thronecorporate.com\/docs\/cartao\/server-to-server)."},"response":[]}]},{"name":"Cart\u00e3o (server-to-server, Vortex)","item":[{"name":"Tokenizar o cart\u00e3o (integra\u00e7\u00e3o direta Vortex)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/vault\/vortex\/cards","host":["{{base_url}}"],"path":["vault","vortex","cards"]},"body":{"mode":"raw","raw":"{\n    \"number\": \"4000000000000010\",\n    \"exp_month\": 12,\n    \"exp_year\": 2030,\n    \"cvv\": \"123\",\n    \"holder_name\": \"LENA FISCHER\"\n}","options":{"raw":{"language":"json"}}},"description":"Primeira chamada da integra\u00e7\u00e3o direta na Vortex: troca o cart\u00e3o por um `card_token` de uso \u00fanico, para cobrar com `POST \/vortex\/payments` no passo 2.\n\n**Com a sua chave de API** (permiss\u00e3o `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integra\u00e7\u00e3o direta da Vortex liberada na conta, `422 partner_api_not_enabled`. A libera\u00e7\u00e3o \u00e9 por adquirente: a da Eminence n\u00e3o vale aqui.\n\n**Validade do token:** uso \u00fanico, at\u00e9 7 dias (`expires_at`).\n\nGuia: [Server-to-server na Vortex](https:\/\/app.thronecorporate.com\/docs\/cartao\/vortex-direto)."},"response":[]},{"name":"Cobrar na Vortex (integra\u00e7\u00e3o direta)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/vortex\/payments","host":["{{base_url}}"],"path":["vortex","payments"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 4990,\n    \"currency\": \"eur\",\n    \"card_token\": \"ac1c3b53b22d47e2baa7b81662dc3a82\",\n    \"customer\": {\n        \"name\": \"Lena Fischer\",\n        \"email\": \"lena@exemplo.de\",\n        \"phone\": \"+4915112345678\",\n        \"ip\": \"91.64.12.33\"\n    },\n    \"description\": \"Plano anual\",\n    \"metadata\": {\n        \"order_id\": \"ORD-2026-00001\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Segunda chamada da integra\u00e7\u00e3o direta na Vortex: cobra com o `card_token` do passo 1 (permiss\u00e3o `transactions:write`), **na moeda do seu comprador**, \u00e0 vista. A resposta j\u00e1 traz o resultado.\n\n**Nome e e-mail do comprador s\u00e3o obrigat\u00f3rios** (`customer.name` at\u00e9 120 caracteres, `customer.email` v\u00e1lido at\u00e9 180). Sem eles, `422 customer_required_for_vortex` e nada \u00e9 criado. **O `customer.ip` tamb\u00e9m \u00e9 obrigat\u00f3rio**: \u00e9 o IP de onde o comprador est\u00e1, nunca o do seu servidor, e sem ele a chamada volta `422 customer_ip_required_for_vortex`. Mande tamb\u00e9m o `customer.document` quando o comprador tiver um: os dois entram na an\u00e1lise de risco da adquirente e aumentam a aprova\u00e7\u00e3o.\n\n**Venda criada responde sempre `201`** com o `status`: `paid` (aprovado, j\u00e1 na carteira), `pending` (autorizado pelo banco e em an\u00e1lise de risco: aguarde o webhook ou consulte; n\u00e3o cobre de novo) ou `failed` (recusado ou n\u00e3o processado, nada cobrado; `retryable` diz se vale uma nova cobran\u00e7a). Erros `4xx`, `429` e `503` antes da cobran\u00e7a significam que nada foi criado.\n\n**A aprova\u00e7\u00e3o nem sempre \u00e9 imediata.** Na Vortex o banco autoriza na hora e a venda ainda passa por an\u00e1lise de risco. Nesse intervalo o `status` \u00e9 `pending`, e isso \u00e9 normal.\n\n**Recorr\u00eancia.** `recurrence` com `cycle` (um dos sete) e `max_payments` opcional, de 2 a 120, contando esta cobran\u00e7a: esta \u00e9 a primeira e as seguintes saem sozinhas, no mesmo cart\u00e3o. A resposta `201` traz `recurrence_id`, `cycle` e `next_charge_at`. A assinatura s\u00f3 passa a valer quando esta cobran\u00e7a aprova, e aqui a aprova\u00e7\u00e3o nem sempre \u00e9 imediata: at\u00e9 l\u00e1 a recorr\u00eancia fica em `pending`. `recurrence_id` nulo quer dizer que a assinatura n\u00e3o abriu e n\u00e3o haver\u00e1 cobran\u00e7as seguintes. Ciclo fora dos sete: `422 invalid_cycle`, nada criado. Consulta e cancelamento em `\/recurrences`. Guia: [Recorr\u00eancia](https:\/\/app.thronecorporate.com\/docs\/cartao\/recorrencias).\n\n**Habilita\u00e7\u00e3o caso a caso**, \u00e0 parte da Eminence. Sem a libera\u00e7\u00e3o, `422 partner_api_not_enabled`. Sem a Vortex habilitada, `422 acquirer_not_enabled`.\n\nA venda \u00e9 uma transa\u00e7\u00e3o 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)."},"response":[]},{"name":"Upsell em um clique na Vortex (integra\u00e7\u00e3o direta)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/vortex\/upsell","host":["{{base_url}}"],"path":["vortex","upsell"]},"body":{"mode":"raw","raw":"{\n    \"parent_transaction_id\": \"e1b9c0a4-7f3d-4e21-9a8b-3c5d6e7f8a90\",\n    \"amount_cents\": 4700,\n    \"currency\": \"usd\",\n    \"description\": \"Plano anual\",\n    \"metadata\": {\n        \"order_id\": \"ORD-2026-00001-up1\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Cobra um segundo produto no **mesmo cart\u00e3o** de uma venda j\u00e1 paga, sem pedir o cart\u00e3o outra vez ao comprador e **sem `card_token`** (permiss\u00e3o `transactions:write`). \u00c9 a oferta do p\u00f3s-compra: o comprador clica uma vez.\n\n**N\u00e3o existe `card_token` nesta rota, e \u00e9 esse o ponto.** Tamb\u00e9m n\u00e3o existem `customer` nem `installments`: o comprador \u00e9 o da venda de origem e o upsell \u00e9 sempre \u00e0 vista. Qualquer um desses campos no corpo volta `422 field_not_supported` e nada \u00e9 criado \u2014 de prop\u00f3sito, para voc\u00ea n\u00e3o receber um `201` achando que mandou um cart\u00e3o.\n\n**O upsell pode ser RECORRENTE.** Mande o mesmo campo `recurrence` da cobran\u00e7a comum e este upsell passa a ser a primeira cobran\u00e7a de uma assinatura, no mesmo cart\u00e3o, enquanto a venda de origem continua \u00fanica. A resposta ganha `recurrence_id`, `cycle` e `next_charge_at`. A assinatura s\u00f3 passa a valer quando este upsell for aprovado, e aqui a aprova\u00e7\u00e3o nunca \u00e9 imediata: at\u00e9 l\u00e1 a recorr\u00eancia fica `pending`. Ciclo fora dos sete volta `422 invalid_cycle` e nada \u00e9 criado nem cobrado.\n\n**`pending` \u00e9 o desfecho normal, e j\u00e1 significa cobrado.** Nesta adquirente o banco autoriza na hora e a venda ainda passa por an\u00e1lise de risco; no upsell h\u00e1 um motivo a mais: o processador confirma a cobran\u00e7a sem devolver o n\u00famero do pedido dela, que chega depois, no aviso. Ent\u00e3o espere o `transaction.paid` e **n\u00e3o repita a chamada** \u2014 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\u00e7\u00e3o, da Vortex, dentro de **120 minutos** do pagamento, com no m\u00e1ximo **5 upsells**, e cobrada pela integra\u00e7\u00e3o direta da Vortex **depois de 28\/10\/2026** (antes disso o cart\u00e3o n\u00e3o era guardado). Fora dessas regras, `409` com o motivo. Upsell de upsell funciona: aponte o `parent_transaction_id` para o primeiro.\n\n**Habilita\u00e7\u00e3o \u00e0 parte.** Ter a integra\u00e7\u00e3o direta liberada n\u00e3o basta: o upsell em um clique \u00e9 liberado conta por conta. Sem isso, `403 one_click_not_enabled`.\n\nS\u00f3 na integra\u00e7\u00e3o direta: no checkout hospedado da Vortex o campo `one_click_from` continua respondendo `one_click: false`.\n\nA venda \u00e9 uma transa\u00e7\u00e3o comum do Throne: consulte pelo `GET \/transactions\/{id}` e acompanhe pelo webhook `transaction.paid`, que **n\u00e3o ganha campo novo** \u2014 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)."},"response":[]}]},{"name":"Cart\u00e3o (server-to-server, ShadowBank)","item":[{"name":"Tokenizar o cart\u00e3o (integra\u00e7\u00e3o direta ShadowBank)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/vault\/shadowbank\/cards","host":["{{base_url}}"],"path":["vault","shadowbank","cards"]},"body":{"mode":"raw","raw":"{\n    \"number\": \"5555555555554444\",\n    \"exp_month\": 11,\n    \"exp_year\": 2031,\n    \"cvv\": \"737\",\n    \"holder_name\": \"MARIA S SOUZA\",\n    \"customer\": {\n        \"name\": \"Maria Souza\",\n        \"email\": \"maria@exemplo.com\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Primeira chamada da integra\u00e7\u00e3o direta na ShadowBank: troca o cart\u00e3o por um `card_token`, para cobrar com `POST \/shadowbank\/payments` no passo 2.\n\n**Com a sua chave de API** (permiss\u00e3o `transactions:write`), sempre a partir do seu servidor, nunca do navegador do comprador. Sem a integra\u00e7\u00e3o direta da ShadowBank liberada na conta, `422 partner_api_not_enabled`. A libera\u00e7\u00e3o \u00e9 por adquirente: a da Eminence e a da Vortex n\u00e3o valem aqui.\n\n**Validade do token:** at\u00e9 7 dias (`expires_at`), e nunca depois do fim do m\u00eas de validade do cart\u00e3o.\n\n**O bloco `customer` \u00e9 opcional e recomendado.** Dele s\u00f3 o nome chega \u00e0 adquirente; o resto serve para que o mesmo comprador caia sempre no mesmo cadastro do lado dela quando voltar a comprar \u2014 e \u00e9 isso que d\u00e1 ao upsell em um clique um cart\u00e3o para reencontrar. Mande o mesmo `customer` que voc\u00ea vai mandar na cobran\u00e7a.\n\nGuia: [Server-to-server na ShadowBank](https:\/\/app.thronecorporate.com\/docs\/cartao\/shadowbank-direto)."},"response":[]},{"name":"Cobrar no cart\u00e3o (integra\u00e7\u00e3o direta ShadowBank)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/shadowbank\/payments","host":["{{base_url}}"],"path":["shadowbank","payments"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 2500,\n    \"currency\": \"BRL\",\n    \"card_token\": \"sbt_7b58f4a1600bd9419cb20b7f111bc831\",\n    \"description\": \"Plano Pro\",\n    \"customer\": {\n        \"name\": \"Maria Souza\",\n        \"email\": \"maria@exemplo.com\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Segunda chamada da integra\u00e7\u00e3o direta na ShadowBank: cobra o `card_token` do passo 1. Voc\u00ea cobra na **moeda do seu comprador** e a cota\u00e7\u00e3o que credita o seu saldo \u00e9 fixada aqui.\n\n**S\u00f3 o nome do comprador \u00e9 obrigat\u00f3rio** (`customer.name`, at\u00e9 120 caracteres). O e-mail \u00e9 opcional: esta adquirente cobra sem ele. Sem o nome, `422 customer_required_for_shadowbank` e nada \u00e9 criado.\n\n**Sempre \u00e0 vista.** `installments` s\u00f3 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\u00e1lise ou indefinido \u2014 **n\u00e3o repita**) ou `failed` (recusado; `retryable` diz se pode tentar de novo com um token novo).\n\n`pending` \u00e9 desfecho normal, n\u00e3o erro: a cobran\u00e7a pode cair em an\u00e1lise da adquirente e fechar depois, pelo webhook.\n\n**Cobran\u00e7a recorrente:** mande `recurrence` e esta cobran\u00e7a vira a primeira de uma assinatura. A adquirente guarda o cart\u00e3o e cobra os ciclos seguintes sozinha, a partir do ciclo 2 \u2014 o comprador nunca \u00e9 cobrado duas vezes no mesmo dia. A assinatura s\u00f3 abre se esta cobran\u00e7a for aprovada.\n\n**Upsell em um clique:** n\u00e3o \u00e9 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)."},"response":[]},{"name":"Upsell em um clique (integra\u00e7\u00e3o direta ShadowBank)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/shadowbank\/upsell","host":["{{base_url}}"],"path":["shadowbank","upsell"]},"body":{"mode":"raw","raw":"{\n    \"parent_transaction_id\": \"a960cd5a-a166-4e16-8e28-72a64b4013ed\",\n    \"amount_cents\": 1500,\n    \"currency\": \"BRL\",\n    \"description\": \"Garantia estendida\"\n}","options":{"raw":{"language":"json"}}},"description":"Cobra o **mesmo cart\u00e3o** de uma venda que j\u00e1 foi paga, sem pedir o cart\u00e3o ao comprador de novo e **sem `card_token` nenhum**. Voc\u00ea manda s\u00f3 o `transaction_id` da venda de origem, em `parent_transaction_id`.\n\nPrecisa, al\u00e9m da integra\u00e7\u00e3o direta liberada, do **upsell em um clique habilitado na conta** \u2014 \u00e9 por conta, n\u00e3o por adquirente. Sem ele, `403 one_click_not_enabled`.\n\n**O upsell pode ser recorrente:** mande `recurrence` e ele vira a primeira cobran\u00e7a de uma assinatura, igual \u00e0 cobran\u00e7a 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\u00e3o), com o cart\u00e3o guardado e abaixo do limite de upsells por venda (5). Qualquer um desses faltando \u00e9 `409`, e v\u00e1rias dessas situa\u00e7\u00f5es respondem a MESMA coisa de prop\u00f3sito \u2014 a resposta n\u00e3o conta nada a mais sobre a venda de origem do que voc\u00ea j\u00e1 sabe.\n\n**O valor tem um teto pr\u00f3prio:** o menor entre um limite absoluto e vinte vezes o valor da venda de origem. Ele existe porque o comprador n\u00e3o digita nada nesta cobran\u00e7a.\n\n**Campos que esta rota n\u00e3o tem:** `card_token`, `customer`, `installments` e `one_click_from`. Qualquer um deles \u00e9 `422 field_not_supported`, com o nome em `field` \u2014 nunca descartado em sil\u00eancio.\n\nGuia: [Server-to-server na ShadowBank](https:\/\/app.thronecorporate.com\/docs\/cartao\/shadowbank-direto#upsell-em-um-clique)."},"response":[]}]},{"name":"Recorr\u00eancias","item":[{"name":"Listar recorr\u00eancias","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/recurrences","host":["{{base_url}}"],"path":["recurrences"]},"body":null,"description":"As recorr\u00eancias da conta, as mais recentes primeiro (permiss\u00e3o `transactions:read`), em `data`, com a pagina\u00e7\u00e3o em `meta`. `per_page` vai de 1 a 100 (padr\u00e3o 25); fora da faixa, vale o limite mais perto. Guia: [Recorr\u00eancia](https:\/\/app.thronecorporate.com\/docs\/cartao\/recorrencias)."},"response":[]},{"name":"Consultar recorr\u00eancia","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/recurrences\/:id","host":["{{base_url}}"],"path":["recurrences","{id}"]},"body":null,"description":"Uma recorr\u00eancia da conta (permiss\u00e3o `transactions:read`). Quem diz se ela ainda cobra \u00e9 `status`. `charges_count` e `last_charge_at` contam as cobran\u00e7as desta recorr\u00eancia que existem na sua conta. `next_charge_at` \u00e9 uma estimativa: libere e corte acesso pelo `transaction.paid` de cada cobran\u00e7a. Recorr\u00eancia de outra conta responde `404`. Guia: [Recorr\u00eancia](https:\/\/app.thronecorporate.com\/docs\/cartao\/recorrencias)."},"response":[]},{"name":"Cancelar recorr\u00eancia","request":{"method":"POST","header":[],"url":{"raw":"{{base_url}}\/recurrences\/:id\/cancel","host":["{{base_url}}"],"path":["recurrences","{id}","cancel"]},"body":null,"description":"Para as cobran\u00e7as seguintes (permiss\u00e3o `transactions:write`). Com `200`, a recorr\u00eancia n\u00e3o cobra mais, e a resposta traz a recorr\u00eancia. Pedir o cancelamento de uma recorr\u00eancia que j\u00e1 tinha parado tamb\u00e9m responde `200`, sem efeito. N\u00e3o estorna e n\u00e3o mexe em venda nenhuma. N\u00e3o usa `Idempotency-Key`: repetir \u00e9 seguro. Sem `200`, o cancelamento n\u00e3o foi confirmado e a resposta \u00e9 `cancel_failed`: enquanto n\u00e3o vier `200`, trate a recorr\u00eancia como ativa. Guia: [Recorr\u00eancia](https:\/\/app.thronecorporate.com\/docs\/cartao\/recorrencias)."},"response":[]}]},{"name":"Internacional (Paycore)","item":[{"name":"Criar checkout internacional","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/global\/checkout","host":["{{base_url}}"],"path":["global","checkout"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 2000,\n    \"currency\": \"usd\",\n    \"customer\": {\n        \"name\": \"John Carter\",\n        \"email\": \"john@example.com\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"Cria um checkout internacional (permiss\u00e3o `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\u00e3o serve para este trilho.\n\nA p\u00e1gina avisa a sua por `postMessage` (`throne-elements:ready`, `paid`, `error` e `resize` com `height`). A cota\u00e7\u00e3o que credita o seu saldo \u00e9 fixada na aprova\u00e7\u00e3o, n\u00e3o na cria\u00e7\u00e3o. Uma recusa mant\u00e9m 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)."},"response":[]}]},{"name":"Links de pagamento","item":[{"name":"Listar links de pagamento","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/payment-links","host":["{{base_url}}"],"path":["payment-links"]},"body":null,"description":"Os 100 links mais recentes (permiss\u00e3o `payment_links:read`)."},"response":[]},{"name":"Criar link de pagamento","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/payment-links","host":["{{base_url}}"],"path":["payment-links"]},"body":{"mode":"raw","raw":"{\n    \"description\": \"Consultoria de 1 hora\",\n    \"amount_cents\": 15000,\n    \"max_uses\": 1\n}","options":{"raw":{"language":"json"}}},"description":"Cria uma p\u00e1gina de pagamento pronta (permiss\u00e3o `payment_links:write`). Compartilhe o campo `url` da resposta. Cada pagamento feito pelo link \u00e9 uma cobran\u00e7a Pix e gera `transaction.paid`. Com o recebimento por Pix desabilitado na conta, a resposta \u00e9 `422 pix_not_enabled` e o link n\u00e3o \u00e9 criado; um link j\u00e1 criado mostra \"Link indispon\u00edvel\" ao comprador at\u00e9 o recebimento ser habilitado de novo."},"response":[]},{"name":"Consultar link de pagamento","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/payment-links\/:id","host":["{{base_url}}"],"path":["payment-links","{id}"]},"body":null,"description":null},"response":[]},{"name":"Desativar link de pagamento","request":{"method":"POST","header":[],"url":{"raw":"{{base_url}}\/payment-links\/:id\/revoke","host":["{{base_url}}"],"path":["payment-links","{id}","revoke"]},"body":null,"description":null},"response":[]}]},{"name":"Saques","item":[{"name":"Pedir saque (Pix ou cripto)","request":{"method":"POST","header":[{"key":"Idempotency-Key","value":"6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b","type":"text"},{"key":"Content-Type","value":"application\/json","type":"text"}],"url":{"raw":"{{base_url}}\/withdrawals","host":["{{base_url}}"],"path":["withdrawals"]},"body":{"mode":"raw","raw":"{\n    \"amount_cents\": 50000,\n    \"totp_code\": \"123456\",\n    \"destination\": {\n        \"key\": \"12345678909\",\n        \"key_type\": \"cpf\"\n    }\n}","options":{"raw":{"language":"json"}}},"description":"**Sem ambiente de testes: qualquer chave com esta permiss\u00e3o, inclusive `pk_test_`, transfere dinheiro de verdade.**\n\nExige: permiss\u00e3o `withdrawals:write` (desligada por padr\u00e3o), 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\u00ednimo padr\u00e3o R$ 50,00 (a conta pode ter outro), m\u00e1ximo R$ 500.000,00, limite di\u00e1rio 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}`."},"response":[]},{"name":"Consultar saque","request":{"method":"GET","header":[],"url":{"raw":"{{base_url}}\/withdrawals\/:id","host":["{{base_url}}"],"path":["withdrawals","{id}"]},"body":null,"description":"Permiss\u00e3o `withdrawals:read`. `failure_reason` vem em linguagem pronta para mostrar ao seu cliente. A API n\u00e3o tem listagem de saques."},"response":[]}]}]}