PIX S2S · CREATE VERIFIEDStores BRL habilitadas

PIX via XPayments S2S

Crie o PIX no backend, receba Copia e Cola + QR Code e deixe a XPayments tratar routing, provider e confirmação. O Merchant integra apenas com a API XPayments.

Auth

xp_live_* no backend. Nunca no browser.

Resposta

copyPaste, pixString e QR para apresentação.

Finalidade

pending não é pago. Aguarde succeeded/webhook.

Provider-neutral

Não exponha nem codifique credenciais do provider.

01 · Criar

POST /api/v1/payments/charge

O amount usa minor units: 500 = R$5,00. Use CPF/CNPJ sem formatação em customer.document e uma reference única para a tentativa lógica.

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"
    }
  }'

02 · Consumir a action

Não gere outro PIX para criar o QR

A resposta já contém o BR Code e representações gráficas. Guarde transactionId e reference, mostre action.copyPaste e renderize action.qrCodeBase64 ou um QR local a partir de action.copyPaste.

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://..."
  }
}

03 · Node.js

Implementação backend

example

const payload = {
  amount: 500, // R$ 5,00
  currency: "BRL",
  payment_method_types: ["pix"],
  reference: order.id,
  customer: {
    name: customer.name,
    document: customer.document.replace(/\D/g, ""),
  },
  metadata: {
    order_id: order.id,
    description: `Pedido ${order.id}`,
  },
};

const r = await fetch("https://api.xpayments.digital/api/v1/payments/charge", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XPAYMENTS_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

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

return {
  transactionId: payment.transactionId,
  status: payment.status,
  copyPaste: payment.action?.copyPaste,
  qrCode: payment.action?.qrCodeBase64,
};

04 · Webhook

Confirmação final

A entrega do produto/serviço deve ser acionada pelo estado financeiro final. O payload recebido deve ser verificado, deduplicado e processado de forma idempotente.

example

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

Quer que uma IA implemente isto no seu projeto?

Abra o guia de integração com IA, copie o prompt PIX e cole no ChatGPT, Claude, Gemini, Cursor, Z.AI ou outro agente que esteja a desenvolver o seu checkout.

Copiar prompt de integração PIX →