Internacional (Paycore)

Visão geral#

O Internacional (Paycore) é um botão de pagamento embutido na sua página. O comprador conclui o pagamento com carteira digital internacional ou cartão internacional, dentro do checkout do Throne. É um trilho separado do cartão, e os dois podem ficar habilitados ao mesmo tempo.

Diferenças importantes em relação ao cartão:

O transaction_id de um trilho não funciona no outro.

1. Criar o checkout#

curl -X POST https://app.thronecorporate.com/api/v1/global/checkout \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount_cents": 2000, "currency": "usd", "customer": { "name": "John Carter", "email": "john@example.com" } }'

import { randomUUID } from 'node:crypto';

const res = await fetch('https://app.thronecorporate.com/api/v1/global/checkout', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.THRONE_PK}:${process.env.THRONE_SK}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({ amount_cents: 2000, currency: 'usd', customer: { name: 'John Carter', email: 'john@example.com' } }),
});
const { transaction_id, checkout_url } = await res.json(); // res.status === 201

import os, uuid, requests

r = requests.post(
    "https://app.thronecorporate.com/api/v1/global/checkout",
    headers={
        "Authorization": f"Bearer {os.environ['THRONE_PK']}:{os.environ['THRONE_SK']}",
        "Accept": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"amount_cents": 2000, "currency": "usd",
          "customer": {"name": "John Carter", "email": "john@example.com"}},
    timeout=20,
)
checkout = r.json()  # r.status_code == 201

Outros campos (metadata, itens, documento, endereço) são ignorados neste endpoint. Guarde o transaction_id para ligar a venda ao seu pedido.

Resposta 201 Created:

{
  "transaction_id": "5f0a2c1e-8d3b-4c7a-9e21-6b4d8f2a1c90",
  "status": "pending",
  "checkout_url": "https://app.thronecorporate.com/global/5f0a2c1e-8d3b-4c7a-9e21-6b4d8f2a1c90"
}

2. Embutir na sua página#

Coloque o checkout_url num iframe, com embed=1 e, se quiser, a aparência:

<iframe id="pagamento-internacional"
        src="CHECKOUT_URL?embed=1&color=%237c3aed&theme=light&radius=10"
        allow="payment"
        title="Pagamento"
        style="width:100%; border:0; min-height:520px"></iframe>

• color: cor no formato #rrggbb (na URL, # vira %23).
• theme: light ou dark.
• radius: cantos arredondados, de 0 a 32.
• Mantenha allow="payment": sem ele, a carteira digital pode não funcionar dentro do iframe.

O checkout avisa a sua página por postMessage. Escute as mensagens para ajustar a altura e reagir ao pagamento:

const frame = document.getElementById('pagamento-internacional');
const origemThrone = new URL(frame.src).origin;

window.addEventListener('message', (ev) => {
  if (ev.origin !== origemThrone || !ev.data || typeof ev.data.type !== 'string') return;
  switch (ev.data.type) {
    case 'throne-elements:resize':
      frame.style.height = ev.data.height + 'px';
      break;
    case 'throne-elements:paid':
      // o comprador concluiu: mostre o "obrigado"
      break;
    case 'throne-elements:error':
      // ev.data.message: o comprador pode tentar de novo
      break;
  }
});

Como no cartão, esses eventos são sinais de tela. A confirmação que vale é o webhook transaction.paid ou a consulta.

3. Confirmar a venda#

A venda vira paid quando o pagamento é capturado. Isso pode levar alguns instantes depois de o comprador concluir. Você recebe o webhook transaction.paid, no mesmo formato do cartão:

• payment_method vem sempre credit_card, inclusive quando o comprador pagou com carteira digital. card_brand e card_last4 vêm null.
• currency e native_amount_cents são a moeda e o valor que você mandou.
• amount_cents é o valor bruto creditado no seu saldo, em reais (a moeda da sua conta), e net_amount_cents o líquido, já descontada a taxa de cartão da sua conta.
• fx_rate é a cotação usada para creditar o seu saldo (reais por 1 unidade da moeda da venda), fixada na aprovação. Em venda criada em BRL, fx_rate vale 1.

Antes do pagamento, a consulta mostra amount_cents igual a 0 e fx_rate nulo.

Recusas, estornos e contestações#

• Recusa não encerra a venda: ela continua pending e o comprador pode tentar de novo no mesmo checkout.
• Estorno total deixa a venda refunded; o parcial mantém paid com o valor reduzido.
• Contestação deixa a venda chargeback.
• Nenhum desses eventos gera webhook. Acompanhe pelo GET /transactions/{id}.

Erros#

Trate pelo campo error; o texto de message pode mudar.