Applies to: Payments API | Disputes API | OAuth API | Refunds API
Learn how to collect an application fee when processing payments using the Payments API.
You can create an application integrated with Square to process payments on behalf of sellers that sign up to use the application. You can collect a portion of each payment that your application processes as an application fee.
The CreatePayment endpoint supports the app_fee_money field. When taking a payment, applications set this field to collect an 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.
The Square account that receives application fees in a payment or has application fees taken in a refund is your account, as the developer of the application. It's the Square account that you sign in to when you're accessing the Developer Dashboard. Application fees aren't deposited in a seller's Square account. The Seller Dashboard for your account gives you a report of application fees received for a given period. For more information see Application fee reporting.
Note
The application fee cannot be split among multiple Square accounts.
When there is a payment dispute (see Disputes API) for which the seller is liable for the entire sales amount, you keep your portion of the payment.
As application fee money accumulates in your Square account, you can transfer it to your linked bank account. You can set up an automatic daily balance transfer, which runs about 3 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 transfer amount. For more information, see Set Up and Manage Instant Transfers.
Square identifies the seller's Square account by reading the access token obtained in the OAuth code flow and used in the CreatePayment
request. Your Square account is identified by the application ID associated with that access token.
Important
Developers collecting application fees should review Square Tax Reporting and Form 1099-K Overview.
The following restrictions apply when collecting fees:
Your 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 Square account in that country. For example, if your application is used in Canada and the United States, you must have a Square account in each country. Your Canadian sellers would have a Square account in Canada and take payments in the same currency as your Canadian Square account. Your US sellers would have a Square account in the United States and take payments in the same currency as your US Square account.
Applications can collect fees for the following payments:
- Card payments (see Card Payment)
- Cash App Pay payments with
source_type: WALLET
- Afterpay payments with
source_type: BUY_NOW_PAY_LATER
- ACH bank transfers with
source_type: BANK_ACCOUNT
Application fees don't 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 the 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 OAuth API.
Important
Australia only: Read the Product Disclosure Statement for the Payments API Application Fee (PAAF) service and the Financial Services Guide.
When you collect 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.
The app_fee_money
field can be set in 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 your Square account. - In a
RefundPayment
request,app_fee_money
directs Square to take the specified amount from your Square account to pay for the refund. In the event that your Square account 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. You receive $2.00 USD from the net amount and the seller receives the remaining $17.12 USD.
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 Square account and your Square account.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 thecustomer_id
in the request.Create payment
After receiving the request, Square takes the $0.88 USD processing fee, deposits the $2.00 USD application fee in your Square account, and deposits the remaining $17.12 USD in the seller account. The following is an example response:
{ "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
Square sellers that sign up to use third-party applications must grant the necessary permissions so the application can perform tasks on their behalf. Use the OAuth flow to obtain the necessary permissions from sellers.
Among other permissions, you must obtain permission for the PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
action. The recommended minimum permissions are as follows:
PAYMENTS_WRITE
PAYMENTS_READ
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
ORDERS_READ
ORDERS_WRITE
By granting these permissions, Square sellers indicate that you're 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
.