API 02

Checkout XPay

Crie uma única CheckoutSession e escolha como apresentar o pagamento: numa página externa XPayments ou num modal/iframe sobre a página do Merchant. Redirect e Embedded usam a mesma Store, routing, GatewayVault, Transaction, ledger e webhooks.

Store ativa

Use uma Store ORCHESTRATED com provider e métodos de pagamento configurados.

API Key

Use xp_test_ ou xp_live_ da Store com scope payments_write. A chave fica sempre no servidor.

Webhook

Configure Merchant Delivery para receber o estado financeiro definitivo no seu backend.

Branding

Defina nome público, logo, cor e tema do Checkout sem alterar o nome interno da Store.

A. Redirect Checkout

Redirecione para checkout.xpayments.digital/pay/:sessionId. Depois de succeeded, o Checkout apresenta confirmação e retorna automaticamente ao returnUrl do Merchant.

B. Embedded / iframe

O SDK abre a mesma sessão num modal seguro. Quando a sessão chega a succeeded, o iframe emite XPAYMENTS_STATUS: SUCCESS, fecha o modal e executa onSuccess.

1. Criar a CheckoutSession

Esta chamada é sempre server-to-server. Nunca coloque xp_live_ ou xp_test_ no JavaScript público do browser, numa app mobile ou num repositório público.

curl -X POST https://api.xpayments.digital/api/v1/checkout/session \
  -H "Authorization: Bearer xp_test_********************************" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "EUR",
    "reference": "ORDER-2026-1001",
    "customerEmail": "cliente@example.com",
    "returnUrl": "https://merchant.example/order/1001",
    "allowedOrigin": "https://merchant.example",
    "expiresInMinutes": 30,
    "metadata": {
      "customerName": "João Martins",
      "description": "Order #1001"
    }
  }'

Campo	Tipo	Uso	Descrição
amount	integer	Sim	Valor na menor unidade monetária. Ex.: 1500 EUR = €15,00.
currency	string	Sim	Moeda ISO 4217 com 3 letras, por exemplo EUR, GBP ou PLN.
reference	string	Recomendado	Referência única e namespaced do pedido. Evite reutilizar referências.
customerEmail	string	Não	Email inicial do comprador, quando disponível.
returnUrl	HTTPS URL	Recomendado	Destino do Merchant após sucesso no modo Redirect.
allowedOrigin	HTTPS URL	Embedded	Origem esperada do Merchant para integração Embedded.
expiresInMinutes	integer	Não	Validade da sessão entre 5 e 1440 minutos. Default atual: 30.
metadata	object	Não	Dados públicos controlados, como customerName e description.

2. Resposta da sessão

{
  "success": true,
  "data": {
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "checkoutUrl": "https://checkout.xpayments.digital/pay/xxxxxxxx-...",
    "embedUrl": "https://checkout.xpayments.digital/embed/xxxxxxxx-...",
    "expiresAt": "2026-09-05T18:30:00.000Z"
  }
}

checkoutUrl é usado no fluxo Redirect. embedUrl representa a sessão embedded; para integração normal recomendamos o SDK xpay.js, que cria e fecha o modal por si.

Redirect URL

Use o checkoutUrl devolvido pela API.

window.location.href = checkoutUrl;

O retorno ao Merchant só ocorre depois de o Checkout observar estado financeiro confirmado.

Embedded SDK

O Merchant não precisa construir ou gerir o iframe manualmente.

<script src="https://checkout.xpayments.digital/xpay.js"></script>
<script>
  XPayments.open({
    sessionId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    theme: "light",
    closeOnBackdrop: true,
    onSuccess: () => {
      // Recarregue o pedido no seu backend antes de mostrar "Pago".
      window.location.reload();
    },
    onClose: (reason) => {
      console.log("Checkout closed", reason);
    }
  });
</script>

sessionId

Obrigatório

UUID da CheckoutSession criada no servidor.

theme

Opcional

light ou dark. O branding da Store continua autoritativo para identidade.

onSuccess

Callback

Executado quando o iframe comunica SUCCESS e o modal é fechado.

onClose

Callback

Recebe CLOSED, CANCELLED ou outro motivo de fecho não sucedido.

3. Métodos de pagamento

