Square

If you are building a FinTech experience for users that collect payments via popular commerce platforms, then Hurdlr's Square integration might be a game changer for your users. The Hurdlr API allows you to connect your own Square Developer account, so that you own the relationship with Square.

1. How it works

Hurdlr's Income Streams API makes it easy for your team to provide income tracking functionality to your users from many different data sources. This multitude of income streams can become unwieldy when there is overlap between the income sources.

For example, if your user is a Square seller who also collects payments outside of Square (e.g. directly into their bank account), then your user will want to have Square and their bank account linked to your platform. But, when Square disburses the income (less its processing fees) into the user's bank account, the result could double count the user's income.

Rest assured, the Hurdlr API takes care of all of the above for you, and your development team will not need to do any Square-specific development. Specifically, in the above scenario, the Hurdlr API will:

a) automatically pull in the user's Square data

b) create business income records for the top-line income that was earned

c) create business expense records for Square's processing fees

d) reconcile transactions that come into the bank against the data from Square, resulting in bank transfer records (as opposed to double counting income, making 1099 reconciliation a breeze).

2. Getting started

If you haven't already done so, you should create a Square Developer account for your company.

3. Complete Square App setup

Once you have created a Square Developer account, in the Apps dashboard, click the "+" icon to add your App.

You will be taken into the "App setup" flow where you will be prompted to enter your App name. Once entered, you will be taken into the App dashboard. In the "OAuth" tab, under "Sandbox Redirect URL", you should add https://redirect.sandbox.hurdlr.com/oAuth/partner/YOUR_HURDLR_CLIENT_ID/square/. Once you are ready to go live in the "Production" environment, you can enable the "Production" toggle on the header. Under "Production Redirect URL", you should add https://redirect.prod.hurdlr.com/oAuth/partner/YOUR_HURDLR_CLIENT_ID/square/.

4. Securely share your Square keys

Under the "Sandbox Redirect URL", you will see Sandbox Application ID and Sandbox Application secret fields. Contact us directly at [email protected] for instructions on how to securely share these two keys.

5. List your app on the Square App Marketplace (optional)

While completing the previous steps are enough to quickly launch your Square integration, if you intend to list your app on the Square App Marketplace, you will need to implement an OAuth Registration endpoint. When a prospective user finds your app on the Square App Marketplace, they will be able to install your app for the first time, which will automatically register them for your app without them needing to manually fill out any info.

1. When the user installs your app from the Square App Marketplace, the Hurdlr API will POST relevant user information to the OAuth Registration URL of your choosing.
2. Upon receiving this user information, your server should parse the user information and determine whether the user has already created an account with your app.
3. If the user already has an account, you can simply respond to the POST request with the redirect_uri representing where the user should be routed.
4. If the user hasn't created an account yet, you should create an account for the user using the information provided in the POST body. You will also want to register the user with the Hurdlr API.
5. Once done, you should respond to the POST request with the Hurdlr access_token and the redirect_uri representing where the user should be routed once the Square App Marketplace registration flow is complete.

6. Next steps

It's as simple as that! Now your customers will be able to receive income (and expenses for processing fees) from Square, directly into the Hurdlr API. If you have not already implemented the Hurdlr Income Streams API nor embedded the Income Dashboard into your product, that is a great next step.