Checkout Brasil

O que é#

O Checkout Brasil é o checkout de cartão para o comprador brasileiro. Você cria o checkout com POST /elements/checkout/br e coloca o transaction_id no mesmo Throne Elements que já usa. O que muda está na página que o comprador vê: ela sai sempre em português, pede o CPF junto com o cartão e abre para comprador de qualquer país.

O nome e o CPF que o comprador digita vão para a adquirente junto com o cartão, na autorização. São os dados que o emissor de um cartão brasileiro espera receber numa compra.

Nota Nada a mudar no que já está no ar. O POST /elements/checkout continua igual, com a mesma resposta e o mesmo webhook. O Checkout Brasil é um endpoint a mais, para a página do seu funil que vende ao comprador brasileiro.

Antes de começar#

O Checkout Brasil funciona nas adquirentes habilitadas para o Checkout Brasil na sua conta. As adquirentes de cartão da sua conta estão em GET /elements/acquirers, mas nem toda adquirente atende o Checkout Brasil: se nenhuma das suas atender, a criação responde 422 acquirer_not_enabled e nada é criado. Para pedir a habilitação, fale com o suporte.

• A chave de API é a mesma, com a permissão transactions:write. Nenhuma chave precisa ser gerada de novo.
• O comprador precisa ter CPF. Sem um CPF válido, o pagamento não sai da página. Para o comprador sem CPF, use o checkout comum.
• A Idempotency-Key, o timeout de 60 segundos e a regra de repetição são os de sempre. Veja Comece aqui.

Criar#

A criação fala com a adquirente. Use 60 segundos de timeout no seu cliente HTTP e gere a Idempotency-Key antes de chamar, guardando junto do pedido. Use uma chave nova, nunca a de uma chamada ao POST /elements/checkout: a chave devolve a resposta da chamada em que foi usada.

curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout/br \
  --max-time 60 \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_cents": 9700,
    "currency": "brl",
    "customer": { "name": "Maria Souza", "email": "maria@exemplo.com" }
  }'

201 Created:

{
  "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"
}

A resposta é a mesma do checkout comum: transaction_id, status, checkout_url, acquirer (a adquirente que ficou com a venda), display, expires_at e, quando houver aviso, warnings. Veja a resposta do checkout comum. O que é próprio do Checkout Brasil está em Referência dos campos.

Na sua página, nada muda:

<div data-throne-elements
     data-id="c4d7a2b1-6e3f-4a9c-8b5d-2f1e0a9c7b63"
     data-color="#7c3aed"
     data-theme="light"
     data-radius="10"></div>

<script src="https://app.thronecorporate.com/throne-elements.js" async></script>

O elemento monta a página em português, com o campo de CPF junto dos dados do cartão. O comprador digita o cartão, o nome e o CPF, e paga. Os eventos throne-elements:ready, throne-elements:paid e throne-elements:error chegam como sempre. A confirmação que vale para liberar o pedido continua sendo o webhook transaction.paid ou o GET /transactions/{id} com status: "paid".

O que muda em relação ao checkout comum#

O comportamento da página depois do clique em pagar (verificação do banco, tentativas, códigos em throne-elements:error) é o da adquirente que ficou com a venda, como no checkout comum: veja o guia dela em Comparar adquirentes.

Aparência#

Você pode ajustar a página do Checkout Brasil na própria criação, com o objeto appearance: o texto do botão, se o valor aparece nele, as cores, o arredondamento, a altura e a largura do botão, e uma moldura em volta dos campos. Tudo é opcional. O que você não mandar segue o padrão e os atributos data-color e data-radius do elemento, como hoje.

curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout/br \
  --max-time 60 \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_cents": 9700,
    "currency": "brl",
    "appearance": {
      "button": { "text": "Finalizar compra", "background_color": "#15803d" },
      "fields": { "radius": 8 },
      "frame": { "border_width": 1, "padding": 24, "shadow": "md" }
    }
  }'

O botão sai "Finalizar compra R$ 97,00" em verde, com o texto em branco escolhido sozinho para ficar legível, e os campos ficam dentro de uma moldura com borda e sombra.

Como a validação funciona:

