Send a secret key as a bearer token on every request:
curl https://api.ordercard.io/v1/payment_methods \
-H "Authorization: Bearer oc_sk_test_4Fq9…"Keys belong to your team, not to a person, so they keep working when someone leaves. Create them in the dashboard under Developers → API keys. The full value is shown once; afterwards OrderCard shows its prefix and last four characters, like oc_sk_test_4Fq9…9fQ2, which is enough to match a key you find in a config file.
Key types
| Key | Looks like | Used for |
|---|---|---|
| Secret | oc_sk_test_…, oc_sk_live_… |
Your server. Calls this API with the permissions you chose. Keep it out of web pages and mobile apps. |
| Publishable | oc_pk_test_…, oc_pk_live_… |
The browser. Loads hosted fields on the websites you listed, and nothing else. |
A publishable key sent to this API is refused with 401.
Environments
Every key belongs to one environment, and so does everything it creates. A sandbox key only sees sandbox cards, gateways and transactions; a live key only sees live ones. There is no environment parameter: switching environments means switching keys.
- Sandbox is free. Use the test cards and the built-in test gateway, or your gateway’s own sandbox account.
- Live charges real cards. It needs an active OrderCard plan; until then live requests answer
402with the codesubscription_required. Owners and admins choose a plan in the dashboard under Team → Billing.
Permissions
A secret key carries a set of permissions. A request that needs a permission the key lacks answers 403 forbidden.
| Permission | Allows |
|---|---|
payment_methods:read |
Reading vaulted cards. |
payment_methods:write |
Updating cards’ details and retaining tokens. |
payment_methods:redact |
Destroying card numbers. |
payment_methods:pan |
Sending raw card numbers from your server (vault a card). Only owners and admins can grant it. |
transactions:read |
Reading transactions. |
transactions:write |
Charging, authorizing, verifying, capturing, voiding and refunding, and surcharge quotes. |
gateways:read / gateways:write |
Reading or managing gateways. |
webhooks:read / webhooks:write |
Reading or managing webhook endpoints. |
When you create a key you can pick a preset: Full access (everything except payment_methods:pan), Read only, Charge only (payment_methods:read and both transaction permissions) or Server-side tokenization. A key can never get a permission its creator does not have.
Unused keys
A secret key that makes no request for 30 days is turned off, so a key nobody uses cannot be misused. A week before, everyone on your team who manages API keys gets an email and a dashboard notification naming the key and the date; any request with the key before then starts its 30 days again. Once it is off, requests with it answer 401 until someone turns it back on under Developers → API keys, which gives it another 30 days. Publishable keys are never turned off for going unused.
Failures
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated |
No key, an unknown key, a revoked, expired or turned-off key, or a publishable key. |
| 402 | subscription_required |
A live key on a team without an active plan. |
| 403 | forbidden |
The key lacks the permission this endpoint needs. |