Payments HTTP API
The endpoints your site calls to check that payments are ready and to create a payment link, with every error they return.
On this page
Payments are open on a few sites while we test them, and these endpoints only answer for those sites. To ask for access, use the support chat.
Your site's payments are a small REST API with three endpoints. GET /status reports whether the site can take payments right now, POST /checkout creates a payment link that sends the visitor to Stripe to pay, and POST /get-checkout reads a payment link back to see whether it was paid. See Payments for the tab, the accounts and the list of payments.
The helper your site's code imports, @/lib/modulify/payments, makes exactly these calls, and chat can write it for you. Keep the key on a server, never in a browser or an app.
Authentication
Send the key as an X-Payments-Key header on every request. The base URL is the value of MODULIFY_PAYMENTS_URL, such as https://api.modulify.ai/site-payments, and every path below goes after it.
curl "$MODULIFY_PAYMENTS_URL/status" \
-H "X-Payments-Key: $MODULIFY_PAYMENTS_KEY"Keys start with mpk_. Your site reads its key from process.env.MODULIFY_PAYMENTS_KEY and the base URL from process.env.MODULIFY_PAYMENTS_URL, both on the server only. They are managed secrets that Modulify creates the next time the preview starts or the site is published, once payments are on for the site. A missing, malformed or unknown key returns 401 with A valid payments key is required!
A key belongs to exactly one site, and its calls only ever reach that site's payments.
Response envelope
Every response, success or failure, has the same shape:
{
"success": true,
"message": "Checkout created.",
"data": {
"id": "cs_live_a1B2c3D4e5",
"url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5",
"expiresAt": 1794366000
},
"code": 200
}Treat a call as failed unless the HTTP status is OK and success is true. Read the payload from data. A refused call has the reason in message, and its HTTP status says what kind of refusal it is.
Endpoints
| Method | Path | Body | Returns |
|---|---|---|---|
| GET | /status |
None | { ready, livemode } |
| POST | /checkout |
{ items, currency, successUrl, cancelUrl, customerEmail, reference, idempotencyKey } |
{ id, url, expiresAt } |
| POST | /get-checkout |
{ id } |
{ id, status, paid, amountTotal, currency, reference, paymentId, livemode, expiresAt } |
/status
Reports whether the site can take payments right now. ready is true when payments are on for the site, the workspace is on a paid plan, and its account is Ready. livemode is true when that account is a live Stripe account, and false for a test account or when the site has no account yet. A site with payments off gets 403 instead, so check the status before you show a payment button.
/checkout
Creates a payment link for the items a visitor is buying. Send the visitor to data.url, where Stripe takes the payment. The link stops taking payments at expiresAt, a Unix time in seconds. At the longest lifetime that is two minutes short of a full day, because Stripe allows no more than 24 hours.
The body:
| Field | Type | Required | Description |
|---|---|---|---|
items |
array | Yes | One to 20 items, each { name, amount, quantity }. name is text of up to 250 characters. amount is a whole number in the currency's smallest unit, from 1 to 99,999,999. A currency with no smaller unit, such as jpy, counts whole units, so 500 is 500 yen. A three-decimal currency such as kwd counts thousandths. quantity is a whole number from 1 to 99 |
currency |
string | Yes | A three letter currency code, such as usd |
successUrl |
string | Yes | An https link the visitor goes to after paying. Put {CHECKOUT_SESSION_ID} in it, for example https://example.com/thanks?checkout={CHECKOUT_SESSION_ID}, and Stripe fills in the payment link's id for /get-checkout |
cancelUrl |
string | Yes | An https link the visitor goes to if they leave without paying |
customerEmail |
string | No | The visitor's email, which Stripe fills in on the payment page. Up to 254 characters |
reference |
string | No | Your own reference for the payment, such as your order id, up to 500 characters. It is kept with the payment, sent in webhooks and returned by /get-checkout |
idempotencyKey |
string | No | Up to 200 plain ASCII letters, digits, spaces and symbols. Send the same key when you retry the same payment link |
The amounts of all the items together, each amount times its quantity, must come to 99,999,999 or less.
The payment page accepts promotion codes. You create them in your Stripe dashboard, and a code only works on the account it was made in.
The idempotency key is kept apart for each site, so two sites on one workspace account can use the same key. Sending the same key again with the same details within a day returns the same payment link, with the same expiresAt. A key reused with different details comes back as 409, and a retry sent while the first request is still running comes back as 503, so try again a moment later.
const response = await fetch(`${process.env.MODULIFY_PAYMENTS_URL}/checkout`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Payments-Key': process.env.MODULIFY_PAYMENTS_KEY || ''
},
body: JSON.stringify({
items: [{ name: 'Pottery class', amount: 4500, quantity: 2 }],
currency: 'usd',
successUrl: 'https://example.com/booked',
cancelUrl: 'https://example.com/booking',
customerEmail: '[email protected]',
reference: 'booking-1042',
idempotencyKey: 'booking-1042-checkout'
})
})/get-checkout
Reads back a payment link this site created, so the page the visitor lands on after paying can confirm the order. Send the id that /checkout returned, or the one Stripe put in your success link.
| Field | Description |
|---|---|
id |
The payment link's id, starting with cs_ |
status |
open while the visitor can still pay, complete once they finished, expired once it ran out |
paid |
true once the payment went through. Fulfil the order only when it is true |
amountTotal |
What the visitor paid or will pay, after any promotion code, in the currency's smallest unit |
currency |
An upper case code, for example USD |
reference |
The reference you sent to /checkout, or null |
paymentId |
The Stripe payment ID once there is one, the same id as in the payment events and the Payments sub-tab, or null |
livemode |
false for a test payment |
expiresAt |
When the link stops taking payments, a Unix time in seconds |
It only finds links made with the account the site uses now, so a link made before you chose another account comes back as 404. A visitor can close the page before it loads, so confirm orders from a payment webhook as well, and fulfil each order once.
const response = await fetch(`${process.env.MODULIFY_PAYMENTS_URL}/get-checkout`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Payments-Key': process.env.MODULIFY_PAYMENTS_KEY || ''
},
body: JSON.stringify({ id: 'cs_live_a1B2c3D4e5' })
})Errors
A refused call answers with success: false, the reason as message and the HTTP status:
| Status | Message | Why |
|---|---|---|
401 |
A valid payments key is required! | The key is missing, malformed or unknown |
403 |
Payments are not switched on for this site! | Payments are off for the site, or not available to it |
403 |
Payments need a paid plan. Upgrade the workspace to take payments! | /checkout only: the workspace is on the Free plan |
409 |
Payments are not ready for this site yet! | /checkout only: the site has no account in use, or the account is not Ready yet |
429 |
Too many checkouts for this site. Try again shortly! | /checkout only: the site made more payment links in the last minute than 60 allows |
400 |
One of the messages below, or Stripe's own reason | /checkout only: a field is wrong. When Stripe refuses a field, such as an amount below its minimum for the currency, Stripe's reason comes back as the message |
409 |
That checkout was already created with different details! | /checkout only: the idempotencyKey was sent before with other details |
503 |
Payments are busy right now. Try again shortly! | /checkout and /get-checkout only: Stripe or the rate limit check could not be reached, or a request with the same idempotency key is still running. Try again shortly |
500 |
Could not create the checkout! | /checkout only: Modulify could not finish the request on its side |
400 |
That payment link id is not valid! | /get-checkout only: id is missing or does not start with cs_ |
404 |
That payment link was not found for this site! | /get-checkout only: the link was made by another site, with another account, or does not exist |
429 |
Too many checkout lookups for this site. Try again shortly! | /get-checkout only: the site read back more payment links in the last minute than 120 allows |
500 |
Could not read the checkout! | /get-checkout only: Modulify could not finish the request on its side |
500 |
Something went wrong while authorizing the payments request! | Modulify could not check the key |
500 |
Something went wrong loading the payment status! | /status only: Modulify could not read the status |
The 400 messages name the field that is wrong:
- Add at least one item to the checkout!
- That checkout has too many items!
- Every item needs a name, a whole amount and a quantity!
- That checkout is over the largest amount Stripe takes!
- Use a three letter currency code, such as usd!
- The success and cancel links must be https links!
- That customer email is not valid!
- That reference is too long!
- That idempotency key is too long!
- That idempotency key can only hold plain letters, digits, spaces and symbols!
- Send the request body as a JSON object!
Limits
| Limit | Value |
|---|---|
| Items in one payment link | 20 |
| Payment links a site can create a minute | 60 |
| Payment links a site can read back a minute | 120 |
| How long a payment link stays open | 1,440 minutes |