CLOSE, SPLIT & SETTLE the PaymentOrder

What is CLOSE, SPLIT & SETTLE?

At this point the purchase is complete and the user should have seen some kind of verification that their purchase was successful and the PaymentOrder is in its initial state, OPEN.

The diagram above illustrates the full lifecycle of a PaymentOrder:

OPEN - Initial state after creation
CLOSED - No futher payments can be added
SPLIT - Allocations are calculated accordingly to SplitTree
SETTLED - Allocation are ready for disbursement

All three lifecycle endpoints accept an optional body parameter:

Parameter	Type	Description
`fast_forward`	boolean	If `true`, Ping will automatically perform all remaining transitions (e.g. from OPEN directly 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 payments 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 allocation (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: Once you’ve split the order and you want to release the allocated funds for disbursement according to your disbursement schedule.

Finally the PaymentOrder can be settled. This is the final step of the PaymentOrder lifecycle. After this the allocations are available for disbursement and Ping will disburse them on agreed upon schedule.

Note: In most cases you’ll call Settle immediately after Split.

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.