You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use this gem to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.
9
+
Use this library to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.
10
+
11
+
## Requirements
12
+
13
+
Use of the Square Java SDK requires:
14
+
15
+
* Java 8 or better
16
+
* Maven or Gradle to build and install the SDK.
10
17
11
18
## Installation
12
19
13
-
Install the gem from the command line:
20
+
### Install with Maven
14
21
15
-
```ruby
16
-
gem install square.rb
22
+
Install the API client library to your local Maven repository:
23
+
24
+
```
25
+
mvn install -DskipTests
17
26
```
18
27
19
-
Or add the gem to your Gemfile and `bundle`:
28
+
**OR**
29
+
30
+
Install the client dynamically by adding a dependency to the POM for your project:
20
31
21
-
```ruby
22
-
gem 'square.rb'
23
32
```
33
+
<dependency>
34
+
<groupId>com.squareup</groupId>
35
+
<artifactId>square</artifactId>
36
+
<version>6.0.0.20200625</version>
37
+
</dependency>
38
+
```
39
+
40
+
### Install with Gradle
41
+
42
+
Install the client by adding the following dependency to the build file for your project:
@@ -82,199 +101,184 @@ First time using Square? Here’s how to get started:
82
101
83
102
1.**Create a Square account.** If you don’t have one already, [sign up for a developer account].
84
103
1.**Create an application.** Go to your [Developer Dashboard] and create your first application. All you need to do is give it a name. When you’re doing this for your production application, enter the name as you would want a customer to see it.
85
-
1.**Make your first API call.** Almost all Square API calls require a location ID. You’ll make your first call to #list_locations, which happens to be one of the API calls that don’t require a location ID. For more information about locations, see the [Locations] API documentation.
86
-
87
-
Now let’s call your first Square API. Open your favorite text editor, create a new file called `locations.rb`, and copy the following code into that file:
88
-
89
-
```ruby
90
-
require'square'
91
-
92
-
# Create an instance of the API Client and initialize it with the credentials
93
-
# for the Square account whose assets you want to manage.
94
-
95
-
client =Square::Client.new(
96
-
access_token:'YOUR SANDBOX ACCESS TOKEN HERE',
97
-
environment:'sandbox'
98
-
)
99
-
100
-
# Call list_locations method to get all locations in this Square account
101
-
result = client.locations.list_locations
102
-
103
-
# Call the #success? method to see if the call succeeded
# The #errors method returns an Array of error Hashes
120
-
result.errors.each do |key, value|
121
-
warn"#{key}: #{value}"
122
-
end
123
-
end
124
-
```
125
-
126
-
Next, get an access token and reference it in your code. Go back to your application in the Developer Dashboard, in the Sandbox section click Show in the Sandbox Access Token box, copy that access token, and replace `'YOUR SANDBOX ACCESS TOKEN HERE'` with that token.
127
-
128
-
**Important** When you eventually switch from trying things out on sandbox to actually working with your real production resources, you should not embed the access token in your code. Make sure you store and access your production access tokens securely.
129
-
130
-
Now save `locations.rb` and run it:
131
-
132
-
```sh
133
-
ruby locations.rb
134
-
```
135
-
136
-
If your call is successful, you’ll get a response that looks like this:
137
-
104
+
1.**Make your first API call.** Almost all Square API calls require a location ID. You’ll make your first call to `listLocations`, which happens to be one of the API calls that don’t require a location ID. For more information about locations, see the [Locations] API documentation.
Yay! You successfully made your first call. If you didn’t, you would see an error message that looks something like this:
144
145
145
-
```
146
-
Error calling LocationsApi.listlocations
147
-
category : AUTHENTICATION_ERROR
148
-
code : UNAUTHORIZED
149
-
detail : This request could not be authorized.
150
-
```
146
+
Next, get an access token and reference it in your code:
151
147
152
-
This error was returned when an invalid token was used to call the API.
148
+
1. Open the Developer Dashboard and select your application. The **Credentials** page for your app opens by default.
149
+
1. Set the dashboard mode to **Sandbox Settings** for a sandbox access token.
150
+
1. Copy the Access Token in the Credentials section of the page and replace `YOUR_SANDBOX_ACCESS_TOKEN` with the token.
153
151
154
-
After you’ve tried out the Square APIs and tested your application using sandbox, you will want to switch to your production credentials so that you can manage real Square resources. Don't forget to switch your access token from sandbox to production for real data.
152
+
**Important** When you eventually switch from trying things out on sandboxto actually working with your real production resources, you should not embed the access token in your code. Make sure you store and access your production access tokens securely.
155
153
156
154
## SDK patterns
157
155
If you know a few patterns, you’ll be able to call any API in the SDK. Here are some important ones:
158
156
159
157
### Get an access token
160
158
161
-
To use the Square API to manage the resources (such as payments, orders, customers, etc.) of a Square account, you need to create an application (or use an existing one) in the Developer Dashboard and get an access token.
162
-
163
-
When you call a Square API, you call it using an access key. An access key has specific permissions to resources in a specific Square account that can be accessed by a specific application in a specific developer account.
159
+
To use the Square API to manage the resources of a Square account (payments, orders, customers, etc.), you need to create an application (or use an existing one) in the Developer Dashboard and get an access token. Access tokens have specific permissions to resources in a specific Square account that can be accessed by a specific application in a specific developer account.
164
160
Use an access token that is appropriate for your use case. There are two options:
165
161
166
-
- To manage the resources for your own Square account, use the Personal Access Token for the application created in your Square account.
167
-
- To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage so that you can work on their behalf. When you implement OAuth, you ask the Square account holder for permission to manage resources in their account (you can define the specific resources to access) and get an OAuth access token and refresh token for their account.
162
+
- To manage the resources for your own Square account, use the **Personal Access Token** for the application created in your Square account.
163
+
- To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage so that you can work on their behalf. When you implement OAuth, you ask the Square account holder for permission to manage resources in their account and get an OAuth access token and refresh token for their account. You define the specific resources you want to access as part of the OAuth call.
168
164
169
165
**Important** For both use cases, make sure you store and access the tokens securely.
170
166
171
167
### Import and Instantiate the Client Class
172
168
173
169
To use the Square API, you import the Client class, instantiate a Client object, and initialize it with the appropriate access token. Here’s how:
174
170
175
-
-Instantiate a `Square::Client` object with the access token for the Square account whose resources you want to manage. To access sandbox resources, initialize the `Square::Client` with environment set to sandbox:
171
+
-Initialize the `SquareClient` with environment set to sandbox:
176
172
177
-
```ruby
178
-
client =Square::Client.new(
179
-
access_token:'SANDBOX ACCESS TOKEN HERE',
180
-
environment:'sandbox'
181
-
)
173
+
```java
174
+
SquareClientclient =newSquareClient.Builder()
175
+
.environment(Environment.SANDBOX)
176
+
.accessToken("SANDBOX ACCESS TOKEN HERE")
177
+
.build();
182
178
```
183
179
184
180
- To access production resources, set environment to production:
185
181
186
-
```ruby
187
-
client =Square::Client.new(
188
-
access_token:'ACCESS TOKEN HERE',
189
-
environment:'production'
190
-
)
182
+
```java
183
+
SquareClientclient =newSquareClient.Builder()
184
+
.environment(Environment.PRODUCTION)
185
+
.accessToken("ACCESS TOKEN HERE")
186
+
.build();
191
187
```
192
-
188
+
193
189
### Get an Instance of an API object and call its methods
194
190
195
191
Each API is implemented as a class. The Client object instantiates every API class and exposes them as properties so you can easily start using any Square API. You work with an API by calling methods on an instance of an API class. Here’s how:
196
192
197
-
- Work with an API by calling the methods on the API object. For example, you would call list_customers to get a list of all customers in the Square account:
193
+
- Work with an API by calling the methods on the API object. For example, you would call listCustomers to get a list of all customers in the Square account:
See the SDK documentation for the list of methods for each API class.
204
201
205
-
Pass complex parameters (such as create, update, search, etc.) as a Hash. For example, you would pass a Hash containing the values used to create a new customer using create_customer:
206
-
207
-
```ruby
208
-
# Create a unique key for this creation operation so you don't accidentally
209
-
# create the customer multiple times if you need to retry this operation.
210
-
require'securerandom'
211
-
212
-
idempotency_key =SecureRandom.uuid
213
-
214
-
# To create a customer, you'll need to specify at least a few required fields.
- Pass complex parameters such as create, update, or search as a model. For example, you would pass a model containing the values used to create a new customer using create_customer:
203
+
204
+
```java
205
+
CustomersApi api = client.getCustomersApi();
206
+
Address address =newAddress.Builder()
207
+
.addressLine1("1455 Market St")
208
+
.addressLine2("San Francisco, CA 94103")
209
+
.build();
210
+
// Create a unique key(idempotency) for this creation operation so you don't accidentally
211
+
// create the customer multiple times if you need to retry this operation.
212
+
// For the purpose of example, we mark it as `unique_idempotency_key`
System.err.println("ApiException when calling API");
228
+
e.printStackTrace();
229
+
}
224
230
```
225
231
226
232
- Use idempotency for create, update, or other calls that you want to avoid calling twice. To make an idempotent API call, you add the idempotency_key with a unique value in the Hash for the API call’s request.
227
233
- Specify a location ID for APIs such as Transactions, Orders, and Checkout that deal with payments. When a payment or order is created in Square, it is always associated with a location.
228
234
229
235
### Handle the response
230
236
231
-
API calls return a response object that contains properties that describe both the request (headers and request) and the response (status_code, reason_phrase, text, errors, body, and cursor). The response also has #success? and #error? helper methods so you can easily determine the success or failure of a call:
232
-
233
-
```ruby
234
-
if result.success?
235
-
p result.data
236
-
elsif result.error?
237
-
warn result.errors.inspect
238
-
end
237
+
If your API call succeeds, Square API returns a response object containing an `HttpContext` that describe both the request and the response. Otherwise, the API throws an `ApiException`:
System.err.println("ApiException when calling API");
248
+
e.printStackTrace();
249
+
}
239
250
```
240
251
241
-
- Read the response payload. The response payload is returned as a Struct from the #data method. For retrieve calls, a Struct containing a single item is returned with a key name that is the name of the object (for example, customer). For list calls, a Struct containing a Array of objects is returned with a key name that is the plural of the object name (for example, customers).
242
-
- Make sure you get all items returned in a list call by checking the cursor value returned in the API response. When you call a list API the first time, set the cursor to an empty String or omit it from the API request. If the API response contains a cursor with a value, you call the API again to get the next page of items and continue to call that API again until the cursor is an empty String.
243
-
244
252
## Tests
245
253
246
-
First, clone the gem locally and `cd` into the directory.
254
+
First, clone the repo locally and `cd` into the directory.
The Square Platform is built on the [Square API]. Square has a number of other SDKs that enable you to securely handle credit card information on both mobile and web so that you can process payments via the Square API.
276
+
The Square Platform is built on the [Square API]. Square has a number of other SDKs that enable you to securely handle credit card information on both mobile and web so that you can process payments via the Square API.
275
277
276
278
You can also use the Square API to create applications or services that work with payments, orders, inventory, etc. that have been created and managed in Square’s in-person hardware products (Square Point of Sale and Square Register).
0 commit comments