> ## 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 operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> 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>
  Plans are in early access and subject to change. To request Plans access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

A plan is a subscription, or 2 to 4 installments, that a payer agrees to once in checkout. A subscription charges every 1 to 25 weeks or every 1 to 5 months, so its payments are less than 180 days apart; yearly plans aren't available yet. Natural keeps the card and the agreement, and you charge each later payment when it falls due.

## Installments

An installment plan splits one purchase into 2 to 4 payments. In `POST /plans`, set each payment's amount in `terms.payments`, in order, and the time between payments in `terms.every`, on the same intervals as a subscription:

```json theme={null}
{
  "data": {
    "attributes": {
      "terms": {
        "kind": "installments",
        "description": "Standing desk, in 3 monthly payments.",
        "payments": [
          {
            "amountMinor": 12000
          },
          {
            "amountMinor": 12000
          },
          {
            "amountMinor": 12000
          }
        ],
        "every": {
          "unit": "month",
          "count": 1
        }
      }
    }
  }
}
```

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.

## Lifecycle

1. Create a plan with `POST /plans`. It starts `pending` and returns a `checkoutUrl`.
2. The payer agrees to the terms and pays payment 1 in checkout. The plan becomes `active`, and `mandateId` names the card agreement it charges.
3. Charge each later payment with `POST /plans/{planId}/payments`. It returns the [card payment](/guides/concepts/card-payments). 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. `GET /plans/{planId}/payments` lists a plan's charges, newest first, as the same card payments: payment 1 from checkout, and each attempt at a later payment.
4. A plan becomes `canceled` when the payer or you cancel it, when the payer's bank stops its agreement, when checkout ends without payment 1, or when the agreement can't be set up. An installment plan becomes `finished` once every payment is paid or skipped.

## Missed payments

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

A plan 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 /plans/{planId}/skip`, so it's no longer owed. That includes a payment whose window closed while the plan was stopped. Skipping a payment first records any earlier payments that already lapsed as missed, so they stay owed until you skip them too. Skip only settles a missed payment: it doesn't skip an upcoming one, and it doesn't restart a plan that needs attention. To start collecting again, call `POST /plans/{planId}/resume`.

## Canceling

You can cancel a plan with `POST /plans/{planId}/cancel`. A subscription's payer can also cancel it online, on its manage page. An installment plan's payer can view it there but can't cancel it, because they still owe its remaining payments. When a plan 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 plan is canceled can still go through, and the plan's payments stay listed. To end a plan that's still `pending`, cancel its payment intent instead.

The payer reaches the manage page two ways:

* **From your app.** Call `POST /plans/{planId}/manage-links` and send your signed-in customer to the `url` it returns. The link opens once, with no code, and expires after 5 minutes, so create one each time the customer asks to manage the plan.
* **From Natural's emails.** The plan's confirmation, each receipt and each failed-payment email link to it: "Manage or cancel" for a subscription, "View your plan" for an installment plan. The link asks for a code sent to the email the payer confirmed in checkout.

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

## Plan payments and webhooks

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

* `plan` has the plan's `id`, its `kind`, and the `paymentNumber` the charge pays. 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 plan's charges with `GET /plans/{planId}/payments`, `GET /card-payments` 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.