Learn how to collect an application fee when processing payments using the Square Payments API.
Payments API and Refunds API

Take Payments and Collect Fees

An application developer can create an application integrated with Square to, for example, process payments on behalf of sellers that sign up to use the application. The developer can collect a portion of each payment that the application processes as the application fee.

Link to section
Overview

The CreatePayment endpoint supports the app_fee_money field. When taking a payment, applications specify this field to collect the application fee. When the payment is complete, the payment amount is credited to the seller's Square account and the application fee is credited to your Square account.

Link to section
Get your application fee money

As application fee money accumulates in your developer account Square Balance, you can transfer it to your linked bank account. You can set up an automatic daily balance transfer which runs about three hours after the close of business hour that you set in your account. You can also use the Square Instant Transfer feature to get your current balance transferred immediately at a cost of 1.5% of the balance to transfer. For more information, see Set Up and Manage Instant Transfers

Note

The application fee cannot be split among multiple Square developer accounts.

Square identifies the seller Square account by reading the access token obtained in the OAuth code flow and used in the CreatePayment request. Your Square developer account is identified by the application ID associated with that access token.

Link to section
Application fee restrictions

The following apply when collecting fees:

  • The developer Square account and seller Square account need to be in the same country where application fees are collected. In addition, the seller location where the application fee is taken must use the same currency as your developer account in that country. For example, if your application is used in Canada and the United States, you must have a developer account in each country. Your Canadian sellers would have a Square account in Canada and take payments in the same currency as your Canadian developer account. Your American sellers would have a Square account in the United States and take payments in the same currency as your American developer account.

  • Applications can collect fees only for card payments (see Take Card Payment). Application fees do not apply when CreatePayment is called to record a cash or external payment because the seller gets money directly from the buyer without being processed by Square.

  • To process payments on behalf of other Square sellers, applications must have necessary permissions. Your application needs to use OAuth to obtain the permissions from sellers and use the OAuth token to authenticate CreatePayment requests. For more information, see Connect your Application to a Seller's Account Using OAuth.

Important

Australia only: Read the Product Disclosure Statement for the Payments API Application Fee (PAAF) service and the Financial Services Guide.

Link to section
Application fee limit

When a developer collects a fee from each payment that Square processes through your application, Square ensures that the seller retains some portion of the payment's total_money after subtracting the Square processing fees and the application fee. The following guidelines apply:

  • When total_money is $5.00 or greater, the maximum allowed application fee percentage is 90%.

  • When total_money is less than $5.00, the maximum allowed application fee percentage is 60%.

This app_fee_money maximum is based on the payment's total_money amount (the sum of amount_money and tip_money). For more information, see Payment.

Link to section
Implementation

The app_fee_money field can be set in either the CreatePayment or RefundPayment request:

  • In a CreatePayment request, app_fee_money indicates the application fee for a payment. Square takes the specified amount from the payment and deposits it in the Square Balance of the developer account.

  • In a RefundPayment request, app_fee_money directs Square to take the specified amount from your developer account to pay for the refund. In the event that your developer account Square Balance is zero (such as immediately after an Instant Transfer), Square takes the refunded application fee directly from your linked bank account.

After receiving a CreatePayment request, Square splits the payment (Square fees, an application fee, and the rest of the funds going to the seller). To understand payment splitting, consider a payment of $20.00 USD that includes an application fee of $2.00 USD. Square first takes its fee. Assuming 2.9% plus a $0.30 USD fee rate, Square receives $0.88 USD, which results in a net amount of $19.12 USD. The application developer receives $2.00 USD from the net amount and the seller receives the remaining $17.12 USD.

A diagram illustrating payment splitting, where the application developer receives a $2 fee from the payment and the seller receives the remainder of the payment.

The following is an example (CreatePayment endpoint) request. In the request:

  • The Authorization header specifies the OAuth access token providing encoded information about the seller and developer accounts.

  • amount_money specifies the amount ($20.00 USD) to charge.

  • app_fee_money specifies $2.00 USD as the application fee.

  • source_id identifies the payment source. The example specifies a card on file as the payment source, which also requires the customer_id in the request.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "ccof:eMXMUau3U9s0Omexample",
    "customer_id": "REK96J96AS5AN2Y8Z4H01example",
    "app_fee_money": {
      "amount": 200,
      "currency": "USD"
    }
  }'
    Try in API Explorer

    After receiving the request, Square takes the $0.88 USD processing fee, deposits the $2.00 USD application fee in the developer account, and deposits the remaining $17.12 USD in the seller account. 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
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    {
  "payment": {
    "id": "AfUqQQo9b932Nbifl1v7example",
    "created_at": "2019-07-23T20:39:19.831Z",
    "updated_at": "2019-07-23T20:39:20.317Z",
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 200,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "MASTERCARD",
        "last_4": "5809",
        "exp_month": 9,
        "exp_year": 2022,
        "fingerprint": "sq-1-..."
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "revUcH"
    },
    "location_id": "7WQ0KXC8ZSD90",
    "order_id": "j0gN8yDiDIrtDteHbEbxIS61Xa4F",
    "customer_id": "REK96J96AS5AN2Y8Z4H01QWYE8",
    "total_money": {
      "amount": 2000,
      "currency": "USD"
    }
  }
}

    You might not see the processing fee immediately in the response. You can use a follow-up GetPayment request to review the payment and processing fee.

    Get Payment
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

Link to section
Refund API Permissions

Square sellers that sign up to use third-party applications must grant the necessary permissions so the application can perform tasks on their behalf. The application developer uses the OAuth flow to obtain the necessary permissions from sellers.

Among other permissions, the application developer must obtain permission for the PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS action. The recommended minimum permissions are:

  • PAYMENTS_WRITE

  • PAYMENTS_READ

  • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

  • ORDERS_READ

  • ORDERS_WRITE

By granting these permissions, Square sellers indicate that the developer is allowed to take a portion of a payment as an application fee. That is, when taking a payment on behalf of these Square sellers (using the Payments API), the application can specify app_fee_money.

Link to section
Disputes and application fee

When there is a payment dispute (see Disputes API) for which the seller is liable for the entire sales amount, the developer keeps their portion of the payment.

Link to section
Tax reporting

Developers collecting application fees should review Square Tax Reporting and Form 1099-K Overview.

Link to section
Related topics

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

On this page