Xpend
Começar grátis
ComeçarPagamentosIntegraçõesReferência APIChangelog
Começar

Quickstart

Do registo ao primeiro pagamento em 6 passos. Integração server-side: os dados do cliente são recolhidos no teu site e enviados a partir do teu servidor (com o SDK ou por REST directo).

ⓘ

Autenticação por chave (Authorization: Bearer). A API só aceita pagamentos de domínios registados — envia o storeUrl e adiciona o domínio em Definições → Domínios. Preferes que a IA faça tudo? Vê Integrar com IA.

1. Cria conta e obtém as chaves

Regista-te em /auth/register. Depois, em Backoffice → API Keys, tens a chave pública, a secret key (só backend) e o webhook secret. A autenticação é por chave: Authorization: Bearer <secret>.

2. Regista o domínio da tua loja

Em Backoffice → Definições → Domínios, adiciona o domínio da loja (ex.: aminhaloja.pt). A API só aceita pagamentos de domínios registados — envias o storeUrl em cada pagamento e, se o domínio não constar na lista, a resposta é 403 DOMAIN_NOT_ALLOWED. Remover um domínio corta o acesso de imediato.

3. Integra (SDK ou REST)

Em Backoffice → Integrações tens ZIPs prontos (Node.js, PHP, Cloudflare Workers) — cada um traz o cliente da API, o handler de webhook e um .env com as tuas chaves. Preenche o XPEND_STORE_URL com o URL da loja. Não é obrigatório usar o SDK: podes chamar a REST directamente com a chave Bearer.

# extrai o ZIP para o teu projeto e instala as dependências
npm install dotenv

4. Cria uma transacção

Cria sempre primeiro uma transacção pending. Devolve um transactionId.

const xpend = require('./xpend')

const payment = await xpend.createPayment('ORDER-123', 49.90, {
  name: 'João Silva',
  email: 'joao@email.com',
  phone: '912345678',
  address: 'Rua das Flores 12',
  city: 'Lisboa',
  postalCode: '1000-001',
  country: 'Portugal',
}, [
  { id: 'sku-1', name: 'Ténis Running', quantity: 1, priceInCents: 4990 },
])
console.log(payment.transactionId) // → "txn_42"

Resposta:

{ "transactionId": "txn_42", "amount": 49.90, "currency": "EUR" }

5. Cobra o cliente

MB WAY — notificação push, 4 minutos para confirmar.

await xpend.triggerMbway(payment.transactionId, '912345678')
// O cliente recebe uma notificação MB WAY no telemóvel (4 min para confirmar).

Multibanco — referência (entidade + referência) válida 3 dias.

const mb = await xpend.generateMultibanco(payment.transactionId)
console.log(mb.entity, mb.reference) // entrega ao cliente: entidade + referência + valor
{ "entity": "24000", "reference": "123456789", "amount": 49.90, "expiresAt": "2026-05-13T14:32:00Z" }

6. Recebe a confirmação

Quando o cliente paga, a Xpend envia um webhook assinado para o URL que configurares em Backoffice → Webhook. É esta a confirmação oficial — vê a documentação de webhooks.

Próximos passos