XPayments

S2S Developer Docs

API v1 · S2S StableMB WAY E2E CertifiedPIX Create VerifiedSandbox + LiveUpdated 10 Sep 2026

API Server-to-Serverpara checkout próprio do Merchant

O backend do Merchant chama a XPayments diretamente. A API Key seleciona a Store, e a Store define moeda, routing, ambiente e GatewayVault. O Merchant apresenta no seu frontend apenas a action devolvida pela API.

Endpoint base

https://api.xpayments.digital/api/v1

Criar pagamento

POST /payments/charge

Auth

Bearer / x-api-key

01 · Quickstart

Primeiro pagamento

A API Key fica exclusivamente no backend do Merchant. Envie um método por request em payment_method_types; o runtime utiliza o primeiro item do array.

cURL

example

curl -X POST \
  https://api.xpayments.digital/api/v1/payments/charge \
  -H "Authorization: Bearer xp_test_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "EUR",
    "payment_method_types": ["mb_way"],
    "reference": "ORDER-2026-0001",
    "customer": {
      "name": "Cliente Exemplo",
      "phone": "+351912345678"
    },
    "metadata": {
      "order_id": "ORDER-2026-0001"
    }
  }'

Node.js

example

const response = await fetch(
  "https://api.xpayments.digital/api/v1/payments/charge",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.XPAYMENTS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 500,
      currency: "EUR",
      payment_method_types: ["mb_way"],
      reference: "ORDER-2026-0001",
      customer: {
        name: "Cliente Exemplo",
        phone: "+351912345678",
      },
      metadata: { order_id: "ORDER-2026-0001" },
    }),
  }
);

const payment = await response.json();
if (!response.ok) throw new Error(payment?.error?.code ?? "PAYMENT_ERROR");

// Uma action ou redirect não significa pagamento liquidado.
// Confirme o estado final por webhook / Transaction = succeeded.
console.log(payment);

02 · Contrato

Campos de criação

amount é sempre um integer na menor unidade monetária: 500 significa €5,00 em EUR ou R$5,00 em BRL. A reference deve identificar unicamente a tentativa lógica no sistema do Merchant.

Campo	Obrigatório	Descrição
amount	Sim	Integer positivo em minor units.
currency	Sim	ISO 4217, por exemplo EUR, PLN ou BRL.
payment_method_types	Sim	Um método habilitado para a Store.
reference	Recomendado	Referência única do pedido/tentativa.
customer	Depende	name, email, phone e document conforme o método.
metadata	Opcional	Dados do Merchant. Recomendado: order_id e description.

03 · Métodos

Matriz de integração

A disponibilidade final depende da Store e do provider configurado. Métodos que usam Stripe Payment Element pertencem à superfície Stripe-compatible, não exigem que o Merchant envie PAN/CVV à XPayments.

Método	Superfície recomendada	Estado	Action / nota
PIX	Native S2S	CREATE VERIFIED	BRL · copyPaste + QR · Store habilitada.
MB WAY	Native S2S / Checkout	CERTIFIED E2E	EUR · telefone PT · bank_app.
Multibanco	Native S2S / Checkout	STORE-DEPENDENT	Entidade/Referência quando habilitado.
Bizum	Native S2S / Checkout	STORE-DEPENDENT	EUR · fluxo bank app / redirect.
Card / Visa / Mastercard / Amex	Stripe-compatible + Elements / Checkout	STORE-DEPENDENT	Use pk_* pública + client_secret ou Checkout XPay.
BLIK	Native S2S / Checkout	STORE-DEPENDENT	PLN · exige capability Stripe da Store.
Bancontact / iDEAL / EPS / outros APM	Checkout / Stripe-compatible	STORE-DEPENDENT	Disponibilidade determinada pela conta/provider.

04 · PIX

PIX via API S2S

Para Stores BRL habilitadas, payment_method_types: ["pix"] cria uma cobrança PIX dinâmica. O retorno já contém os dados necessários para o Merchant renderizar o pagamento sem conhecer o provider subjacente.

