Introduction

This migration guide explains critical changes made to our list endpoints. The changes are breaking, and thus, mandatory. The previous implementation returned all items in a single response, which caused excessively large payloads for clients retrieving large datasets. The new approach implements pagination to provide better performance, reliability, and scalability.

Important Notice

🚨 Action Required: Clients must migrate to the new version by including the header x-api-version: 2025-03-06 in all list endpoint requests (listed further down). The old version will be supported until April 30th, 2025. After this date, all requests to the old version will be rejected.

Please update your clients as soon as possible to avoid service disruption.

Overview of Changes

• API Versioning
  We are gradually introducing a new versioning model for our API to better facilitate fast and reliable API development. For this first update, clients will have to opt in to use a specific version for our first breaking changes.
• General Request Changes:
  The new pagination mechanism replaces the previous non-paginated approach with cursor-based pagination. Users do not need to populate pagination parameters themselves; pre-filled URLs are provided in the response. The only relevant parameter is limit, which limits the response results, and is capped at 200.
• General Response Changes:
  All list responses are now paginated and follow the following format:
  • data: The list of items for the current result set.
  • _links: An object with pre-filled URLs containing cursor and limit parameters. The keys are:
    • next: The next page URL, null if it's the last page.
    • previous: The previous page URL, null if it's the first page.
    • current: The current page URL.
    • first: The first page URL and original query.
• Get Merchants
  The Get Merchants endpoint now follows the aforementioned paginated list format. It is otherwise unchanged.
• Get Payment Orders
  The Get Payment Orders endpoint now returns a list of stripped-down summarized Payment Order object without their underlying Payments. To get a Payment Order complete with Payments, use the Get Payment Order endpoint. If Payments is the only thing you are concerned with, use the Get Payments endpoint.
• Deprecated: Get Disbursement
  The Get Disbursement endpoint will be deprecated as of this update. In its place, we are introducing a new Get Allocations endpoint. This endpoint can be used to query allocations that is currently included as settlements in the Get Disbursement response object. The same list of settlements can now be retrieved as allocations by supplying a disbursement_id query filter. The Disbursement callback remains unchanged.
• Deprecated: Get PaymentOrders Allocations
  The Get PaymentOrders Allocations endpoint that previously required a Payment Order ID has been replaced by the aforementioned more generalized Get Allocations endpoint. Use the payment_order_id query filter and adjust to handle our new paginated result.

Example Request (New Version)

{
  "data": [
    { "id": "03712afd-5889-415a-86af-dde21fa210c6", ... },
    { "id": "07e03baf-efab-4cb6-a34b-62b9f164ec07", ... }
  ],
  "_links": {
    "next": "https://sandbox.pingpayments.com/payments/api/v1/payment_orders?limit=20&starting_after=03712afd-5889-415a-86af-dde21fa210c6",
    "previous": null,
    "current": "https://sandbox.pingpayments.com/payments/api/v1/payment_orders?limit=20",
    "first": "https://sandbox.pingpayments.com/payments/api/v1/payment_orders?limit=20"
  }
}

Breaking Changes

• Clients that do not follow _links provided in the response will not receive the full dataset.
• Applications expecting all results in a single response must be updated to handle pagination.
• The response structure has changed, requiring updates to response parsing logic.
• Get Payment Orders now returns a stripped-down Payment Order without its underlying Payments.
• Get Disbursement is now deprecated.

Migration Steps

1. Update Clients to Support Pagination:
   • Modify clients to follow URLs provider in the _links object for pagination
   • Update response handling to properly retrieve additional pages if required
2. Adjust Response Parsing Logic
   • Ensure clients can properly parse the new response format, especially when following next or previous links
3. Testing
   • Verify compatibility with the new endpoint structure
   • Ensure edge cases are properly handled
     • Empty pages
     • Last page reached

Affected Endpoints

• Get Merchants
• Get Disbursement
• Get Payment Orders
• Get Payment Order Allocations

New Endpoints

• Get Allocations