RebornDocs

Clientes internacionais

Cartão internacional: UI e checkout de vocês, cobrança pela API Reborn. Sem PIX nem payment link.

Este guia é para quem processa cartão internacional com perfil internacional. A API aceita as moedas de presentment das contas habilitadas (Américas e/ou Europa) — USD, CAD, EUR, GBP e as demais da região. A autenticação é a mesma da API de seller: X-Api-Key gerada em Integrações. Base sandbox: https://sandbox-api.rebornpay.io. Sempre envie Idempotency-Key na criação da transação.

ModoQuando usarStatus
Direct APICheckout e UI de vocês. O servidor chama POST /v1/transactions; o 3DS completa no browser com o cliente Reborn.Disponível agora
Reborn Card FieldsCampos de cartão da Reborn no checkout de vocês (PCI) + 3DS no browser. Sem conta de adquirente e sem Card Vault.Disponível agora — payments.collect / payments.confirm

A integração internacional é HTTP na API Reborn + @rebornpay/elements no browser. O servidor cria a cobrança com sk_; o browser usa a publishable key Reborn (pk_) para montar os Card Fields e concluir o 3DS. Em Integrações, cadastre as origens do checkout próprio na publishable key — isso libera CORS. Não integre adquirente no client: os campos são da Reborn.

  • Checkout sessions, payment links, PIX
  • POST /v1/transactions/threeds/* e @rebornpay/checkout-3ds — 3DS do checkout Brasil
  • card.cardToken do tokenize Brasil — recusado no path internacional
  • transactions.runThreeDs no Elements — mesmo fluxo Brasil
  • Parcelas: installments deve ser 1

A API aceita PAN de teste em claro enquanto o Card Vault não estiver salvo. Em produção, use Card Fields — o PAN não deve passar pela sua API. Cartões: 4242424242424242 (sucesso), 4000002500003155 (3DS), 4000000000000002 (recusa). Envie currency no ISO da cobrança (ex. USD, EUR, JPY). Com as duas regiões ativas, moedas europeias vão para a conta Europa; o restante, para as Américas. A lista completa vem em allowedCurrencies do perfil internacional.

POST /v1/transactions — PAN de teste
{
  "paymentMethod": "CREDIT_CARD",
  "amount": 100,
  "currency": "USD",
  "description": "Pedido sandbox",
  "buyer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "card": {
    "number": "4242424242424242",
    "expirationMonth": "12",
    "expirationYear": "28",
    "cvv": "123",
    "holderName": "JANE DOE"
  }
}
cURL
curl -X POST "https://sandbox-api.rebornpay.io/v1/transactions" \
  -H "X-Api-Key: rk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @charge.json

Troque os inputs de cartão da UI de vocês pelos campos Reborn. O SDK monta número, validade e CVC; tokenize() devolve card.token para o POST /v1/transactions. O PAN não toca a API Reborn nem o DOM de vocês. Se o seller tiver Card Vault, o mesmo collect.mount usa o cofre automaticamente.

payments.collect.mount + tokenize
import { loadElements } from "@rebornpay/elements";

const reborn = await loadElements({
  publishableKey: "pk_test_...",
  apiBaseUrl: "https://sandbox-api.rebornpay.io",
});

const collect = await reborn.payments.collect.mount("#card-fields");
collect.on("change", (state) => {
  payButton.disabled = !state.complete;
});
const card = await collect.tokenize();

// No seu servidor, com sk_: POST /v1/transactions { card, currency, amount, ... }
// Sem Card Vault: envie o objeto retornado por tokenize() (card.token) — não use vault=CARD
// Com Card Vault: tokenize devolve vault:"CARD" + card.token / cvv
POST /v1/transactions — token dos Card Fields
{
  "paymentMethod": "CREDIT_CARD",
  "amount": 100,
  "currency": "USD",
  "description": "Pedido sandbox",
  "buyer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "card": {
    "token": "<token>",
    "lastDigits": "4242",
    "bin": "424242",
    "expirationMonth": "12",
    "expirationYear": "28",
    "holderName": "JANE DOE"
  },
  "returnUrl": "https://loja.example/pagamento/retorno"
}

Layout próprio: passem os containers de cada campo. O merchant estiliza borda, espaçamento e labels; o SDK preenche o interior.

slots number / expiry / cvc
const collect = await reborn.payments.collect.mount("#checkout", {
  currency: "USD",
  fields: {
    number: "#card-number",
    expiry: "#card-expiry",
    cvc: "#card-cvc",
  },
  showHolderName: false,
});
@rebornpay/elements-react
import { useRef } from "react";
import {
  ElementsProvider,
  CardFields,
  CardNumber,
  CardExpiry,
  CardCvc,
  type CardFieldsHandle,
} from "@rebornpay/elements-react";

export function InternationalCheckout() {
  const fieldsRef = useRef<CardFieldsHandle>(null);

  async function pay() {
    const card = await fieldsRef.current?.tokenize();
    const created = await fetch("/api/charge", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ card, amount: 100, currency: "USD" }),
    }).then((r) => r.json());

    // Se created.status === "PENDING", use reborn.payments.confirm no ElementsProvider
  }

  return (
    <ElementsProvider
      options={{ publishableKey: "pk_test_...", apiBaseUrl: "https://sandbox-api.rebornpay.io" }}
    >
      <CardFields ref={fieldsRef} currency="USD">
        <CardNumber />
        <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 12 }}>
          <CardExpiry />
          <CardCvc />
        </div>
        <button type="button" onClick={() => void pay()}>
          Pagar
        </button>
      </CardFields>
    </ElementsProvider>
  );
}

Os Card Fields carregam iframes hospedados fora do domínio de vocês. Se a página de checkout usa Content-Security-Policy, libere js.rebornpay.io e a API Reborn (sandbox-api.rebornpay.io / api.rebornpay.io) em script-src e connect-src. A publishable key Reborn (pk_test_ / pk_live_) é a que vocês passam em loadElements; o SDK busca a configuração dos campos em GET /v1/payments/config.

Se a resposta vier PENDING com pendingAction.clientSecret, complete o desafio no browser com reborn.payments.confirm. O SDK usa pendingAction.publishableKey (ou GET /v1/payments/config) — não cole chave de 3DS no frontend.

Confirm: POST /v1/transactions/{id}/3ds/confirm com a pk_ e clientSecret no body. Com sk_ o body é opcional.

payments.confirm após pendingAction
import { loadElements } from "@rebornpay/elements";

const reborn = await loadElements({
  publishableKey: "pk_test_...",
  apiBaseUrl: "https://sandbox-api.rebornpay.io",
});

// created = resposta de POST /v1/transactions no seu servidor (sk_)
// Envie returnUrl na cobrança. Se o banco pedir 3DS, redirecione o browser para pendingAction.url.
// Ao concluir (sucesso ou falha), a Reborn notifica o webhook do seller:
// TRANSACTION_PAID ou TRANSACTION_CANCELLED — veja /guides/webhooks.
if (created.status === "PENDING" && created.pendingAction?.url) {
  window.location.href = created.pendingAction.url;
}

if (created.status === "PENDING" && created.pendingAction?.clientSecret) {
  await reborn.payments.confirm({
    transactionId: created.id,
    clientSecret: created.pendingAction.clientSecret,
    publishableKey: created.pendingAction.publishableKey,
  });
}

Cadastre a URL no dashboard (ou via API de webhooks). Eventos deste fluxo: TRANSACTION_PAID (incluindo após o 3DS), TRANSACTION_CANCELLED (3DS concluído com falha/recusa) e TRANSACTION_REFUNDED. O payload traz o mesmo objeto da API pública, incluindo feeAmount e netAmount em centavos. Detalhes em Webhooks.

Estorno: POST /v1/transactions/{id}/refunds.

Se vocês já têm cofre próprio, o Collect usa o Card Vault no lugar dos Card Fields. A Reborn nunca vê PAN: o Collect tokeniza no browser; a API recebe aliases; o hop até a adquirência acontece no outbound do vault.

  1. Seller app → Integrações → Card Vault (visível só no perfil internacional).
  2. Host, usuário e senha do outbound (a senha nunca volta no GET).

Depois que o vault estiver conectado, PAN cru e o token dos Card Fields são recusados. Toda charge precisa de card.vault=CARD e aliases no token / cvv.

A rota outbound e o reveal dos campos são configurados com o time Reborn — não publique destino de adquirente em repositório ou frontend.

token e cvv são aliases do Collect — não dígitos do cartão. Envie lastDigits e bin (o Collect costuma expor) para dashboard e antifraude; a Reborn não infere last4 do alias.

POST /v1/transactions — Card Vault
{
  "paymentMethod": "CREDIT_CARD",
  "amount": 100,
  "currency": "USD",
  "description": "Pedido sandbox",
  "buyer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "card": {
    "vault": "CARD",
    "token": "tok_...",
    "cvv": "tok_...",
    "expirationMonth": "12",
    "expirationYear": "28",
    "holderName": "JANE DOE",
    "lastDigits": "4242",
    "bin": "424242"
  }
}

TesteEsperado
USD 4242 sem vaultPAID (ou PENDING → webhook TRANSACTION_PAID)
Card Fields tokenize + chargePAID; API sem PAN
EUR 3DSpendingAction → 3DS Reborn → confirm → PAID
RefundTRANSACTION_REFUNDED
Alias do Card VaultPAID; core sem PAN
PAN depois do vault salvo4xx pedindo vault=CARD