Technical concepts
Authentication
Every API request carries a secret API key in the Authorization header. The key selects the environment and limits what the request can do.
Send the API key#
Send the key as a bearer token in the Authorization header of every request. The header value has at most 128 characters.
curl https://api.merxian.com/v1/transactions \
-H "Authorization: Bearer $MERXIAN_API_KEY"The API does not accept a key in the query string or in the body.
Key format#
A key has a prefix, then a secret. The prefix names the environment of the key:
| Prefix | Environment | Effect |
|---|---|---|
mx_sandbox_ |
Sandbox | Reaches only sandbox data. No real money moves. |
mx_live_ |
Live | Reaches only live data. Payments move real money. |
Sandbox and live use the same base URL, https://api.merxian.com. The key alone selects the environment. No header or parameter changes it. A sandbox key cannot read a live resource, and a live key cannot read a sandbox resource. See Accounts and environments.
Keys do not expire. A key stays valid until you revoke it.
Scopes#
Each key holds a set of scopes. Each endpoint requires one scope. A scope must match exactly: transactions:write does not include transactions:read. Give a key both when it must read and write.
When you create a key and choose no scopes, the key gets only transactions:read.
| Scope | Allows |
|---|---|
transactions:read |
List transactions, Retrieve a transaction, Preview a transaction |
transactions:write |
Create, update, finalize, and cancel a transaction, and add an adjustment |
payments:read |
Retrieve a payment, List the payments of a transaction, Retrieve a refund |
payments:create |
Create a payment, Retry a payment |
payments:cancel |
Cancel a payment |
payments:refund |
Refund a payment |
checkout:read |
Retrieve and list checkout sessions and payment links |
checkout:write |
Create and expire checkout sessions. Create, update, activate, and deactivate payment links |
Give each key only the scopes that its system needs. For example, a system that only creates checkout sessions needs checkout:write, and checkout:read if it reads them.
Keep keys safe#
- Store the key in an environment variable or a secret store. Read it at runtime, for example as
MERXIAN_API_KEY. - Do not commit a key to source control.
- Do not write a key to logs, error reports, or analytics.
- Use a different key for each system, so that you can revoke one without stopping the others.
- Roll a key on a schedule, and at once when a person with access leaves.
- Revoke a key at once if you think that it leaked.
- Keep sandbox keys and live keys in separate configuration.
Authentication errors#
| Status | Code | Cause |
|---|---|---|
401 |
AuthenticationRequired |
The key is missing, malformed, revoked, or unknown, or its prefix is not mx_sandbox_ or mx_live_. The response has the header WWW-Authenticate: Bearer. |
403 |
InsufficientScope |
The key does not hold the scope that the endpoint requires. The message names the scope. |
403 |
AccountSuspended, AccountClosed |
The account cannot collect payments. Payment endpoints return these codes. |
Do not retry a 401 or a 403 with the same key. Fix the key or its scopes first. See the error reference.