Square Platform

Square Platform for Marketplaces and Split Payments

This integration allows for you to use your own Square account where your own application's Square account is used, instead of Foxy's. You may then use Square's ''app_fee_money'' functionality to take fees from the payment that's made from a customer to a connected merchant.

This functionality is only available for Foxy users on the Platform Pro plan, and most of the setup must be done via the API. (For instance, you must set up the Square oauth flow yourself to collect the credentials. Once you have them, you can set them using the Foxy API.)

The basic use case would be for each of your sellers to have a corresponding Template Set + Payment Set in Foxy, with their Square account connected to the Payment Set. This limits one transaction in Foxy to split payments with only one corresponding merchant, but that is a limitation in Square as well. (In other words, you cannot have products from multiple sellers in a cart, and use Square to split the payment between multiple sellers. That's a Square limitation. If you need that functionality, you're better off with a different approach. Please contact us for details.)

Note also that all the documentation and considerations from the non-platform Square integration apply to this integration as well.

Setting Up Square Platform for Foxy

In order to enable it send a POST request to api_url/stores/store_id/hosted_payment_gateways with data in the following format:

{
    "type": "square_platform",
    "test_third_party_key": "{{ Insert refresh token that you obtained via OAuth }}",
    "additional_fields": "{\"expires_at\":\"\",\"location_id\":\"\",\"square_platform_auth\":\"0\",\"square_platform_cards\":\"0\",\"square_platform_platform_application_id\":\"\",\"square_platform_platform_application_secret\":\"\",\"square_platform_split_payment_logic\":\"\",\"test_expires_at\":\"\",\"test_location_id\":\"{{ Insert location id for the payments here }}\",\"test_square_platform_auth\":\"0\",\"test_square_platform_cards\":\"{{ Set this to 1 to enable it }}\",\"test_square_platform_platform_application_id\":\"{{ Insert Square application id here }}\",\"test_square_platform_platform_application_secret\":\"{{ Insert Square application secret here }}\",\"test_square_platform_split_payment_logic\":\"{\\\"total_item_price\\\": {\\\"platform_percentage\\\": 70},\\\"total_tax\\\": {\\\"platform_percentage\\\": 0},\\\"total_shipping\\\": {\\\"platform_percentage\\\": 100}}\"}"
}

If you want to enable a live one, just populate the same fields that don't have the test_ prefix. Note that the additional_fields is JSON stringified, and the square_platform_split_payment_logic is escaped a second time. (Yes, we know that's a bit awkward. It will be tidied up in a future API release.)

The square_platform_split_payment_logic set on the hosted_payment_gateways, made into a proper JSON object, looks like this:

"test_square_platform_split_payment_logic": {
  "total_item_price": {
    "platform_percentage": 70
  },
  "total_tax": {
    "platform_percentage": 0
  },
  "total_shipping": {
    "platform_percentage": 100
  }
}

This allows you to specify default payment splitting logic for the item subtotal, tax, and shipping. For instance, the above example would split 70% of the item subtotal to your platform, 0% of the tax (ie. the merchant assumes all tax liability), and 100% of the shipping to you (which would be appropriate if you're functioning as the fulfillment provider).

You can also override this logic using the pre-payment webhook, which allows you to do custom logic per transaction. This could be useful if you want to take into account your own wholesale prices, or do custom fees based on products, or handle discounts and coupons more specifically. To override, you'd return a payment_logic node (instead of the square_platform_split_payment_logic). Note that you would not stringify the JSON in the webhook response. (We realize this is inconsistent and we hate it too. It'll be tidied in a future API release to avoid stringifying JSON.)

Square's Fees

Square's fees are taken out before the app_fee_money is passed in. Also note that Foxy needs the percentages of each subtotal, which are then calculated out into a decimal value that's passed through. If you want to handle specific amounts, you'll need to back into them with a bit of math using the pre-payment webhook's override.

Testing

Obtaining A Test Account

Sign up for a Sandbox account here: https://squareup.com/

How To Connect Sandbox Account To Foxy

1. Once you've created your account, if you need to, login into SquareUp

2. Go to https://developer.squareup.com/apps

3. Scroll to Sandbox Test Accounts

4. Click on the Launch button for the Sandbox account you want to activate

5. Login into the Foxy admin and go to payment.

6. Make sure which servers do you want to use? in the gateway screen is set to Test servers

7. Go to the Accept payments using your Square account option, check the box, and click the Connect to Square button.

8. Once returned to the Foxy admin with Square successfully connected, select the Payment location and save the configuration. If you're already using an integration that shows a credit card input on the checkout, you'll need to disable that in order to show the Square credit card input.

   If you see the following error when trying to connect:
   You'll want to review the steps just above to make sure that you have a sandbox account with Square and that you've logged into the account and launched the seller test account from the Developer Dashboard in Square.

Important Notes and Caveats

This integration is intended only for advanced users, and requires the Platform Pro plan. Please contact us if you're interested and we'll help walk you through it.