Checkout XPayHosted, iframe ou SDK

O Merchant cria uma CheckoutSession no seu backend. A XPayments devolve uma URL Hosted e uma URL Embedded, ambas ligadas à mesma Store, routing, GatewayVault, Transaction, ledger e webhooks.

Fluxo certificado

CheckoutSession → MB WAY → shared GatewayVault → signed webhook → Transaction succeeded → WalletMovement.

01 · Criar sessão

POST /api/v1/checkout/session

A chamada é server-side e usa a API Key da Store. O amount é enviado na menor unidade monetária.

Request

example

curl -X POST \
  https://api.xpayments.digital/api/v1/checkout/session \
  -H "Authorization: Bearer xp_test_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2510,
    "currency": "EUR",
    "reference": "ORDER-PT-2026-0184",
    "customerEmail": "joao@example.com",
    "returnUrl": "https://merchant.example/payments/result",
    "allowedOrigin": "https://merchant.example",
    "expiresInMinutes": 30,
    "metadata": {
      "customerName": "João Martins",
      "description": "Pedido #0184"
    }
  }'

201 Created

example

{
  "success": true,
  "data": {
    "sessionId": "3cb4c392-f084-4778-97cc-a733921c8c6c",
    "checkoutUrl": "https://checkout.xpayments.digital/pay/3cb4c392-f084-4778-97cc-a733921c8c6c",
    "embedUrl": "https://checkout.xpayments.digital/embed/3cb4c392-f084-4778-97cc-a733921c8c6c",
    "expiresAt": "2026-09-08T03:20:27.233Z"
  }
}

02 · Abrir checkout

Escolha Hosted ou Embedded

Hosted / Redirect

Redirecione o browser para o checkoutUrl. É a integração mais simples e a superfície Hosted está certificada E2E.

example

window.location.href = checkoutUrl;

Embedded / iframe

Use embedUrl ou o helper SDK. Configure allowedOrigin ao criar a sessão.

example

<iframe
  src="https://checkout.xpayments.digital/embed/3cb4c392-f084-4778-97cc-a733921c8c6c?parent_origin=https%3A%2F%2Fmerchant.example"
  title="XPayments Checkout"
  allow="payment *"
  referrerpolicy="strict-origin-when-cross-origin"
  style="width:100%;height:760px;border:0"
></iframe>

03 · SDK

Modal XPayments

O SDK atual expõe window.XPayments.open(). O callback de sucesso serve para UX; o backend do Merchant deve continuar a confirmar o pedido por webhook/Transaction.

example

<script src="https://checkout.xpayments.digital/xpay.js"></script>
<script>
  XPayments.open({
    sessionId: "3cb4c392-f084-4778-97cc-a733921c8c6c",
    theme: "light",
    closeOnBackdrop: true,
    onSuccess: function () {
      // UX only. Confirm the order on your backend/webhook.
      console.log("Checkout reported success");
    },
    onClose: function (reason) {
      console.log("Checkout closed", reason);
    }
  });
</script>

04 · Estado

Consultar CheckoutSession

A página Checkout acompanha o estado, mas o Merchant também pode consultar a sessão pelo backend.

example

GET https://api.xpayments.digital/api/v1/checkout/session/{sessionId}

example

{
  "success": true,
  "data": {
    "sessionId": "...",
    "storeName": "Merchant Display Name",
    "amount": 25.1,
    "currency": "EUR",
    "status": "succeeded",
    "transactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "paymentMethods": [
      { "code": "mb_way", "label": "MB WAY" },
      { "code": "card", "label": "Cartão" }
    ]
  }
}

05 · Confirmação

O browser não é a fonte financeira

Webhook Merchant

Método recomendado para atualizar o pedido no backend.

Transaction succeeded

Estado financeiro persistido pela XPayments.

API Key server-side

Nunca coloque xp_test_/xp_live_ no browser ou no bundle frontend.

Importante: retorno ao returnUrl, callback onSuccess, fecho do modal, requires_action ou redirect não substituem confirmação financeira no backend.

06 · Personalização

Branding vem da Store

O Checkout pode receber nome público, logo, cor principal, tema, locale e auto-return configurados na Store. O nome interno da Store não precisa ser exibido ao comprador.