Contracts

contracts

A contract is the agreement to perform a one-time or recurring payment. Every payment in Shuttle is linked to a contract — even one-off payments create a contract under the hood.

Payment Models

A contract can be created in one of three models:

One-time: A single charge is created and payment is attempted immediately (or on a scheduled date)
Recurring (frequency-based): Charges are generated automatically on schedule (weekly, monthly, etc.) and payment is attempted for each
Scheduled charges: An explicit list of charges is supplied at creation, each with its own amount and due date. Use this when amounts or dates vary between charges (e.g., irregular instalment plans). frequency must be omitted or set to ONEOFF; action: AUTH is not supported. A charge with due: "now" or a past timestamp (within 24 hours) is taken synchronously during contract creation and a decline blocks the whole contract from being created. Charges with a future due timestamp are taken asynchronously by the scheduler on the due date, and the contract is created regardless of those later payments’ outcome. See List contract charges to retrieve the created charges.

For recurring contracts, if a significant change is made (amount, frequency), a new contract is created with a parent reference to the previous one. Changing the payment method or next payment date does not create a new contract.

Nonce (Duplicate Prevention)

Pass a nonce when creating a payment to prevent duplicate submissions. If the same nonce is submitted within 24 hours, no new contract will be created and the result of the previous contract will be returned.

Automatic Retries

Failed recurring payments are automatically retried on the following schedule:

Errors (e.g., gateway offline): 5 min, then 60 min, then 3 hours, then 6 hours, then 1 day

Declines (e.g., insufficient funds): 1 day, then 3 days, then 7 days, then 14 days, then 21 days

The retry_count tracks attempts and retry_complete is set when all retries are exhausted. A successful payment resets both. New instalments will still be attempted even after retry_complete.

Status Flow

Status	Description
`SETUP`	Contract is being configured
`ACTIVE`	Contract is active and charges are being generated/paid
`FAILING`	The last payment attempt failed, retries are in progress
`PENDING`	Payment has been made but is awaiting confirmation
`SUSPENDED`	Contract has been manually suspended
`UNRESOLVED`	No conclusive payment result received
`COMPLETED`	All charges have been paid
`CANCELLING`	Cancellation requested but outstanding balance remains
`CANCELLED`	Contract has been cancelled

Was this page helpful?