API Reference Overview
Base URL, response envelope, conventions and the full resource list.
The Wajub API is a REST API: one base URL, JSON bodies, standard HTTP status codes, and a
single Authorization header carrying your API key. There is no separate sandbox host and no
version segment in the path.
Built-in playground
Set your API keys in the top bar, then use Test this endpoint on any resource page to send a real request from the documentation.
Base URL
Every request goes to the same host, over HTTPS:
https://api.wajub.comThe environment is decided by the prefix of the key you send, not by the URL. A key starting
with sk_test., pk_test. or rk_test. reads and writes the sandbox database; a key starting
with sk., pk. or rk. reads and writes live data. Same host, same paths, same payloads.
Your first call
GET / costs nothing, touches no resource, and answers the two questions worth asking first: is
this key valid, and which environment does it open.
curl https://api.wajub.com/ \
-H "Authorization: $WAJUB_API_KEY"The response names your team and the environment the key belongs to:
Response envelope
Every response carries the same three fields, then the payload.
statusstringoptionalOK, Created, Not Found, Unprocessable Content.codeintegeroptionalmessagestringoptionalA single resource is returned under a key named after it. A payment comes back under
transaction, not payment, because the underlying record is a transaction:
Lists return an items array and a meta object:
Here is the key to read for each resource. GET /events is the one list that does not use
items:
| Resource | Single | List |
|---|---|---|
| Payments | transaction | items |
| Refunds | refund | items |
| Transfers | transfer | items |
| Customers | customer | items |
| Beneficiaries | beneficiary | items |
| Payment links | link | items |
| Invoices | invoice | items |
| Accounts | account | items |
| Webhook endpoints | endpoint | items |
| Events | event | events |
| Balance | balance | n/a |
Every response carries a request ID
X-Request-Id is returned on every response, success or failure. Log it, and quote it to support
when something goes wrong. You can also send your own (up to 64 characters) and Wajub will echo it
back rather than generate one, which makes your logs and ours line up.
X-Request-Id: 9f1c0f2a-3f5e-4f1b-9a1e-2c8d6b0e7a41
X-Wajub-Version: 2026-09-01
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117Conventions
| Topic | What it covers |
|---|---|
| Authentication | Public, private and restricted keys, scopes, IP rules |
| Errors | Status codes and the errors object |
| Failure Reasons | failure_reason on failed payments, transfers, refunds |
| Pagination | per_page, page and cursor |
| Rate limits | The five limiters and the X-RateLimit-* headers |
| Idempotency | Replaying a creation without charging twice |
| Versioning | Date-based versions and what has changed |
Resources
| Resource | Key endpoints |
|---|---|
| Payments | POST /payments, GET /payments/{id} |
| Providers | GET /providers |
| Refunds | POST /refunds, GET /refunds/{id} |
| Transfers | POST /transfers, GET /transfers/{id} |
| Customers | POST /customers, GET /customers/{id} |
| Subaccounts | POST /accounts |
| Balance | GET /balance |
| Events | GET /events, POST /events/{id}/resend |
| Beneficiaries | POST /beneficiaries |
| Webhook Endpoints | POST /webhooks |
| Payment Links | POST /links |
| Invoices | POST /invoices |
| Disputes | GET /disputes |
Three add-ons sit outside the core resources and are documented separately: Identity, Tax and Shield.
Try it now
GET /balance needs a private key, so it is also a good check that your server-side key works: