REST API · v1

API Reference

The VebboPay API gives you programmatic access to accounts, payments, AI agents, subscriptions, invoices, cards, teams, and webhooks. Every endpoint is RESTful, returns JSON, and is secured with JWT bearer token authentication — or X-Api-Key for developer API key access to wallet routes.

RESTful JSONHMAC WebhooksEd25519 AgentsUK Faster PaymentsGBP-native

Quick Start

1. Get a JWT token

Call POST /api/v1/users/login with your email and password. The response contains an access_token.

Authorization Bearer eyJhbGci...

2. Use the token

Include your token in the Authorization header of every protected request. For developer API key access to wallet routes, use X-Api-Key instead.

Authorization: Bearer <jwt_token>
— or for developer API key routes —
X-Api-Key: <developer_key>

Make your first call

curl

curl -X GET \
  "https://api.vebbopay.com/api/v1/wallet/my-banking-details" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Authentication

JWT Bearer — most routes

Call POST /api/v1/users/login to obtain a token. Pass it as Authorization: Bearer <token> on all protected endpoints.

X-Api-Key — developer API key (wallet routes)

Create a developer API key in the Dev Portal. Pass it as X-Api-Key: <key> on /api/v1/wallet/* routes. JWT takes precedence if both are supplied.

X-API-Key — organisation API key (PAaaS routes)

Create an organisation key via POST /api/v1/organisations/{id}/api-keys. Pass it as X-API-Key: <key> on /api/v1/paas/* routes. Note the different capitalisation (X-API-Key vs X-Api-Key).

Accounts & Balances

Payments & Transfers

Products & Prices

Payment Links

Subscriptions

Direct Debits / VRP

Invoices

AI Agents

Teams

Cards

Audit & Reconciliation

Webhooks & Events

KYC / KYB

Document Inbox

PAaaS · Organisations

PAaaS · API Keys

PAaaS · Doc Ingestion

PAaaS · Payment Queue

PAaaS · Approvals

PAaaS · Reconciliation

PAaaS · Agent Triggers

PAaaS · Usage Metering

Error Codes

Code	Name	Description
400	Bad Request	The request body is malformed or missing required fields.
401	Unauthorized	No valid token provided, the token has expired, or an HMAC signature is invalid.
403	Forbidden	The token is valid but the API key lacks the required permission scope.
404	Not Found	The resource (account, agent, invoice, etc.) does not exist or does not belong to you.
409	Conflict	A duplicate resource was detected — e.g. duplicate nonce on an A2A transfer.
422	Unprocessable Entity	Semantic validation failed — e.g. insufficient balance, missing sort_code/account_number for GBP send, or CoP mismatch.
429	Too Many Requests	Rate limit exceeded. Check the Retry-After header before retrying.
500	Internal Server Error	Unexpected server error. Retry with exponential back-off.
503	Service Unavailable	A live Modulr operation was attempted without MODULR_API_KEY configured (strict mode).

Rate Limits

Limits are applied per API key or JWT. Exceeding a limit returns HTTP 429 with a Retry-After header.

Tier	Reads	Writes	Batch	Webhooks
Free	60 / min	20 / min	5 / hour	2 endpoints
Starter	300 / min	100 / min	50 / hour	10 endpoints
Pro	1,000 / min	300 / min	200 / hour	25 endpoints
Enterprise	Unlimited	Unlimited	Unlimited	Unlimited