Create a PaymentOrder

What is a PaymentOrder?

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

Note: In most of the cases Ping recommends to limit the PaymentOrder to one Successful Payment to give granular control over the payment allocations.

A PaymentOrder moves through several states—OPEN, CLOSED, SPLIT, and SETTLED—each affecting fund availability. We will go into these more in details 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

Response Parameters