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

Next

  • Payments covers the tab, the accounts and the list of payments.
  • Webhooks describes the payment events and their payload.
  • Secrets explains the managed secrets the site reads.