# Payments

Source: https://modulify.ai/docs/built-in/payments

Take payments from your site's visitors into your own Stripe account, with a list of every payment, analytics and the payment links your site's code creates.

> **Payments are in alpha**
>
> Payments are open on a few sites while we test them. To take payments on your site, ask for access in the [support chat](https://modulify.ai/docs/reference/support-chat).

A site with payments can take them from its visitors, for a booking, an order, a ticket or anything else you sell. The money goes straight to a Stripe account in your name. Modulify never holds it, pays it out, refunds it or files tax forms for it. Stripe pays your balance out to your bank account, and you manage refunds and disputes in your Stripe dashboard. Everything lives in the **Payments** tab under **More** in the editor, with three sub-tabs: **Overview**, **Payments** and **Analytics**.

Only the workspace owner can turn payments on or off, connect a Stripe account and choose the account a site takes payments with. Everyone else with access to the site sees those controls disabled, with the tooltip **Only the workspace owner can change payments.** Only the owner can open **Payments** and **Analytics**. Everyone else sees those two sub-tabs disabled, with the tooltip **Only the workspace owner can see payments.**

## Before you begin

Payments need a Stripe account for your workspace. Stripe checks your details in its own secure setup and asks for what it needs to pay you out. Modulify takes no fee from payments. Stripe takes its card fee from your balance on each payment.

Payments need a paid plan. On Free the tab stays visible, with its controls off and the tooltip **Payments need a paid plan.** The account's country must be one Stripe supports for payment accounts, and the country menu on **Overview** lists them.

The **Payments** tab only appears under **More** on a site that has payments. If you do not see it there, payments are not open for that site yet.

## Set up payments

### Connect a Stripe account

On **Overview**, under **Connect a Stripe account**, choose a **Country** and a **Business type**, then choose **Set up payments**. Modulify opens Stripe's own setup for the account. When you finish, Stripe brings you back to the **Payments** tab of this site.

### Choose the account

The account is listed with its status. Choose **Use** once an account shows **Ready**, to make it the one this site takes payments with. **Turn on** stays disabled until the account in use is **Ready**. If you leave Stripe's setup before it is done, choose **Continue setup** on the account to pick up where you left off.

### Turn payments on

Under **Accept payments on this site**, choose **Turn on**. Turning payments off is always allowed. Visitors can pay once the account in use shows **Ready**, and the line under the switch reads **Visitors can pay this site.** If that account later stops being **Ready**, or the workspace leaves its paid plan, the line says what is missing and the payment links your site asks for are refused until it is fixed.

## Overview

**Accept payments on this site** is the switch for the whole site. Turning it off stops new payment links. A payment link that was already made stays open until it runs out.

Under **Payment accounts** the tab lists each account with its country, **Live** or **Test**, whether it is for a **Company** or an **Individual**, and its status:

| Status | What it means |
| --- | --- |
| **Setting up** | Stripe is still checking the account and needs nothing from you right now |
| **Action needed** | Stripe needs more details from you before the account can take payments. Choose **Continue setup** to give them |
| **Ready** | The account takes payments, so visitors can pay the sites that use it |
| **Restricted** | Stripe has restricted the account, so it cannot take payments. Your Stripe dashboard says why |
| **Closed** | The account is closed and takes no payments. It no longer counts toward the limit |

When Stripe needs details from you, the account says how many and by when, for example **Stripe needs 2 more details by Dec 1, 2026.**, and offers **Continue setup**. A **Ready** account can owe details too: it keeps taking payments until that date, and Stripe may restrict it if they are still missing then.

**Open Stripe** opens your Stripe dashboard in a new tab, on a **Ready** or **Restricted** account. Sign in there with the Stripe login you made during setup to see payouts, refunds, disputes and your balance.

**Use** chooses the account a site takes payments with, and the account in use shows **In use** on its button. **Use** is only offered on an account that shows **Ready**. When you open **Overview**, Modulify checks with Stripe every account that is not **Ready** yet or still owes details, so its status stays current.

The form stays below the list, so a second business can connect its own account. At the account limit the form stays visible but disabled, with the reason beside it.

## Payments

The **Payments** sub-tab lists every payment your visitors made on the site, newest first, with its refunds and disputes. Each row shows:

- the amount, with a **Paid** or **Failed** badge. A failed payment shows the amount the visitor tried to pay
- a **Test** badge for a payment made in Stripe's test mode, and a **Disputed** badge once a dispute opens
- the Stripe payment ID
- the refunded amount, when there is one
- how long ago the visitor paid, or tried to

Choose **All payments**, **Paid**, **Refunded**, **Disputed** or **Failed** to filter the list. The date picker above the list opens on **Last day** and runs from **Today** to **All time**, or a custom range.

Payments made before you chose a different account stay in the list. A site moved to another workspace starts a fresh list there, because the payments it took before went to the previous workspace's account. Each currency uses its own decimal places, so an amount in a currency with no decimals, such as yen, has none.

Refunds and disputes are made in your Stripe dashboard. A refund or dispute updates its row when Stripe reports it. Modulify keeps each payment in the list for 1 year from when it was made, then removes it. The payment stays in your Stripe dashboard, and a refund or dispute on it after that sends no payment event to your site.

## Analytics

**Analytics** uses the same date picker. Its four cards total the payments in the primary currency, the one with the most payments in the period: **Paid**, **Payments**, **Refunded** and **Disputes**. Only payments that went through count toward **Paid** and **Payments**: a failed attempt shows in the **Payments** sub-tab but never adds to the totals. **Paid over time** charts the amount paid across the period. When visitors paid in more than one currency, **By currency** lists the paid amount and the number of payments for each. Days run from midnight UTC, so a payment made late in the evening in your time may count toward the next day.

## Payment links from your site's code

Your site's server creates a payment link for what a visitor is buying and sends the visitor to it. Stripe hosts the payment page, and the prices come from your server, so the visitor's browser cannot change them.

A payment brings no buyer details back to your site. Save the order in your site first, with whatever you need to deliver it, such as the buyer's name, email and shipping address, collected in your own form. Then create the payment link with the order's id as its `reference`, and the buyer's email so Stripe fills it in.

To confirm the order, use both of these, and fulfil it only once:

- **The success page.** Put `{CHECKOUT_SESSION_ID}` in the success link, for example `https://example.com/thanks?checkout={CHECKOUT_SESSION_ID}`. Stripe fills in the payment link's id, and your page's server reads it back with `getPaymentLink`, which says whether it is paid and returns your `reference`. This works in the preview too.
- **A webhook.** A visitor can close the page before it loads, so add a webhook for the payment events that points at a route on your published site. That route checks each event with `verifyPaymentEvent` and finds the order from `payment.reference`.

Visitors can enter a promotion code on the payment page. You create the codes in your Stripe dashboard, and each one works only on the account it was made in.

Ask chat for it, and it writes the helper `@/lib/modulify/payments` into your project at `src/lib/modulify/payments.ts`. The helper wraps the endpoints below and reads the managed secrets for you, and it only ever runs on the server: `getPaymentsStatus` says whether the site can take payments, `createPaymentLink` makes a payment link and `getPaymentLink` reads one back. It also checks the signature of each payment event that reaches your site's webhook with `verifyPaymentEvent`, and refuses an event that does not match or is too old.

Your site reads two [managed secrets](https://modulify.ai/docs/data/secrets), `MODULIFY_PAYMENTS_URL` and `MODULIFY_PAYMENTS_KEY`. They appear once payments are on for the site, and they reach the preview when it starts and the published site when you publish it. The [Payments HTTP API](https://modulify.ai/docs/built-in/payments-http-api) lists both endpoints, every field and every error.

To hear about a payment, add a webhook for `payment.succeeded`, `payment.refunded` or `payment.disputed`. **Send test event** on a webhook that only has payment events sends a sample payment marked `"test": true`, so you can try your code without paying. A **Slack** or **Discord** webhook posts each payment to a channel with its amount. See [Webhooks](https://modulify.ai/docs/automations/webhooks#payment-events).

## Moving a site to another workspace

Payment accounts belong to a workspace, so a site that moves to another workspace, or is transferred to someone else, stops taking payments into the old account. Payments turn off, the site no longer uses any account, and its payments key is replaced. The new workspace's owner connects or chooses one of their own accounts on **Overview** and turns payments on again, and the site takes payments once it is published again.

## What the AI can do

Chat writes your site's code that creates payment links and confirms orders, using the helper above. Before it does, it reads whether the site can take payments yet and tells you what is missing. It also answers questions about your payments, such as how much the site took this month, from the same list and totals as the tab, for the workspace owner. It cannot turn payments on, connect a Stripe account, choose an account or create a payment link for you, so those stay in the **Payments** tab. The payments tools in [MCP](https://modulify.ai/docs/mcp/tools#payments) read the status, the list of payments and their totals for an AI client.

## Limits

| Limit | Value |
| --- | --- |
| Payment accounts a workspace can have open | 5 |
| Items in one payment link | 20 |
| How long a payment link stays open | 1,440 minutes |
| Payment links a site can create a minute | 60 |
| Payment links a site can read back a minute | 120 |
| How long a payment stays in the list | 1 year |

## Next

- [Payments HTTP API](https://modulify.ai/docs/built-in/payments-http-api) lists every endpoint, field and error.
- [Webhooks](https://modulify.ai/docs/automations/webhooks#payment-events) describes the payment events and their payload.