Payment Order

A payment order represents a single purchase. The payments beneath it are the individual attempts or contributions that fulfil that purchase, whether that's one successful payment, a retry after a failure, or several payments combining to cover the total.

The order is the purchase, and each payment is one effort to pay for it. A customer might pay the whole amount in a single card payment; a first attempt might fail and a second succeed; or the total might be settled partly by card and partly by another method. In every case the order is the one purchase, and its payments are how the funds arrive.

Each payment order has its own payment_order_id. It is created under a tenant, carries a Split Tree describing how its funds will be distributed, and acts as the parent for every payment attached to it. The order's lifecycle is controlled by the tenant, but its ability to advance depends on the status of the payments it contains.

Lifecycle

A payment order moves through four states: OPEN → CLOSED → SPLIT → SETTLED.

📘

Precondition for SPLIT

An order can only be split once every payment it contains has reached a terminal status.

🚀

Fast-forward

The close, split, and settle endpoints each accept an optional fast_forward: true body parameter. When set, Ping automatically performs all intermediate transitions, so a single call can take an order straight from OPEN through to SETTLED, provided its preconditions are met.

⏱️

Mind the timing

Close only when no more payments are coming. Splitting allocates the funds and ends the ability to refund through the acquiring method, and since settling moves through split, settling is irreversible too. Do not settle before the product or service has been delivered

Automating the lifecycle

You don't have to drive close, split, and settle by hand. Two settings, configured when the order is created (or updated later), let Ping advance the lifecycle for you based on rules you define. Manual calls always still work and can override the automation at any time.

Close Condition: when the order auto-closes

A close condition closes the order automatically once a threshold is met. It's evaluated each time a payment reaches a terminal status, and the order only closes when all payments are terminal and at least one is COMPLETED. Fully refunded payments are excluded from the count. Two thresholds are available:

• completed_payment_count — Close once a given number of completed payments exist. Count of 1 is the common case: the order closes the moment its single payment completes.
• completed_payment_amount — Close once the total of completed payments reaches or exceeds an amount, in minor units.

Settle Schedule: when the order auto-settles

A settle schedule defines when a closed order is settled. The settle operation fast-forwards through both split and settle, so this single setting takes a closed order all the way to ready-for-disbursement. Three strategies:

• absolute — Settle at a specific timestamp, useful when the delivery date is known in advance, such as an event. If the order isn't closed yet when the time arrives, settlement is attempted once it closes.
• relative — Settle after a duration (ISO-8601, e.g. P14D) measured from when the order closed. Adding a new payment during the window resets the duration, which prevents settling while funds are still being collected.
• cron — Settle on a recurring UTC schedule; the next occurrence after the order closes is used. Suited to batch settlement, e.g. every Monday morning.

How it relates to other concepts