• Mande JSON com os tipos certos: 48, não "48"; false, não "false". Uma chave com null vale como ausente.
• Chave que não existe, valor fora da regra ou combinação impossível: 422 invalid_appearance e nada é criado. A resposta traz field com o caminho da chave, por exemplo appearance.button.text.
• O texto do botão não aceita, em maiúsculas ou minúsculas, as palavras real, reais, centavo, centavos, grátis, gratis, gratuito, gratuita, free, zero, cancelar, voltar, fechar e sair: o botão sempre paga o valor da venda.
• Contraste: text_color com contraste menor que 3:1 sobre background_color é recusado. De 3:1 até 4,5:1 é aceito, com o aviso low_contrast em warnings. Branco sobre #16a34a dá 3,29:1 (aceito, com aviso); branco sobre #15803d, 5,01:1.
• fields.focus_color que quase some sobre fundo claro ou escuro também gera low_contrast.
• A moldura precisa deixar pelo menos 256 px para os campos: frame.max_width, menos 32 (ou 56 com shadow: lg), menos duas vezes a soma de frame.padding e frame.border_width.

Quem vence quando você também usa os atributos do elemento:

As chaves que você manda ficam gravadas na criação e não mudam pela URL do checkout; as que você não manda seguem os atributos do elemento. Para mudar o que foi gravado, crie um checkout novo.

O que não muda: os nomes e os exemplos dos campos (número do cartão, nome no cartão, validade, CVV e CPF), a frase de segurança abaixo do botão, os textos de processamento, de verificação do banco, de aprovação e de recusa, o botão "Tentar de novo", a fonte e as bandeiras. São os textos que o comprador e o banco esperam ver numa página de pagamento.

O botão em cada momento: antes do clique, o seu texto, com ou sem o valor; durante o envio, "Processando", desativado e nas suas cores; recusado, a tela de recusa com "Tentar de novo", e de volta ao formulário o botão volta ao seu texto; aprovado, a tela de pagamento aprovado.

Erros#

Os erros do checkout comum valem aqui, com o mesmo significado: invalid_amount, currency_not_supported, fx_unavailable, card_not_enabled, invalid_acquirer, os de Idempotency-Key, 502 checkout_failed e 503 temporarily_unavailable. Veja a tabela do checkout comum. O que é próprio do Checkout Brasil:

No Checkout Brasil, invalid_amount vem com alternatives vazio e o 503 não sugere outra adquirente: acima do máximo, divida o pedido.

Decida sempre pelo campo error. O message é texto de apoio e pode mudar.

Perguntas que aparecem sempre#

O CPF do comprador fica guardado? Não. Ele vai para a adquirente na autorização do pagamento e só. O Throne não guarda o CPF digitado, e ele não volta na consulta nem no webhook. Se você quiser o documento registrado na venda, mande customer.document na criação, como no checkout comum.

Serve para Pix? Não. O Checkout Brasil é só cartão. Para Pix, use POST /transactions com payment_method: "pix", como em Cobrar com Pix.

Posso usar o mesmo Throne Elements? Sim. O script, os atributos e os eventos são os mesmos: só troque o data-id pelo transaction_id novo. Vale a regra de sempre: para trocar de checkout, use um container novo (detalhes).

Preciso de outra chave de API? Não. A mesma chave, com transactions:write, cria os dois checkouts.

E se o comprador não tiver CPF? O pagamento não sai: o campo é obrigatório e conferido na tela. Para esse comprador, crie o checkout comum.

O customer.document da criação preenche o CPF? Não. O campo CPF da página nasce vazio e o comprador digita o dele. O que vai para a adquirente é o CPF digitado na tela; o customer.document fica registrado na venda e volta no webhook, como no checkout comum.

O ?nl= no checkout_url muda o idioma? Não. No Checkout Brasil a página sai em português sempre, inclusive para teste.

A venda aparece diferente na consulta ou no webhook? Não. É uma venda de cartão como as outras: mesmo GET /transactions/{id}, mesmo transaction.paid, mesmo acquirer.

Posso mudar a frase de segurança ou o nome dos campos? Não. Só o botão, as cores, o formato e a moldura mudam, pelo objeto appearance. O resto é o texto que o comprador e o banco esperam ver numa página de pagamento.

O appearance funciona no POST /elements/checkout? Não. Ele só existe no Checkout Brasil; no checkout comum o campo é ignorado.

Referência dos campos#

Requisição, POST /elements/checkout/br:

metadata e itens não são aceitos, como no checkout comum: guarde o transaction_id para ligar a venda ao seu pedido.

Resposta 201: os mesmos campos do checkout comum. Veja a referência da resposta. O que é próprio do Checkout Brasil:

• warnings pode trazer, além dos avisos de customer, o aviso low_contrast, sobre appearance.

Veja também Cartão: como funciona e Throne Elements.