2. Get Allocations

The first step in building the report is to fetch all allocations related to a given disbursement. This data forms the foundation of your report.

What is an allocation?

An allocation represents a portion of a payment that has been assigned to a specific recipient. In the simplest case, a payment may have just one allocation. However, it's more common for a payment to be split into multiple allocations, each directed to a different recipient.

Example

Request

curl --location 'https://sandbox.pingpayments.com/payments/api/v1/allocations?disbursement_id=<YOUR-DISBURSEMENT-ID>' \
--header 'x-api-secret: <YOUR-API-SECRET>' \
--header 'tenant_id: <YOUR-TENANT-ID>'

Note: In this example we filter allocations on disbursement_id, but there are many more possible filters.

Response

{
   "data":[
      {
         "id":"1f179ceb-5b3d-4275-81fc-5af8daaadeae",
         "label":"Sales",
         "metadata":{},
         "reference":"PING*0001",
         "currency":"SEK",
         "amount":1800,
         "payment_id":"6985dd73-9041-4ab8-a0c9-330509366f4e",
         "settled_at":"2025-05-27T08:36:15.978013Z",
         "recipient_type":"merchant",
         "recipient_name":"John Doe",
         "recipient_bank_account":{
            "account_number":"",
            "currency":"SEK",
            ...
         },
         "payment_order_id":"ad15f034-518c-4a31-88af-e700b975169e",
         "merchant_id":"f38aab4a-b09d-4ec1-9cf5-e045af109ee2",
         "disbursement_id":"91a58cfd-048d-433e-87d7-bade023999c5",
         "disbursed_at":"2025-05-27T08:38:30.314601Z",
         "allocated_at":"2025-05-27T08:36:15.934790Z"
      },
      ...
   ],
   "_links":{
      "first":{
         "href":"https://sandbox.pingpayments.com/payments/api/v1/allocations?disbursement_id=<YOUR-DISBURSEMENT-ID>"
      },
      "next":{
         "href":null
      },
      "current":{
         "href":"https://sandbox.pingpayments.com/payments/api/v1/allocations?disbursement_id=<YOUR-DISBURSEMENT-ID>"
      },
      "previous":{
         "href":null
      }
   }
}

Note: The response is paginated. If the disbursement includes many allocations, you may need to follow the _links.next URL until it returns null to retrieve the full list.

Parameters

Request parameters

All the request parameters are provided as query parameters.

Name	Description
`disbursement_id`	The id of a Disbursement.
`payment_id`	The id of a Payment.
`payment_order_id`	The id of a PaymentOrder.
`merchant_id`	The id of a Merchant.
`limit`	Used to set how many allocations to return in a single page.
`starting_after`	Parameter used for pagination through links, should not be set manually.
`ending_before`	Parameter used for pagination through links, should not be set manually.
`ending_before_including`	Parameter used for pagination through links, should not be set manually.

Response parameters

Name	Description
`data`	The list of allocations which matches the provided filter.
`_links`	Links to help navigation through multiple pages of allocations.