XPayments — API Merchant S2S

API v1 S2S Stable

Contrato de integração Server-to-Server para o backend do Merchant. Endpoint base: https://api.xpayments.digital/api/v1.

Segurança: a API Key pertence à Store e nunca deve ser exposta no browser, aplicação mobile ou código público.

Autenticação

Authorization: Bearer xp_live_********************************

Compatibilidade: x-api-key: xp_live_********************************. O scope necessário para criação de pagamentos é payments_write.

Criar pagamento

POST /payments/charge
Content-Type: application/json

amount é enviado na menor unidade monetária: 1500 EUR = EUR 15,00.

MB WAY

{
  "amount": 1500,
  "currency": "EUR",
  "payment_method_types": ["mb_way"],
  "reference": "ORDER-PT-2026-0184",
  "customer": {"name":"João Martins","phone":"+351912345678"}
}

Resposta típica: status=requires_action, action.type=bank_app. O cliente confirma na aplicação MB WAY.

Bizum

{
  "amount": 2500,
  "currency": "EUR",
  "payment_method_types": ["bizum"],
  "reference": "ORDER-ES-2026-0331",
  "customer": {"name":"María García","phone":"+34612345678"}
}

Requer telefone espanhol. O runtime aceita valores entre EUR 0,50 e EUR 5.000,00.

Multibanco

{
  "amount": 3450,
  "currency": "EUR",
  "payment_method_types": ["multibanco"],
  "reference": "ORDER-PT-2026-0185",
  "customer": {"email":"cliente@example.com"}
}

Quando requer ação, a resposta contém action.entidade, action.referencia e action.montante. Apresente estes dados ao cliente.

Bancontact

{
  "amount": 4200,
  "currency": "EUR",
  "payment_method_types": ["bancontact"],
  "reference": "ORDER-BE-2026-0078",
  "metadata": {"return_url":"https://merchant.example/payment/result"},
  "customer": {"name":"Pieter Janssen","email":"cliente@example.com"}
}

customer.name e metadata.return_url HTTPS são obrigatórios. Redirecione o browser para action.url, sem iframe.

BLIK

{
  "amount": 4200,
  "currency": "PLN",
  "payment_method_types": ["blik"],
  "reference": "ORDER-PL-2026-0447",
  "payment_method_options": {"blik":{"code":"123456"}},
  "customer": {"name":"Jan Kowalski","email":"cliente@example.com"}
}

O código tem seis dígitos, deve ser enviado imediatamente e nunca deve ser persistido ou registado. A resposta de confirmação por aplicação utiliza expiresInSeconds: 60.

Webhook Merchant

Eventos suportados:

payment_intent.succeeded
payment_intent.payment_failed
payment_intent.processing
payment_intent.canceled

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

No webhook, amount está na unidade monetária principal. Quando configurado um secret da Store, valide x-nexflowx-signature com HMAC-SHA256 sobre o corpo JSON bruto.

Regra de negócio: redirects, push notifications e requires_action não confirmam pagamento. Considere pago apenas após payment_intent.succeeded.

Sandbox

Os simuladores devem ser usados apenas com Stores Test/Sandbox.

MB WAY

`+351 911 111 112`	sucesso
`+351 911 111 113`	método indisponível
`+351 911 111 114`	recusa do provedor
`+351 911 111 115`	tentativa expirada
`+351 911 111 116`	recusa do cliente

Bizum — Sandbox XPayments validado anteriormente

`+34 600 000 001`	sucesso
`+34 600 000 002`	falha

Multibanco

`succeed_immediately@example.com`	sucesso rápido
`expire_immediately@example.com`	expira imediatamente
`expire_with_delay@example.com`	expira após atraso
`fill_never@example.com`	permanece sem pagamento

Documento técnico XPayments. A disponibilidade final dos métodos depende da Store e do ambiente.