Integração simples
SDK oficial
Descarrega o ZIP, mapeia o checkout, chama createPayment. O SDK trata de X-VP-Trace, autenticação e serialização.
Não uses fetch/curl directo. Pedidos sem
X-VP-Trace devolvem 403 INTEGRATION_SIGNATURE_REQUIRED.Dois formatos de SDK
O caminho recomendado é o ZIP do backoffice (Node.js, PHP ou Cloudflare Workers) com createPayment(), triggerMbway(), etc. Para projectos TypeScript/npm no monorepo Xpend existe também @xpend/sdk com new Xpend(key).payments.create() e captureTrackingParameters(). Ambos geram X-VP-Trace automaticamente — não uses fetch directo.
1. Download
Backoffice → Integrações — Node.js, PHP ou Cloudflare Workers. O ZIP inclui cliente, webhook e .env pré-preenchido.
2. Variáveis de ambiente
XPEND_SECRET_KEY=vps_live_...
XPEND_WEBHOOK_SECRET=whsec_... ou vhsec_...
XPEND_INSTALL_ID=inst_...3. Um pagamento completo
require('dotenv').config()
const xpend = require('./xpend')
const customer = {
name: 'João Silva',
email: 'joao@email.com',
phone: '912345678',
address: 'Rua das Flores 12',
city: 'Lisboa',
postalCode: '1000-001',
country: 'Portugal',
}
const items = [
{ id: 'sku-1', name: 'Ténis Running', quantity: 1, priceInCents: 4990 },
]
// Captura fbclid/UTMs da URL do checkout (browser) ou repassa do teu funil
const trackingParameters = Object.fromEntries(
[...new URLSearchParams(window.location.search)].filter(([k]) =>
['utm_source','utm_medium','utm_campaign','utm_content','utm_term','fbclid','gclid','ttclid','src','sck'].includes(k)
)
)
const payment = await xpend.createPayment('ORDER-123', 49.90, customer, items, trackingParameters)
// MB WAY
await xpend.triggerMbway(payment.transactionId, '912345678')
// ou Multibanco
const mb = await xpend.generateMultibanco(payment.transactionId)
console.log(mb.entity, mb.reference, mb.expiresAt)Métodos
| Função | Descrição |
|---|---|
| createPayment(orderId, amount, customer, items, trackingParameters?) | Criar transacção com dados do checkout |
| triggerMbway(txId, phone) | MB WAY — telefone 9XXXXXXXX |
| generateMultibanco(txId) | Referência Multibanco |
| getStatus(txId) | Consultar estado na BD (fallback UX — preferir webhook) |
| verifyWebhook(rawBody, signature) | Verificar HMAC do webhook recebido |
Webhook (confirmação)
Quando o cliente paga, recebes payment.success assinado com X-Xpend-Signature. Ver /docs/webhooks.