Refund a Payment with an Application Fee

Applies to: Refunds API | Payments API

Learn how to refund payments that include application fees.

Square processes refunds for payments with application fees in two ways:

• The seller initiates the refund through Square Dashboard or Point of Sale.
• Your application initiates the refund through the Refunds API.

By default, Square automatically handles application fee refunds proportionately in both cases.

If the original payment used app_fee_allocations to distribute fees to multiple parties, you can also specify app_fee_allocations on the refund to control how much each party contributes. For more information, see Refund payments with fee allocations.

When processing a refund:

• Square processing fees — Square retains the processing fees from the original transaction.
• Application fees — Square automatically refunds these proportionately:
  • For a full refund, Square refunds the entire application fee.
  • For a partial refund, Square refunds the proportional amount of the application fee.

For example, suppose your application takes a payment of $20.00 USD on behalf of a seller with a $2.00 USD application fee. Square splits the payment as follows:

• $0.88 USD goes to Square (assuming a 2.9% + $0.30 USD processing fee).
• $2.00 USD goes to your Square account as the application fee.
• $20.00 – ($2.00 + $0.88) = $17.12 USD goes to the seller account.

If the buyer requests a partial refund of $15.00 USD (75% of the original payment) and app_fee_money isn't set, Square refunds proportionately:

• $1.50 USD from your Square account (75% of the $2.00 application fee).
• $13.50 USD from the seller account ($15.00 – $1.50 = $13.50 USD).

When using the Refunds API, you can control how much of the application fee is refunded by setting the app_fee_money parameter:

• If you don't set app_fee_money, Square automatically refunds the application fee proportionately (default behavior).
• If you set app_fee_money to a specific amount, Square refunds that exact amount from your developer account.
• If you set app_fee_money to 0, Square doesn't refund any of the application fee.

The following example shows how to specify a custom application fee refund amount. Using the same $20.00 payment with a $2.00 application fee, suppose your application initiates a partial refund of $15.00 USD (75%) and directs Square to take $8.00 USD from your account:

• $8.00 USD from your Square account (the amount you chose to refund).
• $7.00 USD from the seller account.

1. Take a payment. Follow the example in Collect Application Fees to take a payment. In the response:

   • Square splits the payment between the seller and you: $18 for the seller and $2 for you for a total of $20 charged to the buyer.
   • Get the payment ID from the payment you took and use it in the following step.

2. Refund a portion of the payment.

   1. Refund $15.00 USD (75%). The request specifies the app_fee_money parameter directing Square to take $8.00 USD from your Square account toward the refund.

      Refund payment

      cURL

   2. Verify the response and note the refund ID. Use the refund ID in the next step to verify how Square took funds from different parties to pay for the refund. The refund.status might be PENDING immediately after the refund is created. When that status is APPROVED, you can see how the refund is paid.

   3. Send a GetRefund request to see how Square processed the refund.

      Get payment refund

      cURL

      The following is an example response:

      {
        "refund":{
          "id":"MZU5SuSP821fLg9...",
          "status":"COMPLETED",
          "amount_money":{
              "amount":1500,
              "currency":"USD"
          },
          "payment_id":"MZU5SuSP821fLg9hLcfp3797vaB",
          "order_id":"rOnplN8dwaeDfiGa7NKEYgxShb4F",
          "created_at":"2019-07-05T18:56:58.866Z",
          "updated_at":"2019-07-05T19:11:23.766Z",
          "app_fee_money":{
              "amount":800,
              "currency":"USD"
          },
          "location_id":"7WQ0KXC8ZSD90"
        }
      }

If your application subscribes to the refund.updated webhook, it waits for a notification for the completed refund. The notification body carries the updated Refund with the new value of the status field. The following example shows the body of a refund.updated notification:

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "refund.updated",
  "event_id": "bc316346-6691-4243-88ed-6d651a0d0c47",
  "created_at": "2019-07-05T19:11:23.766Z",
  "data": {
    "type": "refund",
    "id": "MZU5SuSP821fLg9...",
    "object": {
      "refund": {
        "id": "MZU5SuSP821fLg9...",
        "created_at": "2019-07-05T18:56:58.866Z",
        "updated_at": "2019-07-05T19:11:23.766Z",
        "amount_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "status": "COMPLETED",
        "location_id": "NAQ1FHV6ZJ8YV",
        "order_id": "rOnplN8dwaeDfiGa7NKEYgxShb4F",
        "payment_id": "MZU5SuSP821fLg9hLcfp3797vaB",
        "version": 10
      }
    }
  }
}

