Refund a Payment with an Application Fee

A seller can initiate a refund request from your application or from a Square product such as the Point of Sale application or Seller Dashboard. The request can be for refunding any amount of the payment. By default, Square gets refund money by taking funds proportionately from all parties.

When using the Refunds API, you can optionally direct Square to take a specific amount from your Square account as the developer's contribution to the refund. For example, you might acknowledge that the refund request was a result of an application error and might choose to contribute more toward the refund. On the other hand, you might not contribute any amount toward the refund.

The way Square takes funds from your Square account depends on whether you set the app_fee_money parameter in the refund request:

• The parameter is set - Square takes your set amount regardless of whether a full or partial refund is requested. If you set the parameter to a zero amount, Square doesn't take any funds from your account.
• The parameter isn't set - On a full refund, your entire application fee is taken from your account. Otherwise, it's taken in proportion to the size of the refund.

The following example describes how a partial refund with app_fee_money works. Suppose your application originally 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:

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

If your application initiates a partial refund of $15.00 USD (75% of the original payment) that directs Square to take $8.00 USD from your account, Square covers the cost of the refund as follows:

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

You can use the following cURL commands to test this scenario:

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).

When a refund request without app_fee_money is received, Square covers the costs proportionally from all parties (developer and seller) as follows:

• Full refund scenario - Square takes the funds that all parties originally received when Square processed the payment and refunds them accordingly.
• Partial refund scenario - Square returns an amount that is less than the original payment. Square processes the partial refund request as follows:
  • Square takes the proportionate amount from your Square account.
  • Square takes the remainder of the refund amount from the seller account.

The following example describes how a partial refund works. Suppose your application originally 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.

Now suppose your application initiates a partial refund of $15.00 USD (75% of the original payment) without app_fee_money in the refund request. Square calculates the cost of the refund as follows:

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

Use the following cURL commands to test this scenario:

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.
      • 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).