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.
Create the 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.
Choose Save.
Create the URL to the Square authorization page
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:
https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&state=82201dd8d83d23cc8a48caf52b
The URL includes the following:
Your application ID. In the URL, this is the
client_id
parameter.A list of permissions you want the seller to grant to your application. In the URL, this is the
&scope
parameter. 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
&session
parameter. The session parameter determines whether a seller must log in to the Square authorization page. For a production application, this parameter must be set tofalse
so 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
&state
parameter. 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&state
parameter is returned to your application's redirect URL, your application should verify the authenticity of the&state
value. 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_type
parameter. This parameter is required by the OAuth 2.0 protocol but its value defaults tocode
so you do not need to specify it. Thecode
value specifies that the authorization response includes acode
parameter containing the authorization code. Thetoken
value is no longer supported.locale. (optional) In the URL, this is the
&locale
parameter. You can optionally pass alocale
parameter 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:
https://connect.squareupsandbox.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&state=82201dd8d83d23cc8a48caf52b
A sample production URL looks like the following (note the different base URL):
https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&state=82201dd8d83d23cc8a48caf52b
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 parameter
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:
PAYMENTS_WRITE
PAYMENTS_READ
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
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 PayOrder
(ORDERS_WRITE
and 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:
MERCHANT_PROFILE_READ
PAYMENTS_READ
SETTLEMENTS_READ
BANK_ACCOUNTS_READ
However, you should not rely on the default scope. You should explicitly set the scope that your application requires.
Related topics
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.