Migration to 2026-08-24

Introduction

This migration guide outlines the changes introduced in the 2026-08-24 release. This version changes the refund request body, lets you set your own ids on a payment's items, and allows a refund of a payment whose payment order has already settled, where that is enabled on your tenant.

Overview of Changes

New Refund Request Body

The refund request body has changed. It used to take an amount and an order_items list describing what the payment should be left holding after the refund, where the two had to sum to the full payment amount. It now takes an items list saying how much of each item to refund, and the refund amount is their sum.

Before, on 2025-12-09 and earlier:

{
  "amount": 10000,
  "currency": "SEK",
  "reason": "requested_by_customer",
  "order_items": [
    {
      "name": "Test Purchase",
      "amount": 19900,
      "merchant_id": "<MERCHANT-ID>",
      "vat_rate": "0",
      "tags": [],
      "metadata": {}
    }
  ]
}

From 2026-08-24:

{
  "currency": "SEK",
  "reason": "requested_by_customer",
  "items": [
    {
      "id": "00328a14-fd85-4c08-a02b-7ecbeed110d1",
      "amount": 10000
    }
  ]
}

The change exists to make refunds of settled payment orders possible. The old body said what the payment should be left holding. That is enough while the order is still open, because nothing has been allocated yet: the payment is rewritten, and the eventual split allocates less.

Once the order has settled there is nothing left to rewrite. The money is already booked to the merchants, tenants and liquidity accounts named in the split tree, and handing it back to the payer means taking each one's share of the refund from them. Working out those shares needs the refund to say which items it refunds, because an item is what names its recipients and what each of them was settled. The old body carried no ids to match its items against the payment's, so it could not answer that. The new one names items directly.

Older versions keep working. A refund sent on one is carried out the way that version means it, but it cannot refund a settled payment order.

An item may be named once per refund. It can be refunded again in a later refund, but never past its own amount in total.

Item Ids on Initiate Payment

Each entry in order_items on Initiate Payment now accepts an optional id, a UUID4 that must be unique within the payment. Set your own to name an item by an id you already hold, or leave it out and Ping assigns one. The id is returned on the payment, and it is the id you name when refunding that item.

Giving two items of one payment the same id is rejected.

Refunding Items of a Settled Payment Order

A payment order that has SETTLED can now be refunded. Ping reclaims each recipient's share of the refund from the settled funds they still hold, then pays the payer through the original payment provider as usual.

This is off by default and is not self-service. Contact Ping at [email protected] to have it enabled on your tenant. It also requires each recipient to have enough settled funds. A refund whose reclaim cannot be covered is refused before the provider has been asked for anything.

The reclaim is carried on the recipient's next payout as an entry with source: "refund" and a negative amount, so the deduction is visible to whoever reads the payout.

New errors on Refund Payment:

To learn more, see Refunding after settlement and Payouts.

Affected Endpoints

• Refund Payment
• Initiate Payment
• Get Payment