Create a PaymentOrder

What is a PaymentOrder?

The first step to creating a Payment is to create a PaymentOrder. A PaymentOrder is a container for one or more Payments, and its state determines the availability of acquired funds. Once created, use the returned id to initiate individual Payments and to transition the PaymentOrder through its lifecycle.

Note: In most of the cases Ping recommends limiting the PaymentOrder to a single Successful Payment in order to have granular control over the Payment Allocations. If your case is more complex, we can suggest a different approach of grouping and creating Payments to satisfy the needs of your particular case.

A PaymentOrder moves through several states—OPEN, CLOSED, SPLIT, and SETTLED—each affecting fund availability. We will go into detail explanation of these states later in this guide. For now, just know that initially the PaymentOrder is OPEN and new Payments are ready to be added.

Example

Request

curl -X POST https://sandbox.pingpayments.com/payments/api/v1/payment_orders \
  --header "tenant_id: <YOUR-TENANT-ID>" \
  --header "x-api-secret: <YOUR-API-SECRET>" \
  --header "Content-Type: application/json" \
  --data '{
    "split_tree_id": "<YOUR-SPLIT-TREE-ID>",
    "split_parameters": {},
    "currency": "EUR"
  }'

Response

{
    "id": "6ccbf39e-6075-4565-87c4-c43a0d1a9265"
}

Note: Store the returned ID. You’ll need it to create Payments and to transition the PaymentOrder state.

Parameters

Request Parameters

Name	Description
`split_tree_id`	Determines which Split Tree to use. A Split Tree is a dynamic set of rules describing how the acquired funds should be distributed among parties. The Split Tree will be designed and created in collaboration with your team to make sure it reflects the business agreement between Ping and your organization. The ID will then be provided by Ping during onboarding, and should be tested and verified thoroughly so as to ensure the distribution of funds reflects both Pings and your organization's expectations. The Split Tree can be updated without the need to supply a new ID if the need arises. New IDs for new versions is also possible if, for example, a change in pricing should be applied after a set date.
`split_parameters`	Optional customized parameters to dynamically control parts of the Split Tree. e.g. a dynamic percentage, dynamic fixed fees or simply a switch which toggle certain rules. These can be verified by the split tree to produce errors if values are out of range, are missing, or are ill formated.
`currency`	ISO 4217 currency code for all underlying Payments (e.g. EUR, SEK).

Response Parameters

Name	Description
`id`	The ID of the PaymentOrder.