Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application. Creating a JDBC data source based on the CData JDBC Driver for Square consists of three basic steps:

• Add the driver JAR file to the classpath. The JAR file is located in the lib subfolder of the installation directory. Note that the .lic file must be located in the same folder as the JAR file.
• Provide the driver class. For example:
  

  cdata.jdbc.square.SquareDriver

• Provide the JDBC URL. For example:
  

  jdbc:square:InitiateOAuth=GETANDREFRESH;OAuthClientId=MyApplicationId;OAuthClientSecret=MyApplicationSecret;CallbackURL=http://localhost:33333;LocationId=MyDefaultLocation
  
  or
  
  jdbc:cdata:square:InitiateOAuth=GETANDREFRESH;OAuthClientId=MyApplicationId;OAuthClientSecret=MyApplicationSecret;CallbackURL=http://localhost:33333;LocationId=MyDefaultLocation

  The second format above can be used whenever there is a conflict in your application between drivers using the same URL format to ensure you are using the CData driver. The URL must start with either "jdbc:square:" or "jdbc:cdata:square:" and can include any of the connection properties in name-value pairs separated with semicolons.

Connecting to Square

Set the LocationId property to specify a default business location. Or, set the LocationId in the search criteria of your query.

To retrieve the Id, query the Locations table after you authenticate.

Authenticating to Square

You can use a personal access token to authenticate to Square or use the OAuth standard. Use a personal token to access your own data or to test through the sandbox. Use OAuth to allow other users to access their own data.

Personal Access Token

Set the OAuthAccessToken connection property to your personal token, which can be obtained by following the steps below:

1. Navigate to the Developer Dashboard and see Create an OAuth App for creation guide.
2. Once the app is created, the token is listed on the Credentials tab.

Square Sandbox

Version 2 of the Connect API allows you to test in a sandbox environment. Transactions created in the sandbox are not sent through to card networks, and cards are never charged.

To connect to the sandbox, set OAuthAccessToken to the sandbox access token, which is available alongside your standard personal access token:

1. Navigate to the Developer Dashboard and see Create an OAuth App for creation guide.
2. Once the app is created, the sandbox token is listed on the Credentials tab.

In addition to OAuthAccessToken, set Schema to "V2", UseSandbox to "True".

OAuth

OAuth requires the authenticating user to interact with Square using the browser. See Connecting to Square for an authentication guide. You can connect without setting any connection properties for your user credentials. After setting InitiateOAuth to GETANDREFRESH, you are ready to connect. When you connect the driver opens the Square OAuth endpoint in your default browser. Log in and grant permissions to the driver. The driver then completes the OAuth process.

1. Extracts the access token from the CallbackURL and authenticates requests.
2. Refreshes the access token when it expires.
3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Note: The driver is already registered with Square as an OAuth application and will automatically use its embedded OAuthClientId and OAuthClientSecret to connect. If you want to use your own custom OAuth app, see Create an OAuth App to obtain these connection properties. In this OAuth flow, you can authenticate without setting any connection properties for your user credentials. Click Connect and the driver opens the Square OAuth endpoint. Log in and grant permissions to the driver. The driver then completes the OAuth process.