The response shows a total refund of $15.00 USD (amount_money). Square took funds from various parties as follows:

• An application fee refund of $8.00 USD (app_fee_money) is taken from your Square account.
• The amount Square took from the seller account isn't in the response. You need to compute this amount yourself ($15.00 – $8.00 = $7.00 USD).

The following example shows the default behavior when you don't specify app_fee_money. Square refunds the application fee proportionally.

1. Take a payment. Follow the example in Collect Application Fees to take a payment. In the response:
   • Review how Square splits the payment among the parties.
   • Get the payment ID from the payment you took and use it in the following step.
2. Refund a portion of the payment.

   1. Refund $15.00 USD (75%). The request doesn't specify the app_fee_money field.

      Refund payment

      cURL

   2. Verify the response and note the refund ID. Use the refund ID in the next step to verify how Square took funds from different parties to pay for the refund.

   3. Send a GetRefund request to see how Square processed the refund.

      Get payment refund

      cURL

      The following is an example response:

      {
        "refund":{
          "id":"6sqN4XRAx...",
          "status":"COMPLETED",
          "amount_money":{
              "amount":1500,
              "currency":"USD"
          },
          "payment_id":"6sqN4XRAxTtw24LXGycSxKHEuaB",
          "order_id":"9lQuJAYpafsr999GJcNKFiLZbf4F",
          "created_at":"2019-07-05T18:29:24.385Z",
          "updated_at":"2019-07-05T18:41:24.260Z",
          "app_fee_money":{
              "amount":150,
              "currency":"USD"
          },
          "location_id":"7WQ0KXC8ZSD90"
        }
      }

      The response shows a total refund of $15.00 USD (amount_money). Square took funds from various parties as follows:

      • An application fee refund of $1.50 USD (app_fee_money) from your Square account (75% of the original $2.00 application fee).
      • The amount Square took from the seller account isn't in the response. You need to compute this amount yourself using the information in the response ($15.00 – $1.50 = $13.50 USD).

If the original payment used app_fee_allocations to distribute fees to multiple parties, you can use app_fee_allocations on the refund request to specify how much each party contributes to the refund.

The rules for providing app_fee_money and app_fee_allocations on a refund depend on how the original payment was created:

• Payment created with only app_fee_money — The refund can use app_fee_money. You cannot provide app_fee_allocations with multiple locations on the refund.
• Payment created with app_fee_allocations — The refund must use app_fee_allocations. You cannot provide only app_fee_money, because Square doesn't know how to distribute the refund across the original allocation parties.
• Neither provided on the refund — Square refunds fees proportionally from all parties, the same as for single-party refunds.

When providing app_fee_allocations on a refund, the following rules apply:

• The set of locations in the refund allocations must match the set of locations on the original payment. You cannot add new locations or omit existing ones.
• If both app_fee_money and app_fee_allocations are provided, the allocation amounts must sum to the app_fee_money amount.

The following RefundPayment request refunds $10.00 USD from a payment that distributed fees to two parties. Each party contributes $1.00 USD toward the fee refund:

{
  "idempotency_key": "{UNIQUE_KEY}",
  "amount_money": {
    "amount": 1000,
    "currency": "USD"
  },
  "app_fee_money": {
    "amount": 200,
    "currency": "USD"
  },
  "app_fee_allocations": [
    {
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "location_id": "DEVELOPER_LOCATION_ID"
    },
    {
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "location_id": "PARTNER_LOCATION_ID"
    }
  ],
  "payment_id": "PAYMENT_ID"
}

The response includes app_fee_money (the total fee refunded) and app_fee_allocations (the breakdown by party):

{
  "refund": {
    "id": "ZSZHUj6My6yEQWHSvsPliv8jBLZZY_refund",
    "status": "PENDING",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "payment_id": "PAYMENT_ID",
    "created_at": "2026-02-23T18:34:07.559Z",
    "updated_at": "2026-02-23T18:34:07.981Z",
    "app_fee_money": {
      "amount": 200,
      "currency": "USD"
    },
    "app_fee_allocations": [
      {
        "amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "location_id": "DEVELOPER_LOCATION_ID"
      },
      {
        "amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "location_id": "PARTNER_LOCATION_ID"
      }
    ],
    "location_id": "SELLER_LOCATION_ID",
    "destination_type": "CARD"
  }
}