> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Charge a payer's card on a schedule they agreed to

<Note>
  Subscriptions are in early access and subject to change. To request Subscriptions access, contact
  [hi@natural.com](mailto:hi@natural.com).
</Note>

A subscription charges a payer's card on a schedule they agree to once in checkout: with no end, or in 2 to 4 installments. One with no end charges every 1 to 25 weeks or every 1 to 5 months, so its payments are less than 180 days apart; yearly intervals aren't available yet. Natural keeps the card and the agreement, and charges each later payment when it falls due. In `POST /subscriptions`, a subscription with no end sets `terms.amount`, the amount of every payment (at least \$0.50), and `terms.every`, its one interval. Its `terms.paymentCount` reads null.

## Installments

A subscription in installments splits one purchase into 2 to 4 payments. In `POST /subscriptions`, set the purchase's total in `terms.totalAmount`, the number of payments in `terms.paymentCount`, and the time between payments in `terms.every`, on the same intervals as one with no end.

```json theme={null}
{
  "data": {
    "attributes": {
      "terms": {
        "description": "Standing desk, in 3 monthly payments.",
        "every": {
          "unit": "month",
          "count": 1
        },
        "totalAmount": 49999,
        "taxAmount": 3700,
        "paymentCount": 3
      }
    }
  }
}
```

Natural splits the total into equal payments and puts the cents that don't divide evenly on payment 1, so \$499.99 in 3 payments is \$166.67, then \$166.66 twice. Each payment must be at least \$0.50: a split that makes one smaller is refused, and the error names that payment. The subscription lists each payment's amount in `terms.payments`.

Payment 1 is charged in checkout, on the day the payer agrees, and payment n falls n-1 intervals after that day. A payer who agrees on Jan 31 to monthly payments pays on Jan 31, Feb 28 and Mar 31. Checkout shows the payer every date before they agree, and the dates don't change after that. `nextPayment.dueDate` gives the next one.

## Tax

`amount` and `totalAmount` are what the payer pays, tax included. To say how much of it is tax, set `terms.taxAmount`, which defaults to 0. Every payment of a subscription with no end carries `taxAmount`. In installments, the tax is split the same way as its total, with the cents that don't divide evenly on payment 1, and `terms.payments` lists each payment's `taxAmount`. Each payment's payment intent carries its share. The agreement the payer accepts names each payment's tax, and each payment's receipt shows its tax.

## Lifecycle

1. Create a subscription with `POST /subscriptions`. It starts `pending` and returns a `checkoutUrl` and a `clientSecret`. To stop checkout taking payment after a deadline, set `expiresAt`. A pending subscription can't be changed, and neither can its checkout's payment intent. To offer other terms, end the subscription (see [Canceling](#canceling)) and create a new one.
2. The payer agrees to the terms and pays payment 1 in checkout. The subscription becomes `active`, and `mandateId` names the card agreement it charges.
3. Natural charges each later payment automatically when it falls due. A payment can be charged from 12:00 UTC on its due date until 30 days later, or until the next payment opens if that's sooner. To charge one yourself inside that window, use `POST /subscriptions/{subscriptionId}/payments`, which returns the [card payment](/guides/concepts/card-payments). `GET /card-payments?subscriptionId={subscriptionId}` lists every card payment whose `subscription` is that subscription, newest first: each attempt at each payment, payment 1's checkout attempts included.
4. A subscription becomes `canceled` when the payer or you cancel it, when the payer's bank stops its agreement, when checkout ends or expires without payment 1, or when the agreement can't be set up. One in installments becomes `completed` once every payment is paid or marked paid. A canceled subscription stays canceled, even if a charge already under way then pays its last payment.

`GET /subscriptions` lists your subscriptions, newest first. Pass `status` to list only those in one status, such as `needs_attention`.

## Embed checkout

To take payment 1 on your own page instead of sending the payer to `checkoutUrl`, pass the subscription's `clientSecret` from your server to the payer's browser. It's set whenever `checkoutUrl` is, so it's null once checkout ends. Treat it like a password. Mount Natural's payment form with it:

```typescript TypeScript theme={null}
import { loadNatural } from "@naturalpay/js";

const natural = await loadNatural();
await natural.paymentForm({ clientSecret }).mount("#payment-form");
```

The form shows the subscription's agreement as the hosted checkout does, verifies the payer's phone, and charges payment 1. Your page must show what the payer is buying and its price, your country and a support email or phone, and your delivery policy if you ship goods.

In live mode, the form loads only on a site in your checkout domains, which you add in the dashboard under **Developers → API keys**. In sandbox, it loads on any site.

## Missed payments

A declined payment is retried inside its window. If it still isn't paid, it's missed: `missedPayments` lists it and the subscription is `past_due`. Natural never charges a missed payment late, so collect it another way. Later payments are still charged on schedule.

A subscription becomes `needs_attention`, and Natural stops collecting, when two payments in a row are missed or when the bank declines the card in a way that rules out a retry. `attention.reason` says which.

Once you've collected a missed payment another way, mark it with `POST /subscriptions/{subscriptionId}/mark-paid`, so it's no longer owed. That includes a payment whose window closed while the subscription was stopped. Marking a payment paid first records any earlier payments that already lapsed as missed, so they stay owed until you mark them paid too. Marking paid only settles a missed payment: it doesn't settle an upcoming one, and it doesn't restart a subscription that needs attention. To start collecting again, call `POST /subscriptions/{subscriptionId}/resume`.

## Canceling

You can cancel a subscription with `POST /subscriptions/{subscriptionId}/cancel`. The payer of a subscription with no end can also cancel it online, on its manage page. The payer of one in installments can view it there but can't cancel it, because they still owe its remaining payments. When a subscription is canceled, Natural revokes its card agreement and sends `mandate.revoked`, with `revocationReason` `payer_canceled` or `merchant_canceled`. Natural charges nothing more and emails the payer a confirmation. A charge already under way when the subscription is canceled can still go through, and the subscription's payments stay listed.

Canceling a subscription that's still `pending` cancels its checkout instead, so the payer can't pay payment 1, and the subscription becomes `canceled`. There's no agreement yet, so you get `paymentIntent.canceled` rather than `mandate.revoked`, and the payer isn't emailed. If the payer has already submitted payment 1, the cancel is refused with `subscription_pending` until its outcome lands. Once it's paid and the subscription is `active`, a cancel revokes the agreement as above.

The payer reaches the manage page from Natural's emails. The subscription's confirmation, each receipt and each failed-payment email link to it: "Manage or cancel" for a subscription with no end, "View your plan" for installments. Hosted checkout's confirmation links to it too, for a subscription with no end. The link asks for a code sent to the email the payer confirmed in checkout.

The manage page shows the subscription's terms and status, its next payment, its payments and the card on file, and lets the payer of a subscription with no end cancel.

## Subscription payments and webhooks

Every charge of a subscription is a [card payment](/guides/concepts/card-payments) with fields only a subscription's payments carry:

* `subscription` has the subscription's `id`, the `paymentNumber` the charge pays, and its `paymentCount`, which is null when it has no end. Payment 1 is the checkout payment.
* A later payment has `channel` `api`, because Natural charged the card without the payer present, and `mandateId` names the card agreement it was charged on.

Read a subscription's charges with `GET /card-payments?subscriptionId={subscriptionId}` and `GET /card-payments/{cardPaymentId}`. Every charge, payment 1 included, sends `cardPayment.created`, then `cardPayment.succeeded` or `cardPayment.failed`, each with the same fields. A successful charge also sends `paymentIntent.completed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.