Referência da API

Endpoints, parâmetros, respostas e códigos de erro.

Base URL

https://vorkpay.com/api/v1

Autenticação

Todas as chamadas requerem o header Authorization com a tua chave secreta.

Authorization: Bearer vps_live_...

A chave secreta é visível em /dashboard/settings/api-keys. Nunca a uses em código frontend.

Códigos de erro

Código	Significado
`400`	Body inválido ou parâmetros em falta
`401`	Header `Authorization` em falta ou chave inválida
`403`	Conta não está activa (pendente, suspensa ou recusada)
`404`	Recurso não encontrado (ex: `transactionId` inexistente)
`429`	Rate limit excedido
`500`	Erro interno do VorkPay
`502`	Erro a comunicar com a rede bancária

Formato dos erros:

{
  "error": "phoneNumber must be a Portuguese 9-digit mobile (9XXXXXXXX)"
}

Rate limits

A API /api/v1/* tem rate-limit de 30 pedidos por minuto por IP. Acima deste limite recebes 429 Too Many Requests com o headerRetry-After em segundos. Faz backoff exponencial e tenta de novo.

POST /payments/init

Cria uma transacção pending. Devolve um transactionId para usar nos passos seguintes.

Request body

Parâmetro	Tipo	Obrigatório	Descrição
`orderId`	string	Sim	O teu identificador interno do pedido
`amount`	number	Sim	Valor em EUR (positivo)
`currency`	string	Não	Default `EUR` (única suportada)

Response

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

POST /payments/mbway

Dispara uma notificação push MB WAY para o cliente.

Request body

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	ID devolvido por `/init`
`phoneNumber`	string	Sim	9 dígitos, formato `9XXXXXXXX`

Response

{
  "success": true,
  "message": "Notificação enviada. O cliente tem 4 minutos para confirmar."
}

POST /payments/multibanco

Gera uma referência multibanco (entidade + referência).

Request body

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	ID devolvido por `/init`

Response

{
  "entity": "24000",
  "reference": "123456789",
  "amount": 49.90,
  "expiresAt": "2026-05-13T14:32:00Z"
}

GET /payments/status

Consulta o estado actual de uma transacção.

Query params

Parâmetro	Tipo	Obrigatório
`transactionId`	string	Sim

Response — MB WAY pago

{
  "transactionId": "txn_abc123",
  "externalOrderId": "ORDER-123",
  "status": "paid",
  "paymentMethod": "MBWAY",
  "amount": 49.90,
  "currency": "EUR",
  "paidAt": "2026-05-10T14:32:00Z"
}

Response — Multibanco pendente (com referência)

{
  "transactionId": "txn_abc123",
  "externalOrderId": "ORDER-123",
  "status": "pending",
  "paymentMethod": "REFERENCE",
  "amount": 49.90,
  "currency": "EUR",
  "paidAt": null,
  "mb": {
    "entity": "24000",
    "reference": "123456789",
    "expiresAt": "2026-05-13T14:32:00Z"
  }
}

O objecto mb só está presente quando paymentMethod = "REFERENCE" e a referência já foi gerada.

Estados possíveis: pending · paid · failed · cancelled