# Square

## Square – Connector Configuration

### Step 1: Create a Square Developer Account & Access Developer Portal

* Sign in to your Square account at [Square](https://squareup.com/)
* Navigate to the [Square Developer Portal](https://developer.squareup.com/)
* Create a developer account if you don't have one already

> ⚠️ **Note**: You need a Square business account to access production features. Sandbox is available for development.

***

### Step 2: Create Your Application

1. **Create a new application**:
   * Go to [Developer Dashboard](https://developer.squareup.com/apps)
   * Click **"Create your first application"** or **"+"** to add a new app
   * Fill in the application details:
     * **Application Name** (e.g., "My Payment Integration")
     * **Application Description** - Describe your integration's purpose
2. **Choose Environment**:
   * **Sandbox** - For development and testing
   * **Production** - For live transactions with real money

***

### Step 3: Configure OAuth Settings

1. **Navigate to OAuth Tab**:
   * In your application dashboard, click on **"OAuth"**
   * Configure OAuth settings for secure authentication
2. **Set Redirect URIs**:
   * Add your callback URL in the **"Redirect URL"** field
   * For Appmixer, set the redirect URI to:

```http
https://[YOUR_API_BASE]/auth/square/callback
```

Example:

```http
https://api.appmixer.com/auth/square/callback
```

3. **Configure Permissions**:
   * Select the Square API permissions your app needs:
     * `PAYMENTS_READ` - Read payment information
     * `PAYMENTS_WRITE` - Process payments
     * `ORDERS_READ` - Read order information
     * `ORDERS_WRITE` - Create and update orders
     * `CUSTOMERS_READ` - Read customer profiles
     * `CUSTOMERS_WRITE` - Create and update customers
     * `INVENTORY_READ` - Read inventory information
     * `ITEMS_READ` - Read catalog items

***

### Step 4: Copy Your Credentials

After configuring your application, you'll find your API credentials:

* **Application ID** - Your OAuth application identifier
* **Application Secret** - Your OAuth application secret
* **Access Token** - For server-to-server API calls (if using personal access token)

⚠️ **Important**: Keep your Application Secret secure and never expose it in client-side code!

***

### Step 5: Webhook Configuration (Optional)

If your integration needs real-time updates:

1. **Navigate to Webhooks**:
   * In your application dashboard, click on **"Webhooks"**
   * Click **"Add Endpoint"**
2. **Configure Webhook Settings**:
   * **Notification URL**: Your endpoint to receive webhook notifications
   * **Events**: Select events you want to subscribe to:
     * `payment.created`
     * `payment.updated`
     * `order.created`
     * `order.updated`
     * `customer.created`
     * `customer.updated`
3. **Webhook Security**:
   * Square signs webhook requests with a signature
   * Use the provided webhook signature key to verify authenticity

***

### Step 6: Connector Configuration

1. Go to the Appmixer BackOffice -> Configuration.
2. Add new configuration: `acme:square`.
3. Add your `clientId` (Application ID) and `clientSecret` (Application Secret) keys with values.

![alt text](/files/7slJ3VSg0093DknLPtXO)

***

1. **Test OAuth Flow**:
   * Use your Application ID to initiate OAuth authorization
   * Square authorization URL: `https://connect.squareup.com/oauth2/authorize`
   * Required parameters: `client_id`, `redirect_uri`, `response_type=code`, `scope`
2. **API Testing**:
   * Square API base URLs:
     * **Sandbox**: `https://connect.squareupsandbox.com/`
     * **Production**: `https://connect.squareup.com/`
   * Include `Authorization: Bearer <access_token>` header in requests
   * Test with endpoints like `/v2/locations` to verify authentication

***

### Step 7: Rate Limits

**Rate Limits**:

* **API calls**: 10 requests per second per access token
* **Webhooks**: No specific rate limits, but implement proper handling
* **Payment processing**: Additional limits may apply based on your Square account

***

### Useful Links

* [Square Developer Documentation](https://developer.squareup.com/)
* [API Reference](https://developer.squareup.com/reference/square)
* [OAuth Guide](https://developer.squareup.com/docs/oauth-api/overview)
* [Webhook Documentation](https://developer.squareup.com/docs/webhooks/overview)
* [Rate Limits](https://developer.squareup.com/docs/build-basics/api-lifecycle#rate-limiting)
* [Sandbox Testing](https://developer.squareup.com/docs/testing/sandbox)

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/connector-configuration/square.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.