Scheduled Payments

This page is part of the REST API Guides. Card capture happens in the frontend through the Payments Library; see the Payments Library Guides.

Prerequisites: API key, a Payment Gateway Account, 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.

Templates

Create templates in the portal under Scheduled Payments > Templates. There is no API for templates. A template charges through one payment gateway account: if each merchant has its own account, create one template per merchant account and frequency. Scheduled payments do not use fallback gateways and are sent without CVV and without 3DS data.

End-to-End Setup

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.

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

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 for rendering the payment sheet in your page.

Read the token from the result

When the session completes, the Library callback gives you a results token. Send it as a JSON string to validateResults (see Result Handling), then take the token:

curl -X POST https://api.orchestrasolutions.com/EWalletOperations/validateResults \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '"RESULTS_TOKEN"'

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.

Create the contract

Tie the template and the token together:

curl -X POST https://api.orchestrasolutions.com/PaymentContract \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "YOUR_TEMPLATE_ID",
    "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",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2028,
      "payerDetails": {
        "address1": "1 Main Street",
        "city": "Dublin",
        "postCode": "D01 W2T2",
        "countryCode": "IE"
      }
    }
  }'

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.

Store the contract id

You need it to retrieve, update, pause, resume or cancel the arrangement later.

templateId, name, tokenId, startDate and chargeRequestData are required. The token holds only the card number. Send the rest of the card details in chargeRequestData: cardHolderName, expirationMonth and expirationYear, plus the payer’s address in payerDetails if your payment provider asks for it. These details come from your customer. You can take the name and expiry date from the masked card details returned with the token.

This is a general example. Each payment provider is different and may require different fields. Check what your provider needs in Gateway Requirements.

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:

{
  "templateId": "YOUR_TEMPLATE_ID",
  "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",
    "cardHolderName": "Jane Smith",
    "expirationMonth": 12,
    "expirationYear": 2028
  }
}

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.

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.

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.

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

Some processors require additional parameters, and some treat recurring payments differently from one-off ones. Check Additional Guidance for your processor before going live with a plan.

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.

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.

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.

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.

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

Scheduled payments run in the background, so the result is not returned on a request. Retrieve the contract with GET /PaymentContract/{id} to follow it.

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.

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

Next Steps

Payment Contracts API

Full reference for every contract endpoint.

Payments Library Setup

Collect the card and create the token in your frontend.

Gateway Requirements

Processor-specific parameters to check before you schedule.

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

The Three Pieces

Templates

End-to-End Setup

Instalment Plans

Offering a Choice of Plans

Charge Data

Deciding When Payments Stop

Timezones

Managing a Running Contract

Tracking Progress

Next Steps

Payment Contracts API

Payments Library Setup

Gateway Requirements

​The Three Pieces

​Templates

​End-to-End Setup

​Instalment Plans

​Offering a Choice of Plans

​Charge Data

​Deciding When Payments Stop

​Timezones

​Managing a Running Contract

​Tracking Progress

​Next Steps

Payment Contracts API

Payments Library Setup

Gateway Requirements

The Three Pieces

Templates

End-to-End Setup

Instalment Plans

Offering a Choice of Plans

Charge Data

Deciding When Payments Stop

Timezones

Managing a Running Contract

Tracking Progress

Next Steps