Comece aqui

URL base#

Todas as chamadas usam HTTPS e esta base:

https://app.thronecorporate.com/api/v1

O endereço https://api.thronecorporate.com/api/v1 responde igual. O caminho sempre começa com /api/v1: sem o /api, a resposta é 404.

Autenticação#

Toda chamada leva o header Authorization com a chave pública e a secreta separadas por dois-pontos:

Authorization: Bearer pk_live_xxxxxxxx:sk_live_xxxxxxxx

Envie exatamente assim, em texto. Não codifique em base64.

Gere as chaves no painel, em Chaves de API. A chave secreta aparece uma vez só, na criação. Guarde no seu servidor e nunca coloque no navegador, no aplicativo ou num repositório de código.

Teste a chave com uma chamada simples:

curl https://app.thronecorporate.com/api/v1/balance \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Accept: application/json"

$ch = curl_init('https://app.thronecorporate.com/api/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('THRONE_PK') . ':' . getenv('THRONE_SK'),
        'Accept: application/json',
    ],
]);
$saldo = json_decode(curl_exec($ch), true);

const res = await fetch('https://app.thronecorporate.com/api/v1/balance', {
  headers: {
    Authorization: `Bearer ${process.env.THRONE_PK}:${process.env.THRONE_SK}`,
    Accept: 'application/json',
  },
  signal: AbortSignal.timeout(20000),
});
const saldo = await res.json();

import os, requests

r = requests.get(
    "https://app.thronecorporate.com/api/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['THRONE_PK']}:{os.environ['THRONE_SK']}",
        "Accept": "application/json",
    },
    timeout=20,
)
saldo = r.json()

Se a autenticação falhar, a resposta é sempre 401 com {"error": "unauthorized", "detail": "..."}. O campo detail diz o motivo:

Permissões da chave#

Cada chave tem permissões (escopos). Sem a permissão certa, a resposta é 403 com error: "scope_required" e o campo required_scope.

As duas listas de IP da chave#

A lista de IPs da chave é opcional, mas uma chave de produção com a permissão de saque exige as duas listas. Por isso, use uma chave só para saques, rodando de um servidor com IP fixo, e outra para cobranças.

Não existe ambiente de testes separado#

Atenção Hoje as chaves pk_test_ funcionam como as de produção. Um checkout de cartão cobra o cartão de verdade e um saque transfere dinheiro de verdade. Teste com valores baixos e com o seu próprio cartão ou chave Pix.

O roteiro completo, com os erros que dá para provocar sem custo, está em Como testar.

Idempotency-Key#

Toda chamada que cria algo exige o header Idempotency-Key: POST /transactions, POST /elements/checkout, POST /global/checkout, POST /withdrawals e POST /payment-links. Sem ele, a resposta é 400 idempotency_key_required.

Idempotency-Key: 6f1c2b8e-3a4d-4e5f-9a7b-1c2d3e4f5a6b

Regras:

• De 8 a 128 caracteres; fora disso, 400 idempotency_key_required. Use um UUID v4 novo para cada cobrança, checkout ou saque. Não use número de pedido nem sequência, que são curtos e previsíveis.
• A Idempotency-Key vale para a sua conta inteira por 24 horas, em todos os endpoints.
• Gere a chave antes de chamar e guarde junto do seu pedido. É ela que permite repetir sem duplicar.
• Mesma Idempotency-Key com corpo diferente: 422 idempotency_key_mismatch, enquanto a chave valer. A ordem dos campos no JSON não importa.

Como repetir uma chamada com segurança#

Esta é a regra única de repetição da API. Ela vale para todo POST que exige Idempotency-Key e mostra o que acontece quando você repete a chamada com a mesma chave e o mesmo corpo.

As respostas 400 idempotency_key_required e 401 unauthorized saem antes da chave ser registrada: depois de corrigir, a mesma chave pode ser usada.

Timeout do seu lado. Repita com a mesma chave e o mesmo corpo. Se a primeira chamada já terminou, você recebe a resposta dela. Se a resposta for 409 idempotency_key_processing, espere alguns segundos e repita de novo. Se o 409 idempotency_key_processing continuar por mais de 2 minutos, a primeira chamada terminou com erro de servidor: confira no painel se algo foi criado antes de seguir com uma chave nova.

409 idempotency_key_in_use. Essa Idempotency-Key não pode ser usada pela sua conta. Gere outra.

Tempo de resposta e timeouts#

Configure um timeout no seu cliente HTTP. Ele precisa ser maior que o tempo que a API leva para responder, senão você desiste de uma chamada que deu certo.

A criação do checkout de cartão fala com a adquirente e costuma responder em poucos segundos. Em horário de pico ela pode demorar mais, por isso o valor maior. Se mesmo assim o timeout estourar, repita com a mesma Idempotency-Key, como na tabela acima. Os limites e o que fazer com 429 e 503 estão em Limites e tempos.

Limites de requisição#

Passou do limite, a resposta é 429. Espere o tempo do header Retry-After (em segundos) e tente de novo com uma Idempotency-Key nova. Ignore os headers X-RateLimit-* das respostas: eles não refletem os limites acima.

Formato das respostas#

• Corpo sempre em JSON, com Content-Type: application/json. Envie também Accept: application/json em toda chamada.
• Valores em centavos inteiros (amount_cents): R$ 49,90 é 4990. No cartão, na menor unidade da moeda enviada.
• Datas em ISO 8601. As da cobrança, do checkout e do saque vêm em UTC (2026-10-03T14:20:00Z); payment_data.expires_at do Pix e as datas dos links de pagamento vêm com fuso (por exemplo, -03:00). Use um leitor de ISO 8601 que aceite os dois formatos.
• IDs de transação e de saque são UUID em letras minúsculas. Use o id exatamente como veio.
• Campos novos podem aparecer nas respostas e nos webhooks, sempre como acréscimo. Ignore os campos que você não conhece. As mudanças ficam no Changelog.

Formato dos erros#

Erro de campo (validação) volta 422 com a lista por campo:

{
  "message": "O campo amount cents é obrigatório.",
  "errors": { "amount_cents": ["O campo amount cents é obrigatório."] }
}

Erro de regra volta com um código fixo em error e um texto em message:

{ "error": "invalid_request", "message": "Valor mínimo de cobrança: R$ 1,00." }

Alguns erros trazem campos extras para você decidir sem ler o texto. Por exemplo, uma indisponibilidade temporária no cartão:

{ "error": "temporarily_unavailable", "message": "A adquirente está temporariamente indisponível. Tente em instantes.", "retryable": true }

Trate os erros pelo campo error (fixo) e mostre o message só como apoio, porque o texto pode mudar. A lista completa, com o que fazer em cada caso, está em Erros.

Próximo passo#

• Vai receber por Pix: Cobrar com Pix.
• Vai receber cartão: Cartão: como funciona.
• Precisa saber quando a venda foi paga: Webhooks.
• Antes de vender: Checklist de verificação.