Learn about refunding payments that included application fees using the Refunds API.
Payments API and Refunds API

Refund a Payment with an Application Fee

A seller can initiate a refund request from your application or the Seller Dashboard. The request can be for refunding the entire original payment or a portion of the payment. By default, Square covers the refund cost by taking funds proportionately from all parties. Note the following:

  • In an application-initiated refund, the developer can optionally direct Square to take a specific amount toward the refund from the developer's account by adding the app_fee_money parameter in the RefundPayment request.

  • A seller can initiate a refund using the Seller Dashboard or a mobile application where the seller does not have the option to specify app_fee_money. Square splits the refund cost proportionately.

In an application-initiated refund, the developer can optionally direct Square to take a specific amount from the developer account as the developer's contribution to the refund. For example, a developer 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, a developer can choose to not contribute any amount toward the refund.

The developer can specify the amount using the app_fee_money parameter in the request. In this case, regardless of whether the request is for a partial or full refund, Square first takes the specified amount from the developer account. Square then does the following to determine the amount that Square and the seller contribute toward the refund:

  • Full refund scenario

    • Refunds the entire processing fee.

    • Takes the remainder of the refund amount from the seller account.

  • Partial refund scenario

    • Computes the processing fee for only the payment amount that remains, keeps that portion, and refunds the rest of the processing fee.

    • Takes the remainder of the funds to complete the refund from the seller account.

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 the developer 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.

Now suppose your application initiates a partial refund of $15.00 USD (75% of the original payment) and specifies the app_fee_money parameter in the refund request that directs Square to take $8.00 USD from the developer account. Square covers the cost of the refund as follows:

  • $8.00 USD from the developer account (the amount the developer chose to refund).

  • $0.43 USD from Square. Square computes the fee for the remaining $5.00 USD ($20.00 USD original payment – $15.00 USD refund = $5.00 USD remaining), which = $0.45 USD. Earlier Square charged $0.88 USD as part of the payment processing. So Square returns the difference of $0.43 USD ($0.88 USD – $0.45 USD).

  • $6.57 USD, the remainder amount ($15.00 – ($8.00 + $0.43) = $6.57 USD), from the seller account.

The following is a graphical illustration of the same scenario:

A diagram illustrating a refund request with an explicit fee and showing the contribution of the developer, Square, and seller.

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

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

    • Square splits the payment between seller and developer.

      • $18 for the seller and $2 for the developer for a total of $20 charged to the buyer.

    • Note the payment ID. Use the payment ID in 2a.

  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 the developer account toward the refund.

      Refund Payment
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      curl https://connect.squareupsandbox.com/v2/refunds \
        -X POST \
        -H 'Square-Version: 2023-01-19' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "payment_id": "MZU5SuSP821fLg9hLcfp3797vaB",
          "amount_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "app_fee_money": {
            "amount": 800,
            "currency": "USD"
          }
        }'
    2. Verify the response and note the refund ID.
      Use the refund ID with the next step to verify how Square took funds from different parties to pay for the refund. The refund.status may be PENDING immediately after the refund is created. When that status is APPROVED, you can see how the refund was paid.

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

      Get Payment Refund
      • 1
      • 2
      • 3
      • 4
      curl https://connect.squareupsandbox.com/v2/refunds/{refund_id} \
        -H 'Square-Version: 2023-01-19' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json'

      Important

      If you have subscribed to the refund.updated webhook, then await a notification for the completed refund. Use that webhook notification to get the Refund. Otherwise, if your GET request returns a refund with status PENDING, you need to wait for Square to complete processing the refund before you can see how the refund was paid.

      The following is an example response:

      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      • 18
      • 19
      • 20
      • 21
      • 22
      • 23
      • 24
      • 25
      • 26
      • 27
      • 28
      • 29
      {
        "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"
          },
          "processing_fee":[
              {
                  "effective_at":"2019-07-05T20:53:53.000Z",
                  "type":"INITIAL",
                  "amount_money":{
                  "amount":-43,
                  "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 $8.00 USD (app_fee_money) from the developer account.

      • A processing fee refund of $0.43 USD (processing_fee) from the Square account.

      Note

      The response shows the processing fee as a negative number (-43) to indicate that Square returned the fee. Square uses the absolute value to calculate the refund amount from the seller.

      • The amount Square took from the seller account is not in the response. You need to compute this amount yourself ($15.00 – ($8.00 + $0.43) = $6.57 USD).

    4. (optional) If you want, you can repeat the exercise to explore a 100% refund, with the app_fee_money parameter in the refund request.

When a refund request without app_fee_money arrives, Square covers the costs proportionally from all parties (developer, seller, and Square) 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:

    • Takes the proportionate amount from the application developer account.

    • Computes the processing fee for only the payment amount that remains, keeps that portion of the fee, and refunds the remainder of the processing fee.

    • Takes the remainder of the refund amount from the balance of the seller.

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 the developer 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 the developer account (75% refund of the application fee).

  • $0.43 USD from Square. Square computes the fee for the remaining $5.00 USD ($20.00 USD original payment – $15.00 USD refund = $5.00 USD remaining), which = $0.45 USD. Earlier Square charged $0.88 USD as part of payment processing. So Square returns $0.43 USD ($0.88 USD – $0.45 USD).

  • $13.07 USD from the seller account ($15.00 – ($1.50 + $0.43) = $13.07 USD).

The following is a graphical illustration of the same scenario:

A diagram illustrating a refund request without an explicit fee, where the original settlement and refund request amounts vary.

Use the following cURL commands to test this scenario:

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

    • Review how Square splits the payment among the parties.

    • Note the payment ID. Use the payment ID in 2a.

  2. Refund a portion of the payment.

    1. Refund $15.00 USD (75%). The request does not specify the app_fee_money field.

      Refund Payment
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      curl https://connect.squareupsandbox.com/v2/refunds \
        -X POST \
        -H 'Square-Version: 2023-01-19' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "payment_id": "6sqN4XRAxTtw24LXGycSxKHEuaB",
          "amount_money": {
            "amount": 1500,
            "currency": "USD"
          }
        }'
    2. Verify the response and note the refund ID. You 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
      • 1
      • 2
      • 3
      • 4
      curl https://connect.squareup.com/v2/refunds/{refund_id} \
        -H 'Square-Version: 2023-01-19' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json'

      Important

      If you have subscribed to the refund.updated webhook, then await a notification for the completed refund. Use that webhook notification to get the Refund. Otherwise, if your GET request returns a refund with status PENDING, you need to wait for Square to complete processing the refund before you can see how the refund was paid.

      The following is an example response:

      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      • 18
      • 19
      • 20
      • 21
      • 22
      • 23
      • 24
      • 25
      • 26
      • 27
      • 28
      • 29
      {
        "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"
          },
          "processing_fee":[
              {
                  "effective_at":"2019-07-05T20:22:54.000Z",
                  "type":"INITIAL",
                  "amount_money":{
                  "amount":-43,
                  "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 the developer account.

      • A processing fee refund of $0.43 USD (processing_fee) from the Square account.

      • The amount Square took from the seller account is not in the response. You need to compute this amount yourself using the information in the response ($15.00 – $1.50 + $0.43) = $13.07 USD).

        Note

        The response shows the processing fee as a negative number (-43) to indicate that Square returned the fee. Square uses the absolute value to calculate the refund amount from the seller.

    4. (optional) If you want, you can repeat the exercise to explore a 100% refund, without app_fee_money in the refund request.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.