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

# Scheduled Payments

> Set up instalments, subscriptions and recurring billing with payment contracts.

<Info>
  This page is part of the **REST API Guides**. Card capture happens in the frontend through the Payments Library; see the [Payments Library Guides](/guides/library/setup).
</Info>

**Prerequisites:** [API key](/getting-started/generate-api-key), a [Payment Gateway Account](/getting-started/add-payment-provider), and a payment schedule template configured in the Orchestra portal.

Payment contracts are how you charge a card more than once from a single customer interaction. They cover instalment plans, subscriptions, monthly billing, membership renewals and any other arrangement where one agreement produces a series of payments.

You capture and tokenize the card once, create a contract, and Orchestra runs the payments on the schedule. Because the schedule is tied to a payment gateway account rather than to one processor's own subscription product, moving a plan between processors is a configuration change, not a rewrite of your billing code.

## The Three Pieces

| Piece                         | Where                              | What it does                                                                       |
| ----------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
| **Payment schedule template** | Orchestra portal                   | Sets the rhythm: how often payments run, and through which payment gateway account |
| **Token**                     | Payments Library / eWallet session | Represents the customer's card, so the contract never holds card data              |
| **Payment contract**          | REST API                           | One customer's arrangement: which token, how much, starting when, how many times   |

One template normally backs many contracts. That is what keeps every customer on the same plan billing identically.

## End-to-End Setup

<Steps>
  <Step title="Create the template in the portal">
    Once per plan. Choose the frequency (Daily, Weekly, BiWeekly, Monthly, Quarterly, SemiAnnually or Annually) and the payment gateway account that will process the payments. Note the template id.
  </Step>

  <Step title="Collect the card and get a token">
    Start an eWallet session and let the customer pay or enter their card in the frontend. The operation you choose decides whether the first payment happens now:

    | Operation              | Use when                                                          |
    | ---------------------- | ----------------------------------------------------------------- |
    | `CHARGE_AND_TOKENIZE`  | The first payment is taken immediately and the rest are scheduled |
    | `TOKENIZE`             | No payment now, the schedule starts later                         |
    | `PREAUTH_AND_TOKENIZE` | You want to verify the card now and charge later                  |

    ```bash theme={null}
    curl -X POST https://api.orchestrasolutions.com/EWalletOperations \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -d '{
        "operation": "CHARGE_AND_TOKENIZE",
        "paymentGatewayAccountId": "your-gateway-account",
        "amount": 29.00,
        "currencyCode": "EUR",
        "mode": "LIVE",
        "customerEmail": "customer@example.com",
        "merchantReference": "sub-4821"
      }'
    ```

    See the [Payments Library setup guide](/guides/library/setup) for rendering the payment sheet in your page.
  </Step>

  <Step title="Read the token from the result">
    When the session completes, validate the results and take the token:

    ```bash theme={null}
    curl -X POST https://api.orchestrasolutions.com/EWalletOperations/validateResults \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -d '{ "...": "session result payload" }'
    ```

    The response carries `tokenAndMaskedCardModel`, whose `token` field is what the contract needs. The same object holds the masked card details, which you can store to show the customer which card their plan is billed to.
  </Step>

  <Step title="Create the contract">
    Tie the template and the token together:

    ```bash theme={null}
    curl -X POST https://api.orchestrasolutions.com/PaymentContract \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -d '{
        "templateId": "tmpl_monthly_standard",
        "name": "Acme Corp monthly plan",
        "tokenId": "token-from-previous-step",
        "startDate": "2026-11-01",
        "maxOccurrences": 12,
        "chargeRequestData": {
          "amount": 29.00,
          "currency": "EUR",
          "myRef": "sub-4821",
          "orderDesc": "Standard plan, monthly"
        }
      }'
    ```

    <Tip>
      If you took the first payment with `CHARGE_AND_TOKENIZE`, set `startDate` to the date of the **second** payment and count only the remaining payments in `maxOccurrences`. The contract does not know about the charge you already took.
    </Tip>
  </Step>

  <Step title="Store the contract id">
    You need it to retrieve, update, pause, resume or cancel the arrangement later.
  </Step>
</Steps>

`templateId`, `name`, `tokenId`, `startDate` and `chargeRequestData` are required. Everything else is optional.

## Instalment Plans

An instalment plan is a contract with a fixed number of payments. Divide the total by the number of instalments, set `maxOccurrences`, and use a template with the right frequency.

For a 600.00 purchase split into 5 monthly instalments, against a template whose frequency is Monthly:

```json theme={null}
{
  "templateId": "tmpl_monthly_standard",
  "name": "Order 88421, 5 instalments",
  "tokenId": "token-from-previous-step",
  "startDate": "2026-11-01",
  "maxOccurrences": 5,
  "chargeRequestData": {
    "amount": 120.00,
    "currency": "EUR",
    "myRef": "order-88421"
  }
}
```

### Offering a Choice of Plans

