Create the Redirect URL and Square Authorization Page URL
To begin the OAuth process, you need to create two URLs. The first is the redirect URL, which points to your OAuth application that receives the authorization response and that can manage the seller’s access token and refresh token. The second URL is for the seller to use to access the Square authorization page that grants you a set of permissions to use on the seller’s behalf. The response from this authorization page is sent to your redirect URL.
The redirect URL is the endpoint for your application or web page that processes the seller authorization response and manages the seller’s OAuth tokens. You need to add this URL to your application using the Developer Dashboard. The URL must exactly match the endpoint of your application that processes the seller authorization.
There are several requirements for a production redirect URL. These include:
The URL must use HTTPS.
The endpoint must be able to process the GET response from the seller's authorization through the Square authorization web page.
To get your application credentials and set the redirect URL:
Sign in to the Developer Dashboard.
Choose Open for your production application. If you do not have an application set up, see Get Started.
At the top of the page, set the dashboard mode to Production.
In the left pane, choose OAuth.
In the Application ID box, copy and save the application ID for use in the next section.
In the Application Secret box, choose Show, and then copy and save the application secret for use in the next section.
In the Redirect URL box, enter the URL that redirects the seller authorization to your production application.
To begin the process of having a seller authorize your application to act on their behalf, you first create a URL to the Square authorization page with specific parameters. The completed URL looks similar to the following example:
The URL includes the following:
Your application ID. In the URL, this is the
A list of permissions you want the seller to grant to your application. In the URL, this is the
&scopeparameter. Your application should only request permissions for APIs that your application calls and should be the least privileged permissions required by your application. For more information about scoping your permissions request, see the following section.
A Square session login parameter. In the URL, this is the
&sessionparameter. The session parameter determines whether a seller must log in to the Square authorization page. For a production application, this parameter must be set to
falseso that the seller must log in. Many sellers have multiple Square accounts. Requiring the seller to log in helps ensure that the seller is authorizing your application for the correct Square account.
A cross-site request forgery (CSRF) token. In the URL, this is the
&stateparameter. This parameter is a string that is passed to the Square authorization page and returned as a state parameter to the redirect URL defined for your application. A CSRF token is a unique, random, and unpredictable value generated by your application server. When the
&stateparameter is returned to your application's redirect URL, your application should verify the authenticity of the
&statevalue. This technique helps mitigate CSRF attacks. For more information, see section 10.2 of the OAuth 2.0 protocol specification (RFC 6749).
response_type. (optional) In the URL, this is the
&response_typeparameter. This parameter is required by the OAuth 2.0 protocol but its value defaults to
codeso you do not need to specify it. The
codevalue specifies that the authorization response includes a
codeparameter containing the authorization code. The
tokenvalue is no longer supported.
locale. (optional) In the URL, this is the
&localeparameter. You can optionally pass a
localeparameter to force the Square authorization page to present the page using a particular locale. The Square authorization page detects the locale automatically, so this parameter should only be used if your application can definitively determine the preferred locale and has a specific reason for doing so.
A sample Sandbox test URL looks like the following:
A sample production URL looks like the following (note the different base URL):
You provide this URL to the seller. You can do so by creating the URL and sending it from your application, posting it on a web page, or providing it in an email or automated response. For more information about the authorization parameters, see Authorize.
Set the scope to the least privileged permissions required for your application. The
scope parameter is the set of permissions that your application is requesting on the seller's account. Your application should only request permissions for APIs that your application calls and should use the least privileged permissions required. For a complete list of OAuth permissions, see OAuth Permissions Reference.
For example, suppose you are building a basic invoicing application that accepts payments from customers on behalf of the seller (CreatePayment), displays payments for customers and sellers (ListPayments and GetPayment), processes refunds (RefundPayment), and takes an application fee on payments. You need the following permissions:
The last permission is required for
CreatePayment calls if your application takes an application fee that is paid into your developer account. Some specific variations of a call require more permissions. Some calls, such as
PAYMENTS_WRITE), require multiple permissions. Each endpoint in the Square API Reference lists the permissions required to call it. The OAuth Permissions Reference lists all the permissions and the APIs and endpoints they apply to.
If you add other permissions beyond what your application needs, you need to remove those permissions before you submit your application to the App Marketplace.
If you do not set a scope (not recommended), the default is the following:
However, you should not rely on the default scope. You should explicitly set the scope that your application requires.