# Payments HTTP API

Source: https://modulify.ai/docs/built-in/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.

> **Payments are in alpha**
>
> 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](https://modulify.ai/docs/reference/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](https://modulify.ai/docs/built-in/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.

```bash
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](https://modulify.ai/docs/data/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:

```json
{
    "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.

```ts
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: 'visitor@example.com',
        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](https://modulify.ai/docs/automations/webhooks#payment-events) as well, and fulfil each order once.

```ts
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](https://modulify.ai/docs/built-in/payments) covers the tab, the accounts and the list of payments.
- [Webhooks](https://modulify.ai/docs/automations/webhooks#payment-events) describes the payment events and their payload.
- [Secrets](https://modulify.ai/docs/data/secrets) explains the managed secrets the site reads.