Because `maxOccurrences` and `amount` are set per contract, you can decide the number of instalments at the moment of purchase. A checkout that offers one immediate payment, up to 5 instalments, or up to 18 instalments needs no configuration per event: your page presents the options, and you create the contract that matches what the customer chose.

| What the customer chose        | What you do                                                           |
| ------------------------------ | --------------------------------------------------------------------- |
| Pay in full now                | A single `CHARGE` operation, no contract                              |
| First payment now, then N more | `CHARGE_AND_TOKENIZE`, then a contract with `maxOccurrences` set to N |
| N payments, first one later    | `TOKENIZE`, then a contract with `maxOccurrences` set to N            |

The maximum you allow is yours to decide and can differ per product, per event or per page. Nothing in Orchestra caps it.

<Note>
  Frequency comes from the template, not from the contract. If you offer monthly and weekly plans, create one template per frequency and point each contract at the right one. The number of payments and the amount stay per contract.
</Note>

<Warning>
  Each instalment is charged to the card when it falls due, so the card must still be valid and funded on each date. The full amount is not reserved up front. For long plans, watch for cards expiring mid-plan and collect a replacement before the next payment.
</Warning>

### Charge Data

`chargeRequestData` describes the payment made each time the schedule fires:

| Field                               | Description                                        |
| ----------------------------------- | -------------------------------------------------- |
| `amount`                            | Amount in major units, for example `29.00`         |
| `currency`                          | ISO 4217 currency code                             |
| `myRef`                             | Your own reference for the transaction             |
| `orderDesc`                         | Order description, used by some processors         |
| `payerDetails`                      | Payer information, where the processor requires it |
| `isDigital`                         | Digital goods flag, used by some processors        |
| `cardHolderName`                    | Cardholder name as it appears on the card          |
| `expirationMonth`, `expirationYear` | Card expiry                                        |

<Note>
  Some processors require additional parameters, and some treat recurring payments differently from one-off ones. Check [Additional Guidance](/guides/rest-api/gateway-requirements) for your processor before going live with a plan.
</Note>

## Deciding When Payments Stop

A contract can run indefinitely, or you can bound it:

* **`endDate`** stops payments after a calendar date.
* **`maxOccurrences`** stops payments after that many successful charges.

Set both and whichever is reached first ends the contract, which then moves to **Completed** on its own.

<Tip>
  For a fixed instalment plan use `maxOccurrences` rather than `endDate`. It counts successful payments, so a payment that fails and is retried does not cut the plan short.
</Tip>

## Timezones

Two optional fields control which day a payment lands on:

* `merchantTimezone`
* `cardholderTimezone`

Both take IANA names, for example `America/New_York`. Leave them out and Orchestra applies its defaults. Set them when a monthly charge should fall on the first of the month in the customer's timezone rather than yours.

## Managing a Running Contract

| Action | Endpoint                            | Effect                                                                     |
| ------ | ----------------------------------- | -------------------------------------------------------------------------- |
| Pause  | `POST /PaymentContract/{id}/pause`  | Stops payments, keeps the contract. Only an Active contract can be paused. |
| Resume | `POST /PaymentContract/{id}/resume` | Restarts payments. Only a Paused contract can be resumed.                  |
| Cancel | `POST /PaymentContract/{id}/cancel` | Stops payments permanently. Cannot be undone.                              |
| Update | `PUT /PaymentContract/{id}`         | Changes `name`, `endDate`, `maxOccurrences` and `metadata` only.           |

<Warning>
  Cancelling is permanent. A cancelled contract cannot be resumed, and recovering the arrangement means creating a new one. Use pause for anything temporary, such as a payment holiday or an account under review.
</Warning>

To change the amount, the currency or the card, cancel the contract and create a new one. Those are fixed for the life of a contract, which keeps the billing history unambiguous.

## Tracking Progress

| Field                | Meaning                                        |
| -------------------- | ---------------------------------------------- |
| `status`             | `Active`, `Paused`, `Cancelled` or `Completed` |
| `currentOccurrences` | Successful payments so far                     |
| `nextPaymentDate`    | When the next payment is due                   |
| `lastExecutedAt`     | When the last successful payment ran           |

Listing supports filtering by `templateId` and `status`, with `pageNumber` and `pageSize` for paging. Filter by template to see everyone on a plan, by status to find contracts that are paused and should not be.

```bash theme={null}
curl "https://api.orchestrasolutions.com/PaymentContract?status=Paused&pageSize=50" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Contracts API" icon="code" href="/api-reference/paymentcontract/overview">
    Full reference for every contract endpoint.
  </Card>

  <Card title="Payments Library Setup" icon="puzzle-piece" href="/guides/library/setup">
    Collect the card and create the token in your frontend.
  </Card>

  <Card title="Gateway Requirements" icon="circle-info" href="/guides/rest-api/gateway-requirements">
    Processor-specific parameters to check before you schedule.
  </Card>

  <Card title="Transaction Status" icon="magnifying-glass" href="/guides/rest-api/transaction-status">
    Check the outcome of individual payments.
  </Card>
</CardGroup>