Criar PIX · R$5,00

example

curl -X POST \
  https://api.xpayments.digital/api/v1/payments/charge \
  -H "x-api-key: xp_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "payment_method_types": ["pix"],
    "reference": "ORDER-BR-10001",
    "customer": {
      "name": "Nome do Cliente",
      "document": "12345678909"
    },
    "metadata": {
      "order_id": "ORDER-BR-10001",
      "description": "Pagamento do pedido 10001"
    }
  }'

Resposta

example

{
  "success": true,
  "transactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reference": "ORDER-BR-10001",
  "status": "pending",
  "method": "pix",
  "action": {
    "type": "pix",
    "copyPaste": "000201...",
    "pixString": "000201...",
    "qrCode": "data:image/png;base64,...",
    "qrCodeBase64": "data:image/png;base64,...",
    "qrCodeUrl": "https://..."
  }
}

Apresentação

Use action.copyPaste ou action.qrCodeBase64. Não derive um novo pagamento para gerar QR.

Finalidade

pending significa apenas PIX criado. Entregue o produto somente após confirmação final XPayments.

Confirmação

A XPayments valida o estado do provider server-to-server antes do ledger e envia o webhook Merchant configurado.

Abrir guia PIX completo →

05 · Cartões

Cartões: use Stripe-compatible + Elements ou Checkout

A API Native S2S não deve receber PAN/CVV. Para um checkout próprio com cartões, crie o PaymentIntent pelo relay Stripe-compatible e confirme no browser com Stripe.js/Payment Element usando a publishable key pk_* da Store.

Stripe-compatible

Ideal para projetos que já usam Stripe Payment Intents/Elements. A server key passa a ser xp_test_* / xp_live_*; a pk_* permanece browser-safe.

Abrir Stripe-compatible →

Nunca envie PAN bruto

Não envie número de cartão, CVV ou dados PCI sensíveis no JSON de /payments/charge. Use Stripe.js/Elements ou Checkout XPay.

Abrir Checkout →

06 · Estados

Como interpretar a resposta

A resposta inicial descreve o estado daquele instante. O estado financeiro definitivo vem da Transaction XPayments/webhook.

Exemplo MB WAY

example

{
  "success": true,
  "transactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reference": "ORDER-2026-0001",
  "providerId": "pi_...",
  "status": "requires_action",
  "method": "mb_way",
  "action": {
    "type": "bank_app",
    "message": "Pedido MB WAY enviado. Confirme na aplicação."
  }
}

pending: cobrança criada; pagamento ainda não confirmado.
requires_action: cliente precisa aprovar/autenticar.
processing: aceite pelo fluxo, ainda sem estado final.
succeeded: pagamento confirmado no core.
failed / canceled: não creditar o pedido.

07 · Webhooks

Confirmação financeira definitiva

O webhook Merchant é a fonte assíncrona recomendada para atualizar o pedido. Responda 2xx rapidamente, valide a assinatura da Store e processe idempotentemente.

Payload normalizado

example

{
  "event": "payment_intent.succeeded",
  "transaction_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reference": "ORDER-2026-0001",
  "amount": 5,
  "currency": "EUR",
  "status": "succeeded",
  "method": "mb_way",
  "timestamp": "2026-09-10T04:00:00.000Z"
}

Regras

• deduplique por evento + transaction_id;
• não dependa do browser/redirect;
• trate retries como normais;
• mantenha HTTPS;
• nunca exponha webhook secrets no frontend.

08 · Segurança

Regras obrigatórias

As credenciais xp_* são server-side. As pk_* Stripe são públicas e só são necessárias para Stripe.js/Elements.

API Key por Store

Separe xp_test_ e xp_live_. Nunca exponha xp_* no browser.

TLS obrigatório

HTTPS em chamadas, callbacks e webhooks.

Idempotência

Reutilize a mesma reference em retries da mesma tentativa lógica.

Store-scoped

Moeda, providers e métodos dependem da Store identificada pela API Key.

Copiar instruções prontas para uma IA implementar →