O Checkout apresenta métodos rápidos configurados no routing da Store e um modo Stripe dinâmico. O provider continua a decidir quais métodos são elegíveis para aquele pagamento.

card

Cartões

mb_way

MB WAY

bizum

Bizum

multibanco

Multibanco

stripe_all

Mais opções

Mais opções utiliza Stripe Payment Element com métodos dinâmicos. Stripe filtra e ordena métodos elegíveis com base em moeda, dispositivo, disponibilidade e configuração do provider. Não existe um segundo motor financeiro: a Transaction continua no core XPayments.

Branding por Store

Em Stores → Gerenciar → Checkout Experience, configure nome público, logo HTTPS, cor principal, tema e retorno automático. O nome interno da Store e o Store Code permanecem operacionais e não são mostrados como identidade comercial quando existe nome público.

Localização e moeda

O runtime atual adapta idioma, formatação e prioridade dos métodos através do locale e timezone do browser. Portugal prioriza MB WAY/Multibanco; Espanha prioriza Bizum; outros mercados priorizam Card/Stripe Dynamic.

A moeda financeira não é alterada silenciosamente por localização. currency da CheckoutSession é definida pelo Merchant/Store e permanece autoritativa. Isto evita conversões implícitas e divergência contabilística.

4. Estados da CheckoutSession

Redirect, requires_action, regresso do browser ou fecho de iframe não significam sucesso. XPayments reconcilia CheckoutSession e Transaction com o estado do provider. Enquanto o provider ainda está em ação/processamento, a sessão permanece pending; o estado final positivo é succeeded.

status	Significado
pending	Sessão criada ou pagamento ainda não confirmado. Inclui fluxos provider em requires_action/processing enquanto não existe estado final.
succeeded	Pagamento financeiramente confirmado. Estado final de sucesso.
failed	Pagamento recusado, cancelado ou não concluído.
expired	CheckoutSession ultrapassou a validade configurada.

GET /api/v1/checkout/session/{sessionId}

{
  "success": true,
  "data": {
    "status": "succeeded",
    "amount": 15,
    "currency": "EUR",
    "transactionId": "..."
  }
}

Webhook é a confirmação do Merchant

O Checkout melhora UX e acompanha o estado, mas o backend do Merchant deve atualizar o pedido a partir do Merchant Delivery assinado. Não use redirect ou callback do browser como fonte única de verdade.

Configurar webhooks

API Keys e ambientes

Cada sessão é criada com uma API Key da Store. Mantenha Test e Live separados e nunca exponha a chave ao browser.

Gerir API Keys

5. Erros a tratar

HTTP	code / situação	Ação
401	API Key inválida / Store inativa	A sessão não é criada.
403	INSUFFICIENT_SCOPE	A API Key não possui payments_write.
400	CHECKOUT_METHOD_NOT_AVAILABLE	O método pedido não está disponível na Store.
409	CHECKOUT_ALREADY_PAID	A sessão já está associada a pagamento succeeded.
410	CHECKOUT_EXPIRED	A sessão expirou.
400	LIVE_KEY_TEST_GATEWAY_MISMATCH	API Key Live ligada a provider Test.
400	TEST_KEY_LIVE_GATEWAY_MISMATCH	API Key Test ligada a provider Live.

6. Checklist de produção

API Key server-side

Nunca exponha xp_live_ ou xp_test_ no browser, HTML, app móvel ou frontend compilado.

Criação server-to-server

Crie CheckoutSession a partir do backend do Merchant e entregue apenas sessionId/checkoutUrl ao browser.

Webhook validado

Valide HMAC, deduplique eventos e responda HTTP 2xx rapidamente.

Store correta

Confirme moeda, ambiente, provider e métodos da Store antes de usar xp_live_.

Expiração

Defina uma validade compatível com o fluxo e trate CHECKOUT_EXPIRED no Merchant.

Sucesso confirmado

Só marque o pedido como pago quando o estado financeiro for succeeded.

Sandbox

Use Store Sandbox + xp_test_. Para MB WAY, Multibanco e outros métodos com simuladores, utilize apenas valores de teste no ambiente Test. Em Live use dados reais e nunca misture API Key Test com Gateway Live.

Ver dados de Sandbox