Payment Contracts API Overview

← Back to API Reference

A payment contract is a single recurring payment arrangement: one customer, one saved payment method, one schedule. Orchestra executes the payments for you and keeps track of how many have run. Contracts are always created from a payment schedule template, which you configure once in the Orchestra portal. The template sets the rhythm (how often payments run and through which payment gateway account), and the contract supplies the specifics (who is paying, how much, from which token, starting when).

Templates and Contracts

	Payment schedule template	Payment contract
Where it lives	Orchestra portal	REST API
How many	One per billing plan	One per customer arrangement
Defines	Frequency and payment gateway account	Token, amount, currency, start date, limits
Example	”Monthly subscription, billed through our EU gateway"	"Customer 4821, EUR 29.00, from 1 October”

One template typically backs many contracts. Reusing a template is what keeps a subscription plan consistent across all the customers on it.

Contract Lifecycle

Active

Created and running. Orchestra charges the saved token on each due date and increments the occurrence count after each successful payment.

Paused

Temporarily stopped. No payments are attempted. The contract keeps its history and can be resumed.

Cancelled

Permanently stopped. A cancelled contract cannot be resumed; create a new contract instead.

Completed

Reached its end date or its maximum number of payments. No further action needed.

Cancelling is final. If you only want to stop payments for a while, pause the contract instead.

Ending a Contract

A contract can be open-ended, or you can bound it in either of two ways, or both:

endDate stops payments after a calendar date.
maxOccurrences stops payments after a set number of successful charges.

Whichever limit is reached first moves the contract to Completed.

Endpoints

List Contracts

Page through your contracts, filtered by template or status.

Create Contract

Start a recurring arrangement from a template.

Retrieve Contract

Get the full detail of one contract, including its schedule and charge data.

Update Contract

Change the name, end date, maximum occurrences or metadata.

Pause Contract

Stop payments temporarily, keeping the contract intact.

Resume Contract

Restart a paused contract.

Cancel Contract

Stop a contract permanently.

Scheduled Payments Guide

Worked examples, timezone handling and lifecycle detail.

Overview

Payment Operations

String Tokens