API Reference
Eight endpoints, all called from your backend with a key. Everything the customer does — reading the quote, accepting the plan, paying — happens on the ShotPay-hosted checkout page; your store hears about it through webhooks and the verify read.
Base URL
https://api.shotpay.com/api
Every path below is relative to that. There is one API for both modes — the key prefix decides which half of the account a request runs in, so there is no separate sandbox host to point at. See Sandbox.
Authentication
Two headers, both required, on every endpoint:
| Header | Value |
|---|---|
X-Client-Id |
mch_test_ or mch_live_ and 32 characters. Not a secret. |
X-Api-Key |
sk_test_ or sk_live_ and 32 characters. A server-side secret. |
There is one client id per mode, and the two headers must agree on which mode they belong to — a sandbox client id sent with a live key is refused. Full detail on API Keys.
The endpoints
| Endpoint | ||
|---|---|---|
GET |
/v1/ping | Confirm a key works |
GET |
/v1/config | Read the merchant's terms |
POST |
/v1/sessions | Open a checkout session |
GET |
/v1/checkout-sessions/{id} | Verify a session from your server |
GET |
/v1/contracts | List your agreements |
GET |
/v1/contracts/{reference} | Retrieve an agreement |
PATCH |
/v1/contracts/{reference} | Update its bookkeeping fields |
POST |
/v1/contracts/{reference}/cancel | Cancel an agreement |
The shapes these return are described once on Objects.
Conventions
Amounts are integer minor units (cents) — 49999 is $499.99. Requests take
a whole number of cents; a decimal is refused.
Timestamps are ISO 8601. Fields ending _date are dates rather than
timestamps.
Responses are wrapped: the body is always {"data": …} on success. Failures
carry a message, and sometimes reason or errors — see
Error Handling.
Rate limits are bounded per source and per key. A 429 carries a
Retry-After header in seconds.
Generating a client
The OpenAPI 3.1 spec behind these pages is published at
openapi/v1.yaml. It is the same document every ShotPay
plugin builds against, and it generates a client in any language
openapi-generator supports — see SDK.