Core concepts
Test and live modes
One API host, two kinds of key. Test keys reach test restaurants; live keys reach real ones.
The API has one base URL, https://api.maple.inc/v1. The key you send sets the mode:
| Mode | Key | Reaches |
|---|---|---|
| Test | mpk_test_… |
Test restaurants you create in the developer console |
| Live | mpk_live_… |
Real restaurants that granted your app access |
A test key cannot reach a real restaurant, and a live key cannot reach a test restaurant. Test and live data never mix: a connection, webhook subscription or order in one mode does not exist in the other. See Test and live access for the errors.
Anyone can sign up at developers.maple.inc, create an organization and an app, and use test mode at once. Test restaurants take no real payments and reach no real people.
flowchart LR
subgraph API [api.maple.inc]
TK[mpk_test_ key] --> TD[(test restaurants)]
LK[mpk_live_ key] --> LD[(real restaurants)]
end
Test and live access
Access to a restaurant is a grant, and each grant belongs to one mode. A request on a restaurant’s route answers:
404when your app has no grant on that restaurant in the key’s mode. This includes a restaurant that only the other mode has a grant on: a test key does not see your live grants, and a live key does not see test ones.403with codewrong_environmentwhen your app does have a grant in the key’s mode, but the restaurant is the other kind: a test grant on a real restaurant, or a live grant on a test restaurant.
A list leaves out restaurants of the other kind.
Telling the modes apart in your code
Both modes share a host, so read the mode from the data:
GET /v1/mereturns the credential’senvironment(testorlive).- The order resource carries
livemode:truefor a real order,falsefor a test order. - Every webhook envelope carries a top-level
livemode:truefor a live event,falsefor a test event.
A test-first workflow
Build in test mode
Create a test restaurant in the console, then call
https://api.maple.inc/v1with yourmpk_test_…key. The console grants your app access to the restaurant for you. Subscribe a webhook and run the full order loop.Prove your webhook handler
POST /v1/webhook_subscriptions/{id}/testdelivers a signedwebhook.testevent so you can confirm signature verification and your2xxresponse before any real order exists.Go live
Ask Maple to review your app, then create a
mpk_live_…key and call the same host. See below.
Going live
In the console, open your app and choose Go live. It lists three checks:
- The listing has a name, tagline, description, support email, website, privacy policy and permissions.
- The app accepted a test order.
- A test webhook endpoint answered with a
2xxstatus.
Each check links to the page where you finish it. When all pass, choose Submit. Maple reviews the app. The page shows one of four states: Not requested, Waiting for review, Changes asked for (with Maple’s note) and Certified. You can withdraw a submission that is waiting.
A certified app can create live keys, limited to the permissions Maple certified. If you later want more permissions, submit the change; the app stays live while Maple reviews it.
A live key does not by itself reach any restaurant. Maple grants your app access to a real restaurant once its owner agrees. Register a live webhook endpoint and, for order integrations, connect the restaurant as its order receiver. Test grants, subscriptions and connections do not carry over.
Going-live checklist
- Your client’s base URL and key both belong to the mode you mean to use.
- Your webhook handler verifies the HMAC signature and rejects bad or stale signatures. See Webhooks.
- You dedupe deliveries on the envelope
id(delivery is at-least-once). - You respond
2xxquickly and do slower work asynchronously. - Decision calls are retried safely on transient errors (they’re replay-safe).
- You store the live signing secret (
mwhsec_…) securely — it’s shown only once.