After completing the OAuth walkthrough, you should have a good understanding of the OAuth workflow and how to implement it in the Square Sandbox. To build for production, there are some best practices you should follow for your Square integration. If you plan to build an application for the App Marketplace, you must follow these best practices for your application submission to be accepted.
On this page
The following differences between production and the Square Sandbox include:
Your application must use HTTPS in production. For testing, you can use localhost and HTTP.
In production, the
sessionparameter for the authorization page URL should be set to false. However, the Square Sandbox supports only true.
In the Sandbox, the application ID has a prefix of sandbox at the beginning of the ID.
In the Sandbox, the application secret has a prefix of sandbox.
Sandbox and production endpoints have different base URLs:
Make sure you are using your production ID, secret, and base URL when implementing and running in production.
client_id is required. Make sure you are passing your application's production application ID.
In addition to the
client_id parameter, set the following parameters:
Set 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.
For example, suppose you are building a basic invoicing application that accepts payments from customers on behalf of sellers ( Create Payment), displays payments for customers and sellers ( List Payments and Get Payment), processes refunds ( Refund Payment), and takes an application fee on payments. You need to the following permissions:
The last permission is required on Create Payment 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 Pay Order (
PAYMENTS_WRITE) require multiple permissions. Each endpoint in the Square API Reference lists the permissions required to call it. The Permissions Reference lists all the permissions and the APIs and endpoints they apply to.
If you added any other permissions beyond what your application needs, you need to remove those permissions before submitting 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.
Set session to false. The
session parameter tells the Square authorization page to use the seller's logged in Square session without having to explicitly log in. Your application should set
session to false to force the seller to log in. Many sellers have multiple Square accounts. This helps ensure that the seller is authorizing your application for the correct Square account.
Note that the default is true so you must explicitly set the session parameter to false.
Set state to a cross-site request forgery (CSRF) token. The
state parameter is a string that is passed to the Square authorization page and returned as a
state parameter to the callback 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 callback, 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 parameter is actually required but it defaults to
code so you do not need to specify it. The
code value specifies that the callback receives a code parameter containing the authorization code. The Square OAuth API does not support implicit grants; therefore, specifying
token returns an error.
locale. You can optionally pass a locale 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 it has a specific reason for doing so.
Custom parameters (any parameters not defined in this section) are not passed back to the application's redirect URL.
The Square authorization page can return two forms of parameters to your application's callback URL: authorization allowed and errors.
When the seller chooses Allow on the Square authorization page, it redirects to your application's callback page with a URL that looks like the following:
The URL returns the following parameters:
stateis the CSRF token your application passed in the
stateparameter for the Square authorization page. Use this value to verify this is a valid request.
response_typeis code. This signals that an authorization code was returned.
codeis the authorization code that you use to call Obtain Token.
When there is an error, the callback URL returns the following parameters:
stateis the CSRF token your application passed in the
stateparameter for the Square authorization page.
erroris the error type.
error_descriptionprovides more details about the error.
Choosing the Deny button is an error case. When the seller chooses Deny on the Square authorization page, it redirects to your application's callback page with a URL that looks like the following:
The error value of
access_denied indicates that authorization was denied. The
error_description indicates that the reason for the denial was because the user clicked the Deny button.
OAuth and refresh tokens as well as the application secret have privileged access (or potential to get privileged access) to seller resources. You should use them in a secure environment and protect access to them. Follow these best practices:
OAuth operations should be performed on a secure application server. This includes, for example, calls to Obtain Token to obtain the original OAuth and refresh tokens, subsequent calls to get a new OAuth access token using a refresh token, generating and validating the state parameter, encrypting the tokens and application secret, and revoking a token. Do not store or use OAuth or refresh tokens on web or mobile clients.
OAuth and refresh tokens should be stored encrypted in a secure database. Your application should use a strong encryption standard such as AES. The production encryption keys should not be accessible to database administrators, business analysts, developers, or anyone who does not need them. The tokens that these keys protect can be used to perform actions on behalf of the seller and should be guarded appropriately. The encryption keys should not be stored in source control and only be accessible by server administrators.
Submitting an API request without a valid OAuth access token results in a poor experience for sellers and potentially their customers. In some cases, a seller might be prevented from taking payments. An OAuth access token can be invalid for two main reasons: expiration and revocation.
An OAuth access token expires after 30 days. If your application does not get a new access token, it cannot make calls on behalf of the seller. This can happen if your application does not have a token refresh process, but it can also happen if the call to Obtain Token fails and your application does not detect the failure and does not retry.
To ensure tokens remain in a valid state, Square requires all partner applications to renew at a frequent interval.
Your application must automatically renew OAuth access tokens every seven days or less, regardless of whether the seller is actively interacting with your application. Renewing every seven days or less provides sufficient time to discover and resolve errors. If your application only attempts to refresh tokens near the 30-day expiration date, it increases the risk of missing a failed token refresh and creating a poor experience for sellers or their customers.
Your application should check tokens when they are retrieved from your database to see whether they are older than eight days. If this check fails, it should generate a notification (paging or other alerting mechanism) so that you can address any issues with your renewal logic. Silent token renewal failures result in breaking your application integration and potentially cause an outage for your sellers or their customers.
An OAuth access token can be revoked in two ways:
The seller can disconnect the application through My Applications in the Seller Dashboard. Disconnecting an application calls Revoke Token to revoke all OAuth tokens for the seller.
Your application can call Revoke Token to revoke a particular OAuth token or all OAuth tokens for a seller account.
To ensure a token is valid and not revoked, make a call to List Locations and check the response to confirm validity.
Your application must provide a mechanism for sellers to view the status of their connection with Square (OAuth access token status) and to manage the authorization for your application. Typically, this would be a settings/configuration dashboard in your application.
Your application must accurately show the seller's correct OAuth access token status with Square. OAuth access token status must always be accurate and indicate the correct state of the access token (valid, expired, or revoked). Using the recommendation method in the previous section, your application can check the validity of the token by calling List Locations and checking the response.
Your application must enable the seller to disconnect by revoking the access token. You revoke access tokens using Revoke Token.
When your application uses an OAuth access token to make a call, OAuth-related errors can occur if a token is expired, revoked, or has insufficient scope (unauthorized). Your application should handle these error codes and display a customer-friendly message that clearly communicates the error to the seller, their customer, or both: