Developers / Guides / Start here
Keys, environments and headers
Every request carries a key. There are two kinds, two environments, and one extra header for calls that act for a particular merchant.
Two kinds of key
Provider key
Acts for every merchant account under your provider. It is the key for your own integration: it creates merchants, sets their credentials and can issue a merchant's own key.
Merchant key
Scoped to one merchant's data. Use it when a merchant integrates directly. It cannot create merchants, list them, or issue or revoke keys: those return 403.
Send the key in an X-Api-Key header on every request. The only call that does not use it is the address gateways send webhooks to (see Gateway webhooks). Keys are shown once, when they are issued; PayMidWare never displays one again, so store it somewhere secure straight away. Treat keys like passwords: keep them on your server, never in browser or mobile code, and never in source control.
Merchant keys
| Endpoint | Purpose |
|---|---|
| POST /api/merchant-accounts/{ref}/api-key | Issue a key for that merchant and return it once. Calling it again replaces the key, which is how you rotate it. |
| DELETE /api/merchant-accounts/{ref}/api-key | Revoke the merchant's key. Your provider key keeps working for that merchant either way. |
A merchant's key can also be issued from the merchant's own account page in the Portal. Issuing a key for a merchant is optional: your provider key already works for every merchant you own.
The merchant header
Payment calls under /api/payments need to know which merchant's gateway credentials to use. With a provider key, send your own reference for the merchant in an X-Merchant-Reference header. With a merchant key the header is optional, because the key already names the merchant; if you send one that names a different merchant, the request is rejected with 400. Calls under /api/merchant-accounts/{ref}/... take the reference in the address instead.
Sandbox and production
PayMidWare runs a sandbox for building and testing and a production service for real money. Each only accepts and issues its own keys: sandbox keys start with pmw_test_ and production keys with pmw_live_. Every response carries an X-PayMidWare-Environment header saying which service answered, a quick way to confirm you are not about to test against production. Treat them as separate systems: merchants, credentials and keys you create in one are set up again in the other, and sandbox merchants only accept the gateways' own sandbox credentials.
Responses and errors
Requests and responses are JSON over HTTPS. A failure carries a JSON body with an error message and one of these status codes.
| Status | Meaning |
|---|---|
| 400 | The request is not valid: a missing or malformed field, or a value the account cannot use. |
| 401 | No key, or a key that is not valid for this environment. |
| 403 | The key is valid but not allowed to do this, for example a merchant key on a provider-only call. |
| 404 | No such record for this account. A merchant key asking for a sibling merchant gets the same answer as a reference that does not exist. |
| 409 | A conflict, such as a reference or account number that already exists. |
| 429 | Too many requests where a limit applies (short links, for one). Wait for the Retry-After seconds. |
Each authenticated request that names a merchant counts as one API request for that merchant's plan. See Plans, billing and usage.