# 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](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-762ae3fa23de64b0901e915c628bda29a0e07073%2Fsquare.png?alt=media)

***

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)

***