What is a Requisition?

Requisition is a concept in Ping which can be used for you(our tenants) to order payouts where you can decide when and what should be disbursed.

How it works

1.0 Creating a requisition

When creating a Requisition you must provide at least one Selection, each Selection can be seen as a filter on what funds should be disbursed. At the moment each selection can include the fields payment_ids, merchant_ids, setteled_at_to, setteled_at_from.

payment_ids - the id's of the payments you want to disburse
merchant_ids - the id's of the merchants you want to disburse
setteled_at_to - Filters only on funds where the PaymentOrder was settled before the given date
setteled_at_from - Filters only on funds where the PaymentOrder was settled after the given date

1.1 Example selection 1

If you want to disburse all funds to the merchant with id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa" you can provide the following selection

{
  merchant_ids: ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa"],
  payment_ids: null
}

1.2 Example selection 2

If you want to disburse a single payment("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb") to all the included merchants you can provide the following selection

{
  merchant_ids: null,
  payment_ids: ["bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb"]
}

1.3 Example selection 3

If you want to disburse a single payment ("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa") to a single recipient("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb") when the payment has multiple recipients

{
  merchant_ids: ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa"],
  payment_ids: ["bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb"]
}

This means that there will still be settlements which belongs to the payment "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa" which won't be included in the payout.

1.4 Example selection 4

If you want to disburse all funds which was settled between two dates

{
  merchant_ids: null,
  payment_ids: null,
  setteled_at_from: "2025-01-01 00:00:00.243629Z",
  setteled_at_to: "2025-01-31 00:00:00.243629Z"
}

2.0 Submitting a requisition

Once you have added your selections you must submit the requisition to approve the result. Once it's approved it will be ready to be disbursed.

Since a selection can result in multiple payouts in the case of multiple recipients it's possible for the payouts to be disbursed at different times. Each time a payout is disbursed you will receive a callback with the requisition and the updated payouts where you will be able to tell which of them has been disbursed.

3.0 Usage

Your requisition flow must be carefully planned. Creating a requisition for a single payment will not be accepted unless there is a valid justification, such as paying a specific invoice.

In most cases, requisitions should be used for making periodic payouts to your merchants.

3.1 Important notes

If providing a reference when creating a requisition, it will be used for all created
If funds belonging to a merchant without a payout account are selected, no payouts will be created, even though the funds were included in the selection

Requisitions