Get started
Get an API key
An API key authenticates your server. It belongs to one environment and holds a fixed set of scopes.
On this page
Get a sandbox key#
Get a sandbox API key for your account. A sandbox key starts with mx_sandbox_. Choose its scopes when the key is created. For the quickstart, the key needs checkout:write and checkout:read.
Merxian shows the full key once, when it is created. Copy it at that time. Merxian cannot show it again.
Key format#
| Environment | Prefix | Example placeholder |
|---|---|---|
| Sandbox | mx_sandbox_ |
YOUR_SANDBOX_API_KEY |
| Live | mx_live_ |
YOUR_LIVE_API_KEY |
Treat everything after the prefix as an opaque secret. The prefix alone selects the environment. A key with the wrong prefix, or a key that is malformed, revoked, or unknown, gets 401 with the code AuthenticationRequired.
Scopes#
Each endpoint requires one scope. A key holds only the scopes that were chosen when it was created.
| Scope | Allows |
|---|---|
transactions:read |
List, retrieve, and preview transactions |
transactions:write |
Create, update, finalize, cancel, and adjust transactions |
payments:read |
Retrieve payments and refunds |
payments:create |
Create and retry payments |
payments:cancel |
Cancel payments |
payments:refund |
Refund payments |
checkout:read |
Retrieve and list checkout sessions and payment links |
checkout:write |
Create and expire checkout sessions, and manage payment links |
Scopes match exactly. A write scope does not include the read scope of the same resource. A key created without a choice of scopes holds only transactions:read. A request with a missing scope gets 403 with the code InsufficientScope. See Authentication.
Give each key only the scopes that its system needs. For example, a server that only creates checkout sessions needs checkout:write and checkout:read.
Store the key#
Keep the key in a secret store or an environment variable on your server. Read it at runtime.
export MERXIAN_API_KEY="YOUR_SANDBOX_API_KEY"Keys do not expire. Revoke a key when you no longer need it.