Close, Split & Settle the PaymentOrder

5 minute read

What is Close, Split & Settle?

At this point, the purchase is complete, and the end user should have received a confirmation indicating that their Payment was successful. The associated Payment Order is now in its initial state: OPEN, allowing additional Payments to be created if necessary.

The diagram above illustrates the full lifecycle of a PaymentOrder:

  1. OPEN - Initial state after creation
  2. CLOSED - No futher payments can be added
  3. SPLIT - Allocations are calculated accordingly to Split Tree
  4. SETTLED - Allocations are ready for disbursement

All three lifecycle endpoints accept an optional body parameter:

ParameterTypeDescription
fast_forwardbooleanIf true, Ping will automatically perform all intermediate transitions (e.g. from OPEN directly through to SETTLED).

Next, you’ll invoke each corresponding endpoint—Close, Split, then Settle—in that order.

Close Payment Order

When to use: Once all expected payments have finished processing and you’re certain no additional Psayments will be added to this order.

Once all Payments are complete and you know no new Payments will be added, you can close the PaymentOrder. After closing, no further Payments can be added.

Close request

curl --location --request PUT 'https://sandbox.pingpayments.com/payments/api/v1/payment_orders/<YOUR-PAYMENT-ORDER-ID>/close' \
  --header 'x-api-secret: <YOUR-API-SECRET>' \
  --header 'tenant_id: <YOUR-TENANT-ID>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Split Payment Order

When to use: After the goods or services have been delivered (or similar event has occurred) and you’re ready to calculate and lock in all fee- and partner-allocations.

Note: All Payments within the PaymentOrder must be terminated before you can split the PaymentOrder

Performing the split applies your SplitTree and computes each party’s Allocations (e.g. supplier fees, tenant fees, payment-method fees).

Important: Once the Split is performed the option to perform a refund through the acquiring Payment method is no longer possible.

Split request

curl --location --request PUT 'https://sandbox.pingpayments.com/payments/api/v1/payment_orders/<YOUR-PAYMENT-ORDER-ID>/split' \
  --header 'x-api-secret: <YOUR-API-SECRET>' \
  --header 'tenant_id: <YOUR-TENANT-ID>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Settle Payment Order

When to use: Calling Settle marks the final step in the Payment Order lifecycle. It confirms that the allocation of funds — as calculated by the [Split Tree](Split Tree) — is complete and ready to be paid out.

Once Settled, Ping Payments will disburse the funds to the relevant recipients based on your agreed disbursement schedule.

Note: In most cases, you will call Settle immediately after the Split operation is completed. However, some platforms may choose to delay settlement to perform internal reviews or batch processing.

Settle request

curl --location --request PUT 'https://sandbox.pingpayments.com/payments/api/v1/payment_orders/<YOUR-PAYMENT-ORDER-ID>/settle' \
  --header 'x-api-secret: <YOUR-API-SECRET>' \
  --header 'tenant_id: <YOUR-TENANT-ID>' \
  --header 'Content-Type: application/json' \
  --data '{}'

That’s it! You’ve now created a PaymentOrder, processed and finalized payments, and made the funds available for disbursement.