Skip to main content

Partial refunds

Overview​

Partial refunds allow you to return only a portion of the captured payment amount to the buyer, rather than the full amount. This is useful in scenarios such as partial order cancellations, returns of individual items, or adjustments for disputes.

When performing a partial refund, you specify the amount to be refunded and which portion of each split between the parties involved must be returned. Not all payment methods support partial refunds, so always verify the capabilities for the payment method used in the payment methods overview.

For partial refunds:

  • The sum of the amount of all partial refunds cannot exceed the original payment amount.
  • For each partial refund, the amount deducted for each account involved cannot exceed the split amount that account is receiving.

Steps​

1. Create a partial payment refund​

For already captured payments, you can initiate a partial refund by calling the POST api.getpaid.io/v2/payments/{payment_id}/refunds endpoint, specifying the funds to return to the buyer and from which party split the funds are deducted.

POST api.getpaid.io/v2/payments/{payment_id}/refunds
{
  "type": "partial",
  "reference": "RFD-202510-0002",
  "amount": 500,
  "splits": {
    "accounts": [
      {
        "id": "acc_4f5zanqzxfg9w9jj5e81bm6bc9",
        "split": {
          "amount": 450
        }
      },
      {
        "id": "acc_4q90qx2kdczs59yqfq34p09qx6",
        "split": {
          "amount": 50
        }
      }
    ]
  },
  "webhooks": {
    "url": "https://webhooks.titanauto.com/getpaid"
  }
}

2. Handle refund response​

If the refund creation is successful, it returns a unique refund id.

201 Created - POST api.getpaid.io/v2/payments/{payment_id}/refunds
{
  "id": "rfd_4a4m2pjycdb1jbj68h1rvk9kcz",
  "type": "partial",
  "status": "initiated",
  "reference": "RFD-202510-0002",
  "created_at": "2025-10-25T07:11:57.761Z",
  "updated_at": "2025-10-25T07:11:57.761Z"
}

3. Payment refunded
notification​

Once the refund is completed, and the funds are returned to the buyer, your platform server receives a payment_refunded webhook.

payment_refunded webhook
{
  "id": "evt_4yd8tht4hwkpk3g14w4sey01mt",
  "type": "payment_refunded",
  "version": "v2",
  "occurred_at": "2025-10-27T08:01:33.295Z",
  "data": {
    "id": "pay_4kf9v6xp00hzc99rdwr5m97wce",
    "reference": "ORD-202510-0232",
    "refund": {
      "id": "rfd_4a4m2pjycdb1jbj68h1rvk9kcz",
      "reference": "RFD-202510-0002"
    }
  }
}