Configure Automatic Settlement

Settle Schedule and Close Condition allow you to automate the Payment Order lifecycle. Instead of manually calling the Close and Settle endpoints, the system can close and settle Payment Orders on your behalf based on rules you define.

Background: The Payment Order Lifecycle

A Payment Order progresses through four statuses:

OPEN  -->  CLOSED  -->  SPLIT  -->  SETTLED

Important: Settling Means No More Refunds

Once a Payment Order is split and settled, Ping can no longer process refunds on the underlying payments. The funds are committed to the recipients defined by the split tree and queued for disbursement.

Do not settle before the product or service has been delivered. If a customer dispute arises after settlement, it cannot be resolved through a standard refund — it would require manual intervention outside the normal payment flow.

When to Use Automatic Settling

Close Condition

A Close Condition automatically closes a Payment Order when a threshold is met. The condition is evaluated each time a payment reaches a terminal status. For the order to close, all payments must be in a terminal status and at least one must be COMPLETED.

Fully refunded payments are excluded from the evaluation.

completed_payment_count

Close the order when a specified number of completed payments exist.

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "close_condition": {
    "condition": "completed_payment_count",
    "count": 1
  }
}

This is the most common configuration — one payment per order. The order closes as soon as the single payment completes.

completed_payment_amount

Close the order when the total amount of completed payments reaches or exceeds a threshold. The amount is in minor currency units (e.g. ore for SEK/NOK/DKK, cents for EUR/GBP).

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "close_condition": {
    "condition": "completed_payment_amount",
    "amount": 50000
  }
}

This closes the order once 500 SEK (50 000 ore) worth of completed payments exist.

Settle Schedule

A Settle Schedule defines when a Payment Order should be automatically settled after it has been closed. The settle operation includes both the split and the settle steps — the system fast-forwards through the full lifecycle.

There are three strategies: absolute, relative, and cron.

absolute

Settle at a specific point in time. Useful when you know the exact settlement date in advance (e.g. an event date).

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "settle_schedule": {
    "strategy": "absolute",
    "settle_at": "2026-06-15T09:00:00Z"
  }
}

If the order is not yet closed when the timestamp arrives, settlement will be attempted once the order closes.

relative

Settle after a duration has elapsed since the order was closed. The duration is an ISO-8601 duration string.

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "settle_schedule": {
    "strategy": "relative",
    "settle_after": "P7D"
  }
}

Common duration values:

Duration reset behavior: If a new payment is added to the Payment Order while the relative duration window is active, the duration resets. This prevents premature settlement when additional payments are still being collected.

cron

Settle on a recurring schedule defined by a cron expression. The cron follows standard format: minute hour day month weekday. All times are in UTC.

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "settle_schedule": {
    "strategy": "cron",
    "cron_expression": "0 9 * * 1"
  }
}

Example cron expressions:

The next occurrence of the cron expression after the order is closed will be used as the settlement time.

Combining Close Condition and Settle Schedule

Close Condition and Settle Schedule work together to fully automate the lifecycle. The typical flow is:

1. Create Payment Order with close_condition + settle_schedule
2. Payments are added to the order
3. Close condition is met --> order automatically CLOSED
4. Settle schedule triggers --> order automatically SPLIT and SETTLED
5. Funds are ready for disbursement

Example: E-commerce Order (Single Payment, 14-Day Refund Window)

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "close_condition": {
    "condition": "completed_payment_count",
    "count": 1
  },
  "settle_schedule": {
    "strategy": "relative",
    "settle_after": "P14D"
  }
}

The order closes as soon as one payment completes. Settlement occurs 14 days later, giving time for returns and refunds.

Example: Event Ticket Sales (Settle on Event Date)

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "close_condition": {
    "condition": "completed_payment_count",
    "count": 1
  },
  "settle_schedule": {
    "strategy": "absolute",
    "settle_at": "2026-06-15T09:00:00Z"
  }
}

The order closes after payment, but settlement is deferred until the event date when the service is delivered.

Example: Weekly Settlement Batch

POST /api/v1/payment_orders
{
  "currency": "SEK",
  "settle_schedule": {
    "strategy": "cron",
    "cron_expression": "0 9 * * 1"
  }
}

No close condition — the order is closed manually (or via another mechanism). Settlement happens every Monday at 09:00 UTC for any orders closed since the last run.

Manual Override

Even with a settle schedule and close condition configured, you can always call the manual endpoints to close or settle a Payment Order ahead of the automated schedule:

• PUT /api/v1/payment_orders/{payment_order_id}/close — Close immediately
• PUT /api/v1/payment_orders/{payment_order_id}/settle — Settle immediately (with fast_forward: true to close and split in one call)

Summary

Key points to remember:

• Settling is irreversible — refunds are no longer possible after split/settle
• Do not settle before delivery — ensure the product or service has been fulfilled
• Choose a settle_after duration that covers your expected refund/dispute window