CreateOrGetGiftCardAsync(Customer customer, Money amount)
{
// First check for existing gift cards
var searchRequest = new SearchGiftCardsRequest
{
Query = new GiftCardQuery
{
Filter = new GiftCardFilter
{
CustomerId = customer.Id
}
}
};
var searchResponse = await _client.GiftCardsApi.SearchGiftCardsAsync(searchRequest);
if (searchResponse.GiftCards?.Any() == true)
{
var existingCard = searchResponse.GiftCards[0];
// Load additional funds to existing card
var activity = new GiftCardActivity
{
Type = "LOAD",
LocationId = "YOUR_LOCATION_ID",
GiftCardId = existingCard.Id,
LoadActivityDetails = new GiftCardActivityLoad
{
AmountMoney = amount
}
};
var activityRequest = new CreateGiftCardActivityRequest
{
IdempotencyKey = Guid.NewGuid().ToString(),
GiftCardActivity = activity
};
await _client.GiftCardActivitiesApi.CreateGiftCardActivityAsync(activityRequest);
return existingCard;
}
// Create new gift card
var createRequest = new CreateGiftCardRequest
{
IdempotencyKey = Guid.NewGuid().ToString(),
LocationId = "YOUR_LOCATION_ID",
GiftCard = new GiftCard
{
Type = "DIGITAL",
CustomerId = customer.Id
}
};
var createResponse = await _client.GiftCardsApi.CreateGiftCardAsync(createRequest);
var newCard = createResponse.GiftCard;
// Activate the new card with initial balance
var activateActivity = new GiftCardActivity
{
Type = "ACTIVATE",
LocationId = "YOUR_LOCATION_ID",
GiftCardId = newCard.Id,
ActivateActivityDetails = new GiftCardActivityActivate
{
AmountMoney = amount
}
};
var activateRequest = new CreateGiftCardActivityRequest
{
IdempotencyKey = Guid.NewGuid().ToString(),
GiftCardActivity = activateActivity
};
await _client.GiftCardActivitiesApi.CreateGiftCardActivityAsync(activateRequest);
return newCard;
}
```
{% /tab %}
{% tab id="nodejs" %}
```javascript
async createOrGetGiftCard(customer, amount) {
// First check for existing gift cards
const searchRequest = {
query: {
filter: {
customerId: customer.id
}
}
};
try {
const searchResponse = await this.client.giftCardsApi.searchGiftCards(searchRequest);
if (searchResponse.result.giftCards?.length > 0) {
const existingCard = searchResponse.result.giftCards[0];
// Load additional funds to existing card
const activity = {
type: 'LOAD',
locationId: 'YOUR_LOCATION_ID',
giftCardId: existingCard.id,
loadActivityDetails: {
amountMoney: amount
}
};
const activityRequest = {
idempotencyKey: crypto.randomUUID(),
giftCardActivity: activity
};
await this.client.giftCardActivitiesApi.createGiftCardActivity(activityRequest);
return existingCard;
}
// Create new gift card
const createRequest = {
idempotencyKey: crypto.randomUUID(),
locationId: 'YOUR_LOCATION_ID',
giftCard: {
type: 'DIGITAL',
customerId: customer.id
}
};
const createResponse = await this.client.giftCardsApi.createGiftCard(createRequest);
const newCard = createResponse.result.giftCard;
// Activate the new card with initial balance
const activateActivity = {
type: 'ACTIVATE',
locationId: 'YOUR_LOCATION_ID',
giftCardId: newCard.id,
activateActivityDetails: {
amountMoney: amount
}
};
const activateRequest = {
idempotencyKey: crypto.randomUUID(),
giftCardActivity: activateActivity
};
await this.client.giftCardActivitiesApi.createGiftCardActivity(activateRequest);
return newCard;
} catch (error) {
console.error('Error managing gift card:', error);
throw error;
}
}
```
{% /tab %}
{% tab id="python" %}
```python
async def create_or_get_gift_card(self, customer, amount):
# First check for existing gift cards
search_request = {
"query": {
"filter": {
"customer_id": customer["id"]
}
}
}
search_response = await self.client.gift_cards.search_gift_cards(search_request)
if search_response.is_success() and search_response.body.get("gift_cards"):
existing_card = search_response.body["gift_cards"][0]
# Load additional funds to existing card
activity = {
"type": "LOAD",
"location_id": "YOUR_LOCATION_ID",
"gift_card_id": existing_card["id"],
"load_activity_details": {
"amount_money": amount
}
}
activity_request = {
"idempotency_key": str(uuid.uuid4()),
"gift_card_activity": activity
}
await self.client.gift_card_activities.create_gift_card_activity(activity_request)
return existing_card
# Create new gift card
create_request = {
"idempotency_key": str(uuid.uuid4()),
"location_id": "YOUR_LOCATION_ID",
"gift_card": {
"type": "DIGITAL",
"customer_id": customer["id"]
}
}
create_response = await self.client.gift_cards.create_gift_card(create_request)
new_card = create_response.body["gift_card"]
# Activate the new card with initial balance
activate_activity = {
"type": "ACTIVATE",
"location_id": "YOUR_LOCATION_ID",
"gift_card_id": new_card["id"],
"activate_activity_details": {
"amount_money": amount
}
}
activate_request = {
"idempotency_key": str(uuid.uuid4()),
"gift_card_activity": activate_activity
}
await self.client.gift_card_activities.create_gift_card_activity(activate_request)
return new_card
```
{% /tab %}
{% /tabset %}
## Complete example
The following is a complete example showing how to use the service:
{% tabset %}
{% tab id="java" %}
```java
import com.squareup.square.SquareClient;
import com.squareup.square.Environment;
import com.squareup.square.exceptions.ApiException;
import com.squareup.square.models.*;
import java.util.UUID;
public class GiftCardService {
private final SquareClient client;
public GiftCardService(String accessToken) {
client = new SquareClient.Builder()
.environment(Environment.SANDBOX)
.accessToken(accessToken)
.build();
}
public void processCustomerGiftCard(String firstName, String lastName,
String emailAddress, String streetAddress, Money amount) throws ApiException {
// Find or create customer
Customer customer = findOrCreateCustomer(firstName, lastName, emailAddress, streetAddress);
// Create or load gift card
GiftCard giftCard = createOrGetGiftCard(customer, amount);
System.out.println("Gift card processed successfully for customer: " +
customer.getGivenName() + " " + customer.getFamilyName());
System.out.println("Gift card ID: " + giftCard.getId());
}
// ... (include findOrCreateCustomer and createOrGetGiftCard methods from above)
public static void main(String[] args) {
try {
GiftCardService service = new GiftCardService("YOUR_ACCESS_TOKEN");
Money amount = new Money.Builder()
.amount(10000L) // $100.00
.currency("USD")
.build();
service.processCustomerGiftCard(
"John",
"Doe",
"john.doe@example.com",
"123 Main St",
amount
);
} catch (ApiException e) {
System.err.println("Error: " + e.getMessage());
}
}
}
```
{% /tab %}
{% tab id="c#" %}
```csharp
using Square;
using Square.Models;
using System;
using System.Threading.Tasks;
public class GiftCardService
{
private readonly ISquareClient _client;
public GiftCardService(string accessToken)
{
_client = new SquareClient.Builder()
.Environment(Square.Environment.Sandbox)
.AccessToken(accessToken)
.Build();
}
public async Task ProcessCustomerGiftCardAsync(string firstName, string lastName,
string emailAddress, string streetAddress, Money amount)
{
// Find or create customer
var customer = await FindOrCreateCustomerAsync(firstName, lastName, emailAddress, streetAddress);
// Create or load gift card
var giftCard = await CreateOrGetGiftCardAsync(customer, amount);
Console.WriteLine($"Gift card processed successfully for customer: {customer.GivenName} {customer.FamilyName}");
Console.WriteLine($"Gift card ID: {giftCard.Id}");
}
// ... (include FindOrCreateCustomerAsync and CreateOrGetGiftCardAsync methods from above)
public static async Task Main(string[] args)
{
try
{
var service = new GiftCardService("YOUR_ACCESS_TOKEN");
var amount = new Money
{
Amount = 10000, // $100.00
Currency = "USD"
};
await service.ProcessCustomerGiftCardAsync(
"John",
"Doe",
"john.doe@example.com",
"123 Main St",
amount
);
}
catch (ApiException e)
{
Console.Error.WriteLine($"Error: {e.Message}");
}
}
}
```
{% /tab %}
{% tab id="nodejs" %}
```javascript
const { Client, Environment } = require('square');
const crypto = require('crypto');
class GiftCardService {
constructor(accessToken) {
this.client = new Client({
accessToken: accessToken,
environment: Environment.Sandbox
});
}
async processCustomerGiftCard(firstName, lastName, emailAddress, streetAddress, amount) {
try {
// Find or create customer
const customer = await this.findOrCreateCustomer(
firstName, lastName, emailAddress, streetAddress);
// Create or load gift card
const giftCard = await this.createOrGetGiftCard(customer, amount);
console.log(`Gift card processed successfully for customer: ${customer.givenName} ${customer.familyName}`);
console.log(`Gift card ID: ${giftCard.id}`);
} catch (error) {
console.error('Error processing gift card:', error);
throw error;
}
}
// ... (include findOrCreateCustomer and createOrGetGiftCard methods from above)
}
// Usage example
async function main() {
try {
const service = new GiftCardService('YOUR_ACCESS_TOKEN');
const amount = {
amount: 10000, // $100.00
currency: 'USD'
};
await service.processCustomerGiftCard(
'John',
'Doe',
'john.doe@example.com',
'123 Main St',
amount
);
} catch (error) {
console.error('Error:', error);
}
}
main();
```
{% /tab %}
{% tab id="python" %}
```python
from square.client import Client
from square.environment import Environment
import uuid
import asyncio
class GiftCardService:
def __init__(self, access_token):
self.client = Client(
access_token=access_token,
environment=Environment.SANDBOX
)
async def process_customer_gift_card(self, first_name, last_name,
email_address, street_address, amount):
try:
# Find or create customer
customer = await self.find_or_create_customer(
first_name, last_name, email_address, street_address)
# Create or load gift card
gift_card = await self.create_or_get_gift_card(customer, amount)
print(f"Gift card processed successfully for customer: {customer['given_name']} {customer['family_name']}")
print(f"Gift card ID: {gift_card['id']}")
except Exception as e:
print(f"Error processing gift card: {str(e)}")
raise
# ... (include find_or_create_customer and create_or_get_gift_card methods from above)
# Usage example
async def main():
try:
service = GiftCardService('YOUR_ACCESS_TOKEN')
amount = {
"amount": 10000, # $100.00
"currency": "USD"
}
await service.process_customer_gift_card(
"John",
"Doe",
"john.doe@example.com",
"123 Main St",
amount
)
except Exception as e:
print(f"Error: {str(e)}")
if __name__ == "__main__":
asyncio.run(main())
```
{% /tab %}
{% /tabset %}
## Next steps
* Learn more about [managing customer profiles](customers-api/what-it-does).
* Explore how to [manage gift cards on file](gift-cards/manage-gift-cards-on-file).
* Learn about [reloading gift cards](gift-cards/reload-gift-cards).
---
# Managing Duplicate Customers in Square API Integration
> Source: https://developer.squareup.com/docs/customers-api/duplicated-customers
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how Square handles duplicated customers and how your application should handle merged duplicate customers using the Customers API
**Applies to:** [Customers API](customers-api/what-it-does) | [Cards API](cards-api/overview) | [Loyalty API](loyalty-api/overview)
Customer records in Square's system may contain duplicates that accumulate over time. These duplicates can originate from various sources, including Square API integrations and Square's own products. Your application needs to implement a robust strategy for handling duplicates.
## Key Challenges
When developing your application, you need to account for several customer data scenarios. Your system must handle search requests that return multiple records for the same customer, recognizing that these duplicates can arise from various, sometimes untraceable sources. Additionally, since duplicate customer records may be merged over time, your application should implement special handling procedures to manage these consolidated profiles effectively.
## Avoid duplicating customers
To prevent customer duplication, carefully search for existing customers before creating new ones. This search should use unique identifiers such as email addresses and phone numbers to identify potential matches. Furthermore, when processing payments, include the `customer_id` in your requests whenever it's available, as this makes Square use your customer instead of searching for a match and then creating a new customer if the search doesn't turn up a customer.
## Duplicate Detection
Your application might encounter customer duplication even after you've implemented best practices to avoid duplicating customers. To catch potential duplication before adding a new customer, implement these practices:
- Check for similar customer records using available identifiers
- Compare key fields like name, email, and phone number
- Consider fuzzy matching for slight variations in contact details
## Customer Merge Operations and Data Integrity Guidelines
Proper handling of customer record merges is crucial for maintaining data integrity across Square's ecosystem, as these operations affect multiple interconnected services and resources.
### Supported Merge Methods
Square handles duplicate customer profiles through two methods: sellers can manually merge duplicates through the Square Dashboard, or Square can perform automatic merges. In both cases, when a merged customer's ID is requested via the Customer API, Square maintains the original records but returns the new merged customer ID, ensuring all references remain valid.
{% aside type="important" %}
Customer profiles that have been merged into a new profile are never returned by the Customers API. To get objects related to the merged customer profiles, you need to detect customer merges and store the merged IDs.
{% /aside %}
### Important: Preserving Customer Relationships
While it may seem possible to use the Customers API to merge customers by:
1. Creating a new customer
2. Copying profile data
3. [Deleting the old customer](customers-api/use-the-api/keep-records#delete-customer-profiles)
This approach will **break** existing relationships because:
- Customer IDs are used as foreign keys in many Square resources:
- Payments
- Orders
- Loyalty Programs
- Gift Cards
- Subscriptions
- Invoices
- Custom attributes
{% aside type="important" %}
When you delete a customer, these relationships become orphaned and **cannot** be redirected to a new customer ID.
{% /aside %}
.
## Detect merged customer profiles
When Square merges duplicate customer profiles, your application needs to maintain mappings to access resources associated with merged customers. Here's how to implement this:
### Detection Methods
1. **Webhook Events**
- Listen for [customer.created](https://developer.squareup.com/reference/square/customers-api/webhooks/customer.created) events
- Check [CustomerCreatedEventObject](https://developer.squareup.com/reference/square/objects/CustomerCreatedEventObject).event_context
- If created by merge, the context will indicate this
2. **API Response Analysis**
- When calling [RetrieveCustomer](https://developer.squareup.com/reference/square/customers-api/retrieve-customer)
- Compare the returned customer ID with your request ID
- If IDs differ but email/phone match, a merge occurred
### Maintain a merge mapping
In the following implementation examples, a seller had two sets of duplicated customers. Their IDs are represented by the following lists:
* `["previous_id_A", "previous_id_B"]`
* `["previous_id_C", "previous_id_D", "previous_id_E"]`.
Two new customer profiles created from the merge operations:
* `"new_customer_id_1"`
* `"new_customer_id_2"`
Any Customer API responses for these customers after the merge return only these new profile IDs.
The seller used the Square Dashboard to merge these customers into new customer profiles which generated a [customer.created](https://developer.squareup.com/reference/square/customers-api/webhooks/customer.created) webhook event for each merge. The application's webhook handler updated a dictionary by adding the ID of the profile the duplicates were merged into and the IDs of the duplicates. In the following example dictionary, the results of the two merges are recorded.
### Store Customer ID Mappings
Maintaining a dictionary of merged customer profiles:
```json
{
"new_customer_id_1": ["previous_id_A", "previous_id_B"],
"new_customer_id_2": ["previous_id_C", "previous_id_D", "previous_id_E"]
}
```
### Resource Lookup Logic
When searching for customer-associated resources (e.g., orders), the application needs to find all resources that reference the current customer profile and those that reference the old merged customer profiles.
The following [Square Python SDK](sdks/python) example uses the merged customer profile dictionary to find all orders for current ID and any ID merged into the new profile:
1. **Get all customer IDs** - Look the current customer ID up in the dictionary and return all related customer IDs
(both current and previous)
1. **Get all orders** - Search for all orders associated with a customer, including orders linked to their previous profiles
```python
from square import Square
import os
from typing import List, Dict, Any
def get_all_related_customer_ids(current_id: str, id_mapping: Dict[str, List[str]]) -> List[str]:
"""
Given a current (post-merge) customer ID, return all related customer IDs
(both current and previous)
Args:
current_id: The current customer profile ID
id_mapping: Dictionary mapping new IDs to lists of previous IDs
Returns:
List of all related customer IDs (current ID + all previous IDs)
"""
# Start with the current ID
all_ids = [current_id]
# Add any previous IDs associated with this current ID
if current_id in id_mapping:
all_ids.extend(id_mapping[current_id])
return all_ids
def search_customer_orders(
current_id: str,
id_mapping: Dict[str, List[str]],
location_ids: List[str],
client: Square
) -> List[Dict[str, Any]]:
"""
Search for all orders associated with a customer, including orders
linked to their previous profiles
Args:
current_id: The current (post-merge) customer profile ID
id_mapping: Dictionary mapping new IDs to lists of previous IDs
location_ids: List of Square location IDs to search
client: Initialized Square client
Returns:
List of all orders found across all related customer profiles
"""
# Get all customer IDs (current and previous)
customer_ids = get_all_related_customer_ids(current_id, id_mapping)
# Create the search query with customer filter
search_query = {
"filter": {
"customer_filter": {
"customer_ids": customer_ids
}
},
"sort": {
"sort_field": "CLOSED_AT",
"sort_order": "DESC"
}
}
try:
# Search orders using the Square SDK
result = client.orders.search(
body={
"location_ids": location_ids,
"query": search_query
}
)
if result.is_success():
return result.body.get('orders', [])
else:
print(f"Error searching orders: {result.errors}")
return []
except Exception as e:
print(f"Exception when searching orders: {str(e)}")
return []
# Example usage:
def main():
# Initialize the Square client
client = Square(
access_token=os.environ.get("SQUARE_TOKEN"),
environment='sandbox' # Use 'production' for production environment
)
# Example mapping of new IDs to previous IDs
id_mapping = {
"NEW_ID_1": ["OLD_ID_A", "OLD_ID_B"],
"NEW_ID_2": ["OLD_ID_C", "OLD_ID_D"]
}
# Example location IDs - replace with actual location IDs
location_ids = ["057P5VYJ4A5X1", "18YC4JDH91E1H"]
# Search for all orders, including those from previous profiles
orders = search_customer_orders(
current_id="NEW_ID_1",
id_mapping=id_mapping,
location_ids=location_ids,
client=client
)
# Process the orders
for order in orders:
print(f"Order ID: {order.get('id')}")
# Process other order fields as needed
```
{% aside type="tip" %}
You should update your ID mappings immediately when detecting merges to maintain data consistency.
{% /aside %}
## Loyalty reward programs
The process for handling loyalty reward programs associated with duplicate customers is a little complex and needs to be explained.
### Loyalty Account Merging Rules
The way loyalty accounts are handled depends on how a customer profile merge happened. A seller can use the Square Dashboard to manually merge customers or ask Square to automatically merge duplicated customers. The rules are as follows:
- **Manual merges** - When a seller merges two customer profiles that both have loyalty accounts:
- Seller selects which phone number to retain
- Activity from both loyalty accounts combines into the selected account. The `loyalty_account.mapping.phone_number` remains the same.
- **Automatic Merges** - Automatic merging can occur only when:
- One profile has a loyalty account
- The other profile has no loyalty account
- Existing loyalty account gets the new `loyalty_account.customer_id`
{% aside type="important" %}
Square will never automatically merge two profiles that both have loyalty accounts. This prevents accidental combination of active loyalty programs.
{% /aside %}
---
# Ruby SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/ruby/migration
> Status: PUBLIC
> Languages: All
> Platforms: All
Upgrade from the legacy version of the Square Ruby SDK to version 43.0.0 or later.
Version `44.0.0.20250820` of the Ruby SDK represents a full rewrite of the SDK, with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `43.0.1.20250716` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
The new version of the Ruby SDK introduces breaking changes in the client class.
{% table %}
* Legacy {% width="165px" %}
* New {% width="180px" %}
* Additional information
---
*
*
*
---
* `access_token`
* `token`
* The access token used for authentication.
---
* `custom_url`
* `base_url`
* The base URL for API requests.
---
* `square_version`
* `version`
* The Square API version to use.
---
* `additional_headers`
* `additional_headers`
* Additional headers can be set at individual methods.
---
* `timeout`
* `timeout`
* The default HTTP timeout when invoking an endpoint.
---
* `environment`
* `environment`
* This option has been removed. Set the environment in `base_url` instead.
---
* `retry_interval`
* Removed
* This option has been removed.
---
* `backoff_factor`
* Removed
* This option has been removed.
---
* `retry_statuses`
* Removed
* This option has been removed.
---
* `retry_methods`
* Removed
* This option has been removed.
---
* `http_call_back`
* Removed
* This option has been removed.
---
* `bearer_auth_credentials`
* Removed
* This option has been removed.
---
* `user_agent_detail`
* Removed
* This option has been removed.
---
* `config`
* Removed
* This option has been removed.
{% /table %}
```ruby
// LEGACY
require 'square_legacy'
client = Square::LegacyClient.new(
bearer_auth_credentials: BearerAuthCredentials.new(
access_token: ENV['SQUARE_ACCESS_TOKEN']
),
environment: 'sandbox'
)
// NEW
require 'square'
client = Square::Client.new(
base_url: Square::Environment::PRODUCTION,
token: 'YOUR_API_KEY'
)
```
## Use the legacy and new SDK side by side
While the new SDK has many improvements, it takes time to upgrade when there are breaking changes. To make the migration easier, the old SDK is published as `square_legacy` so that the two SDKs can be used side by side in the same project.
The following example shows how to use the new and legacy SDKs inside a single file:
```ruby
require 'square'
require 'square_legacy'
client = Square::Client.new(token: 'YOUR_API_KEY')
legacy_client = Square::LegacyClient.new(
bearer_auth_credentials: BearerAuthCredentials.new(
access_token: ENV['SQUARE_ACCESS_TOKEN']
),
)
# List all payments with the new client.
new_response = client.payments.list()
# List all payments with the legacy client.
legacy_response = legacy_client.payments.list_payments()
```
You should migrate to the new SDK using the following steps:
1. Upgrade the gem to `^44.0.0`.
2. Run `gem install square.rb`.
3. Search and replace all requires from `square` to `square_legacy`.
4. Gradually move over to use the new SDK by importing it from the `square` module.
## Strongly-typed requests and responses
The previous version of the SDK had no strong typing, so users had to craft payloads without any help from autocomplete. The newly generated SDK comes with YARD documentation and RBS types so that developers can let their IDE guide them.
```ruby
// LEGACY
result = client.customers.create_customer(body: {
"given_name": "John",
"family_name": "Smith",
"address": {
"address_line_1": "500 Electric Ave",
"address_line_2": "Suite 600",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "98100",
"country": "US"
}
})
// NEW
result = client.customers.create(body: {
"given_name": "John",
"family_name": "Smith",
"address": {
"address_line_1": "500 Electric Ave",
"address_line_2": "Suite 600",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "98100",
"country": "US"
}
})
```
While the before and after code snippets remain similar, the experience of writing in an editor is quite different.
## Exceptions
The legacy SDK represents successful calls and errors with the same `ApiResponse` type. Users could distinguish between successes and errors as shown:
```ruby
// LEGACY
result = customers_api.create_customer(body: body)
if result.success?
puts result.data
elsif result.error?
warn result.errors
end
```
The new SDK represents errors as `Exceptions`, all of which inherit from the `SquareError` class.
```ruby
begin
result = customers_api.create_customer(body: body)
rescue Square::SquareError => e
puts("The server could not be reached")
puts(e.cause)
end
```
## Auto-pagination
Square's paginated endpoints now support auto-pagination with an iterator. Callers don't need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.
The following example shows the same code, with the legacy and new SDKs:
```ruby
page = client.customers.list(
body: {
limit: 10,
sort_field: 'DEFAULT',
sort_order: 'DESC'
}
)
page.auto_paging_each do |customer|
puts(customer.id)
```
---
# Manage Menus
> Source: https://developer.squareup.com/docs/catalog-api/manage-menus
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to manage menus with the Catalog API and catalog categories.
**Applies to:** [Catalog API](catalog-api/what-it-does)
{% subheading %}Learn how to manage menus with the Catalog API and catalog categories.{% /subheading %}
{% toc hide=true /%}
## Overview
This guide walks you through syncing menus using the Square Catalog API, for example, to display a seller's offerings in your kiosk, mobile application, or online ordering site. You'll also learn how to create root menu categories and organize menus for different services, such as breakfast and lunch.
When a seller [creates a menu](https://squareup.com/help/us/en/article/6424-create-menus-with-square-for-restaurants) through the Square Dashboard, the system automatically creates [catalog categories](https://developer.squareup.com/reference/square/objects/CatalogCategory) with a `CategoryType` of `MENU_CATEGORY`. These categories are used to organize items in the seller's menu and are distinct from regular catalog categories.
Key points about menu categories:
- Automatically created when sellers build menus in the Square Dashboard.
- Have a `category_type` of `MENU_CATEGORY`.
- Used specifically for menu organization.
- Like regular categories, can have parent-child relationships.
- Can be used across different sales [channels](channels-api).
{% aside type="info" %}
When working with catalog categories, your application needs to handle two distinct types: `REGULAR_CATEGORY` and `MENU_CATEGORY`. If your application already has logic that processes `REGULAR_CATEGORY` objects, maintain this logic separately from any new code that handles `MENU_CATEGORY` objects.
`REGULAR_CATEGORY` objects continue to be essential for critical business operations, including:
- Generating sales reports for menu items.
- Routing orders to kitchen printers.
Even if you implement support for `MENU_CATEGORY`, don't remove or modify your existing `REGULAR_CATEGORY` handling. Both category types serve different purposes and should coexist in your application.
{% /aside %}
## Requirements
- A Square account with Square Free, Plus, and Premium subscribers with advanced restaurant capabilities added.
- A Square account with full service, quick service, or bar mode enabled in the Square Point of Sale application.
- Your Square application credentials.
- Authorization to use the [Square Catalog API](catalog-api/what-it-does).
## Syncing menus with your application
When integrating with your application or other external systems, you need an efficient way to sync menu data. This section covers both the initial sync and incremental updates.
### Get menu channels
`CatalogCategory` objects handle location visibility differently than other `Catalog` objects. Instead of direct location assignment, they use channels as an abstraction layer:
- [Channel](https://developer.squareup.com/reference/square/objects/Channel) objects act as the bridge between menu categories and locations.
- Each [Location](https://developer.squareup.com/reference/square/objects/Location) has a corresponding channel (identified by `reference.type = "LOCATION"`).
- Menu categories declare visibility by listing channel IDs in their `channels` array.
**To synchronize menus for a specific location:**
1. Get the channel ID for your target location.
2. Filter menu categories to include only those referencing that channel.
3. Sync only these filtered categories to ensure location-specific accuracy.
for more information about mapping channels to locations, see [Channels API - Menu visibility](channels-api#menu-visibility).
### Initial sync
In the following examples, a restaurant creates a breakfast menu and lunch menu. Each menu has a root category and child categories. The breakfast beverages menu has a submenu for coffee drinks.
To perform a complete menu sync with an external service (such as a delivery platform), you need three specific API calls to get all menu-related catalog objects in the correct hierarchy.
#### Get the root menu categories
{% tabset %}
{% tab id="Request" %}
First, use [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) to get all top-level menu categories for the channel you want to sync. The query uses three filters:
* `exact_query` is set to the category type of menu.
* `set_query` is set to the channels you want to return.
* `range_query` limits the returned menu to root menus.
````
This returns `CatalogCategory` objects that are both top-level categories and menu categories. These objects form your root menu structure.
{% aside type="info" %}
The `present_at_all_locations` property might be set to `true` or `false` but because menu visibility is controlled by the `channels` property, this property has no effect.
{% /aside %}
{% /tab %}
{% tab id="Response" %}
The `SearchCatalogObjects` endpoint returns any root menus that are visible in the specified channel.
{% aside type="info" %}
The `set_query` doesn't exclude catalog categories whose channel list includes other channels too. For this reason, your query might return catalog categories that are visible in the desired channel and also in other channels.
{% /aside %}
```json
{
"objects": [
{
"type": "CATEGORY",
"id": "3H3ADZMYJU6U27JYO2PZFANQ",
"updated_at": "2025-08-06T07:21:55.923Z",
"created_at": "2025-06-02T18:24:46.958Z",
"version": 1754464915923,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Breakfast menu",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 137439154960
},
"is_top_level": true,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o",
"CH_94EExem5ysllXKniR9W0uEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"ecom_seo_data": {
"page_title": "",
"page_description": "",
"permalink": ""
}
}
},
{
"type": "CATEGORY",
"id": "H462U4DGLLEGU34OS4LLLNJQ",
"updated_at": "2025-08-06T07:21:56.451Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1754464916451,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Lunch Menu",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 343597585168
},
"is_top_level": true,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_94EExem5ysllXKniR9W0uEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false
}
}
],
"latest_time": "2025-10-16T20:01:53.649Z"
}
```
{% /tab %}
{% /tabset %}
#### Get the child menu categories
Get all of the descendants of the root categories.
{% tabset %}
{% tab id="Request" %}
Next, use [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) to get all child categories under these root categories:
````
This returns all categories that are both menu categories (`category_type = "MENU_CATEGORY"`) and have their `root_category_id` set to one of the IDs from the first call.
{% /tab %}
{% tab id="Response" %}
The response in the following example shows all breakfast and lunch menu categories.
```json
{
"objects": [
{
"type": "CATEGORY",
"id": "SBT57VC6BCTZ523HYBQ5DSPH",
"updated_at": "2025-06-02T22:03:50.87Z",
"created_at": "2025-06-02T18:24:46.958Z",
"version": 1748901830870,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Pastries",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "3H3ADZMYJU6U27JYO2PZFANQ",
"ordinal": 0
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
}
},
{
"type": "CATEGORY",
"id": "JLIE5PQIE7LEFVN5DZUL72RX",
"updated_at": "2025-06-02T22:03:50.87Z",
"created_at": "2025-06-02T18:24:46.958Z",
"version": 1748901830870,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Breakfast Sandwiches",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "3H3ADZMYJU6U27JYO2PZFANQ",
"ordinal": -68719476736
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
}
},
{
"type": "CATEGORY",
"id": "H5P6BRQKWKL6BDZKIS4FGPSM",
"updated_at": "2025-06-02T22:03:50.87Z",
"created_at": "2025-06-02T21:46:40.409Z",
"version": 1748901830870,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages",
"image_ids": [
"ABHX2WBOQMGTSQ5QOVIYWGPQ"
],
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "3H3ADZMYJU6U27JYO2PZFANQ",
"ordinal": 68719476736
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ",
"ecom_seo_data": {
"page_title": "",
"page_description": "",
"permalink": ""
}
}
},
{
"type": "CATEGORY",
"id": "ZTVXYFS633S6GSLMHVP5O5IG",
"updated_at": "2025-06-02T22:04:56.684Z",
"created_at": "2025-06-02T22:04:56.898Z",
"version": 1748901896684,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Coffee-drinks",
"image_ids": [
"BAXRGSINXCHS7RW4ZMQSHGGL"
],
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "H5P6BRQKWKL6BDZKIS4FGPSM",
"ordinal": -2251731094208512
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
}
},
{
"type": "CATEGORY",
"id": "4D5MK3D5LB2ZPXPMD6IRQ5RB",
"updated_at": "2025-06-10T18:04:54.674Z",
"created_at": "2025-06-10T18:04:54.806Z",
"version": 1749578694674,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Special sandwich subgroup",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "JLIE5PQIE7LEFVN5DZUL72RX",
"ordinal": -2251731094208512
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
}
},
{
"type": "CATEGORY",
"id": "7EN7VWSPUI25PJPS6XEEUV5G",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Starters",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "H462U4DGLLEGU34OS4LLLNJQ",
"ordinal": 0
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC"
],
"online_visibility": false,
"root_category": "H462U4DGLLEGU34OS4LLLNJQ"
}
},
{
"type": "CATEGORY",
"id": "JNC2O2TJ534GSLDLSIE35NMH",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Sandwiches",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "H462U4DGLLEGU34OS4LLLNJQ",
"ordinal": 1
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC"
],
"online_visibility": false,
"root_category": "H462U4DGLLEGU34OS4LLLNJQ"
}
}
],
"latest_time": "2025-06-10T22:44:08.232Z"
}
```
{% /tab %}
{% /tabset %}
{% accordion expanded=false %}
{% slot "heading" %}
#### Understanding menu category relationships
{% /slot %}
When working with menu categories, it's important to understand the distinction between `parent_category_id` and `root_category_id`:
**Direct parent vs. root category**
- `parent_category_id` indicates the immediate parent of a category.
- `root_category_id` indicates the top-level ancestor of a category.
These IDs are different if a category is nested multiple levels deep.
When you make this API call, it shows all categories under a main menu item. For example, in a coffee shop menu:
- Root category: "Breakfast Menu" (ID: `3H3ADZMYJU6U27JYO2PZFANQ`)
- Parent category: "Beverages" (ID: `H5P6BRQKWKL6BDZKIS4FGPSM`)
- Category: "Coffee-drinks" (ID: `ZTVXYFS633S6GSLMHVP5O5IG`)
```json
{
"object": {
"type": "CATEGORY",
"id": "ZTVXYFS633S6GSLMHVP5O5IG",
"updated_at": "2025-06-02T22:04:56.684Z",
"created_at": "2025-06-02T22:04:56.898Z",
"version": 1748901896684,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Coffee-drinks",
"image_ids": [
"BAXRGSINXCHS7RW4ZMQSHGGL"
],
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "H5P6BRQKWKL6BDZKIS4FGPSM",
"ordinal": -2251731094208512
},
"is_top_level": false,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": false,
"root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
}
}
}
```
To properly reconstruct the menu hierarchy, always check the `parent_category_id` to determine where each category belongs in the structure.
{% /accordion %}
#### Get menu items
To complete the menu, your application needs to get the [items](https://developer.squareup.com/reference/square/objects/CatalogItem), [variations](https://developer.squareup.com/reference/square/objects/CatalogItemVariation), any [modifier lists](https://developer.squareup.com/reference/square/objects/CatalogModifierList), [images](https://developer.squareup.com/reference/square/objects/CatalogImage), and other resources related to the items shown on the menus. You can get all this information with a single API call. Note that you need to include the `"include_related_objects": true` query parameter.
{% tabset %}
{% tab id="Request" %}
Finally, use [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) to get all items in the categories returned by the previous API call.
````
{% /tab %}
{% tab id="Response" %}
This returns all menu-related `CatalogItem` objects, their variations, and related objects such as modifier lists, taxes, and product images. Items are associated with owning categories by setting the IDs of these categories in the [CatalogItem.categories](https://developer.squareup.com/reference/square/objects/CatalogItem#definition__property-categories) property.
{% aside type="info" %}
The example response is truncated for brevity.
{% /aside %}
```json
{
"objects": [
{
"type": "ITEM",
"id": "UX7IHR55Q7OXE4OIM6XC5HED",
"updated_at": "2025-06-10T18:04:55.345Z",
"created_at": "2021-12-05T00:12:08.245Z",
"version": 1749578695345,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Cannon Beach, sunset",
"description": "Sunset on a spring evening, Cannon Beach, OR",
"is_taxable": true,
"tax_ids": [
"UCQQDWUYMYIZD3NZZBG7GLQK"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "2LGBIYQR277UJLCBV4HDD5XX",
"updated_at": "2025-06-10T18:04:54.674Z",
"created_at": "2021-12-05T00:12:08.245Z",
"version": 1749578694674,
"is_deleted": false,
"custom_attribute_values": {
"Square:90b0a94b-67f7-427c-add2-14e705ed5139": {
"name": "Media",
"custom_attribute_definition_id": "4MFYBLAD7GH4UQE6ZYUMFLDY",
"type": "SELECTION",
"selection_uid_values": [
"G4QBD2RTWOESM2YSHVOW5CDR"
],
"key": "Square:90b0a94b-67f7-427c-add2-14e705ed5139"
}
},
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "UX7IHR55Q7OXE4OIM6XC5HED",
"name": "Regular",
"sku": "IMGP2427",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 16000,
"currency": "USD"
},
"location_overrides": [
{
"location_id": "E78VDDVFW1EYX",
"track_inventory": true,
"sold_out": true
},
{
"location_id": "LFF3HK0DN6A61",
"track_inventory": true
},
{
"location_id": "LRAXEJYQZ0JED",
"track_inventory": true,
"sold_out": true
}
],
"track_inventory": true,
"inventory_alert_type": "NONE",
"sellable": true,
"stockable": true,
"channels": [
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
]
}
}
],
"product_type": "REGULAR",
"skip_modifier_screen": false,
"ecom_uri": "https://flamingredphoto.square.site/product/cannon-beach-sunset/15",
"ecom_image_uris": [
"https://flamingredphoto.square.site/uploads/1/3/1/8/131848966/s381317022439460574_p15_i3_w460.jpeg"
],
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"image_ids": [
"DZUOK5RZ37YCFM6WOWX564XG"
],
"categories": [
{
"id": "5YKGXW7RGOVVWL5U57VRGR3A",
"ordinal": 412316860416
},
{
"id": "YOJ5XWPLU232WTTG4JKBGEC3",
"ordinal": 2251662374731761
},
{
"id": "4D5MK3D5LB2ZPXPMD6IRQ5RB",
"ordinal": -2251799813685248
}
],
"description_html": "\u003cp\u003eSunset on a spring evening, Cannon Beach, OR\u003c/p\u003e",
"description_plaintext": "Sunset on a spring evening, Cannon Beach, OR",
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC",
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o",
"CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC"
],
"is_archived": false,
"reporting_category": {
"id": "5YKGXW7RGOVVWL5U57VRGR3A",
"ordinal": 412316860416
}
}
},
{
"type": "ITEM",
"id": "GDAYYASFCCF6QUGM4URTS7BN",
"updated_at": "2025-06-10T22:44:08.232Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595448232,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_data": {
"name": "Classic Burger",
"description": "Juicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.",
"is_taxable": true,
"modifier_list_info": [
{
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true,
"hidden_from_customer": false,
"ordinal": 2,
"allow_quantities": "NOT_SET",
"is_conversational": "NOT_SET",
"hidden_from_customer_override": "NOT_SET"
}
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "B5IDPADMOT7MQ2NK26FKNJQU",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "GDAYYASFCCF6QUGM4URTS7BN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1500,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
}
],
"product_type": "FOOD_AND_BEV",
"ecom_uri": "https://flamingredphoto.square.site/product/classic-burger/36",
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"categories": [
{
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"ordinal": 0
},
{
"id": "JNC2O2TJ534GSLDLSIE35NMH",
"ordinal": 0
}
],
"description_html": "\u003cp\u003eJuicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.\u003c/p\u003e",
"description_plaintext": "Juicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.",
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"is_archived": false,
"reporting_category": {
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"ordinal": 0
},
"is_alcoholic": false
}
}
],
"related_objects": [
{
"type": "IMAGE",
"id": "DZUOK5RZ37YCFM6WOWX564XG",
"updated_at": "2022-04-11T23:43:48.436Z",
"created_at": "2021-12-15T00:25:01.383Z",
"version": 1649720628436,
"is_deleted": false,
"present_at_all_locations": true,
"image_data": {
"name": "IMGP2427.jpg",
"url": "https://items-images-production.s3.us-west-2.amazonaws.com/files/c9525e3ae73b06a349b7a6c195c0ce76eb38cf96/original.jpeg"
}
},
{
"type": "CATEGORY",
"id": "5YKGXW7RGOVVWL5U57VRGR3A",
"updated_at": "2025-01-22T19:57:21.1Z",
"created_at": "2018-07-26T21:53:14.953Z",
"version": 1737575841100,
"is_deleted": false,
"custom_attribute_values": {
"helmet_brand": {
"name": "Helmet Brand",
"string_value": "Kratoni",
"custom_attribute_definition_id": "WO43QWQ4QYOOPCQZJMG6JIBF",
"type": "STRING",
"key": "helmet_brand"
}
},
"present_at_all_locations": true,
"category_data": {
"name": "Photographs",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": -2251662374731776
},
"is_top_level": true,
"online_visibility": true
}
},
{
"type": "TAX",
"id": "UCQQDWUYMYIZD3NZZBG7GLQK",
"updated_at": "2025-06-05T07:33:20.607Z",
"created_at": "2022-04-11T23:43:45.765Z",
"version": 1749108800607,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Washington",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "8.9",
"applies_to_custom_amounts": true,
"enabled": true,
"tax_type_id": "us_sales_tax",
"tax_type_name": "Sales Tax",
"is_secondary_tax": false
}
},
{
"type": "CATEGORY",
"id": "5GFEUEK7R4DKFSXP54WUOUJM",
"updated_at": "2025-06-02T18:24:46.792Z",
"created_at": "2025-06-02T18:24:46.958Z",
"version": 1748888686792,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Breakfast Sandwiches",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 206158631696
},
"is_top_level": true,
"online_visibility": true
}
},
{
"type": "CATEGORY",
"id": "QFN5Y5AUUK2XK2NT3AFPV4AL",
"updated_at": "2025-06-02T18:24:46.792Z",
"created_at": "2025-06-02T18:24:46.958Z",
"version": 1748888686792,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Pastries",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 274878108432
},
"is_top_level": true,
"online_visibility": true
}
},
{
"type": "IMAGE",
"id": "GC2BM3L5G7YU5ACM6J5NIB24",
"updated_at": "2025-06-02T21:47:48.166Z",
"created_at": "2025-06-02T21:47:48.199Z",
"version": 1748900868166,
"is_deleted": false,
"present_at_all_locations": true,
"image_data": {
"url": "https://items-images-production.s3.us-west-2.amazonaws.com/files/fbb6a5bb738eca54b3a6accd06e79fc893141221/original.png"
}
},
{
"type": "IMAGE",
"id": "FEOGCZJTM3K2MUNQ5LZUSQ4M",
"updated_at": "2025-06-02T21:48:14.755Z",
"created_at": "2025-06-02T21:48:14.791Z",
"version": 1748900894755,
"is_deleted": false,
"present_at_all_locations": true,
"image_data": {
"url": "https://items-images-production.s3.us-west-2.amazonaws.com/files/d221308875a8e89dcfc58418ddc7854b3ae62df1/original.png"
}
},
{
"type": "MODIFIER_LIST",
"id": "CQZ6SECYCB5E2JM2OJU6WO2M",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_list_data": {
"name": "Sauce Choice",
"ordinal": 100000000,
"selection_type": "SINGLE",
"modifiers": [
{
"type": "MODIFIER",
"id": "FDZD6MPY6CIL4RDDDCYOJ442",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "BBQ",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "MA3TSC4BXGTORHF36EBK35K3",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Spicy",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "XACXEM7NKRQOQETHRJG2ITZZ",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Mild",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 2,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
}
],
"is_conversational": false,
"modifier_type": "LIST",
"min_selected_modifiers": 1,
"max_selected_modifiers": 1
}
},
{
"type": "MODIFIER_LIST",
"id": "UBG5GMFXG4GABAHNIY4DNHWQ",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_list_data": {
"name": "Cooking Preference",
"ordinal": 100000001,
"selection_type": "SINGLE",
"modifiers": [
{
"type": "MODIFIER",
"id": "IZ4ZJIH3RBP7AXNTVDHMAGVD",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Medium",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
},
{
"type": "MODIFIER",
"id": "JMP4KPGWKM4R7LA7HK6VZSET",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Well Done",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
}
],
"is_conversational": false,
"modifier_type": "LIST",
"min_selected_modifiers": 1,
"max_selected_modifiers": 1
}
},
{
"type": "CATEGORY",
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Sandwiches",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 412317061904
},
"is_top_level": true,
"online_visibility": true
}
},
{
"type": "CATEGORY",
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Starters",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 481036538640
},
"is_top_level": true,
"online_visibility": true
}
}
],
"latest_time": "2025-06-10T22:44:08.232Z"
}
```
{% /tab %}
{% /tabset %}
{% accordion expanded=false %}
{% slot "heading" %}
### Processing the initial sync
{% /slot %}
When processing these results, follow this specific order:
1. **Root categories** (from the first call):
- Store the root category IDs.
- Note which are top-level menu categories.
- These form the base of your menu structure.
2. **Child categories** (from the second call):
- Link each child category to its parent and root categories.
- Maintain the `MENU_CATEGORY` hierarchy.
- Store these category IDs for the next step.
3. **Items and variations** (from the third call):
- Link items to their appropriate categories.
- Process all variations for each item.
- Include any related objects (such as modifiers and images).
{% /accordion %}
## Get menu updates
To keep your application's menu data current with the seller's Square catalog, implement a periodic sync strategy to capture various types of menu changes.
### Types of menu updates
- Item modifications (price, description, or images)
- Menu structure changes (new categories or item reorganization)
- Item availability updates
- New item additions or removals
To learn about tracking availability updates, see [Monitor Sold-out Item Variations or Modifiers](inventory-api/monitor-sold-out-status-on-item-variation).
You can efficiently track these changes using the `updated_at` timestamp in the [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) endpoint:
### Return menu category changes
{% tabset %}
{% tab id="Request" %}
This example returns all menu categories modified after June 11, 2025, at 7:00 AM:
````
{% /tab %}
{% tab id="Response" %}
Only menu cateogories are returned.
```json
{
"objects": [
{
"type": "CATEGORY",
"id": "XFOOIQWNGT25OGNOALD4DP4V",
"updated_at": "2025-06-11T20:15:38.512Z",
"created_at": "2025-06-10T23:36:14.87Z",
"version": 1749672938512,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Appetizers",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 549756015376
},
"is_top_level": true,
"channels": [
"CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
],
"online_visibility": true,
"ecom_seo_data": {
"page_title": "",
"page_description": "",
"permalink": ""
}
}
},
{
"type": "CATEGORY",
"id": "ILBEI56EXWHBBHC7LH7HP7CZ",
"updated_at": "2025-06-11T20:26:05.431Z",
"created_at": "2025-06-10T23:39:46.038Z",
"version": 1749673565431,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Delivery Menu",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 618475492112
},
"is_top_level": true,
"channels": [
"CH_4s6dFPG7nd0Axgdcu8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"online_visibility": false,
"ecom_seo_data": {
"page_title": "",
"page_description": "",
"permalink": ""
}
}
},
{
"type": "CATEGORY",
"id": "YUJLJGPTN5OSDE5ZJOTNBK47",
"updated_at": "2025-06-11T20:26:05.431Z",
"created_at": "2025-06-10T23:52:08.642Z",
"version": 1749673565431,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Appetizers",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "ILBEI56EXWHBBHC7LH7HP7CZ",
"ordinal": -2251731094208512
},
"is_top_level": false,
"channels": [
"CH_4s6dFPG7nd0Axgdcu8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"online_visibility": false,
"root_category": "ILBEI56EXWHBBHC7LH7HP7CZ"
}
},
{
"type": "CATEGORY",
"id": "24ZP2P5IMO4QE4VFGFNXRGOM",
"updated_at": "2025-06-11T21:39:58.991Z",
"created_at": "2025-06-11T21:39:59.052Z",
"version": 1749677998991,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Appetizers - menu II",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 687194968848
},
"is_top_level": true,
"online_visibility": true
}
}
],
"latest_time": "2025-06-11T21:39:58.991Z"
}
```
{% /tab %}
{% /tabset %}
### Return item changes
After retrieving any changes to the menu structure, you want to get any changes to menu items and related types.
{% tabset %}
{% tab id="Request" %}
This example retrieves items, variations, images, taxes, discounts, modifiers, and modifier lists. These types are usually defined for menu items and might change frequently. The list of types that you sync might be different.
This example asks for all changes (including deletions) in these types made after June 10, 2025, at 7:00 PM:
````
{% aside type="info" %}
If you include related objects, your result set might include other related objects even if they haven't changed.
{% /aside %}
{% /tab %}
{% tab id="Response" %}
```json
{
"objects": [
{
"type": "ITEM_VARIATION",
"id": "I573TS32QL4CESCFYG5T3Y7A",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "WMESBNU3X25KAZ7MOSEBKNHC",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1000,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
},
{
"type": "ITEM_VARIATION",
"id": "57M2377J6RKASJH5JHY5NCZ2",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "TDQ4GS3ATSYUEWH5YEBHQETC",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1200,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
},
{
"type": "ITEM_VARIATION",
"id": "B5IDPADMOT7MQ2NK26FKNJQU",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "GDAYYASFCCF6QUGM4URTS7BN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1500,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
},
{
"type": "MODIFIER_LIST",
"id": "CQZ6SECYCB5E2JM2OJU6WO2M",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_list_data": {
"name": "Sauce Choice",
"ordinal": 100000000,
"selection_type": "SINGLE",
"modifiers": [
{
"type": "MODIFIER",
"id": "FDZD6MPY6CIL4RDDDCYOJ442",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "BBQ",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "MA3TSC4BXGTORHF36EBK35K3",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Spicy",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "XACXEM7NKRQOQETHRJG2ITZZ",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Mild",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 2,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
}
],
"is_conversational": false,
"modifier_type": "LIST",
"min_selected_modifiers": 1,
"max_selected_modifiers": 1
}
},
{
"type": "MODIFIER_LIST",
"id": "UBG5GMFXG4GABAHNIY4DNHWQ",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_list_data": {
"name": "Cooking Preference",
"ordinal": 100000001,
"selection_type": "SINGLE",
"modifiers": [
{
"type": "MODIFIER",
"id": "IZ4ZJIH3RBP7AXNTVDHMAGVD",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Medium",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
},
{
"type": "MODIFIER",
"id": "JMP4KPGWKM4R7LA7HK6VZSET",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Well Done",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
}
],
"is_conversational": false,
"modifier_type": "LIST",
"min_selected_modifiers": 1,
"max_selected_modifiers": 1
}
},
{
"type": "MODIFIER",
"id": "FDZD6MPY6CIL4RDDDCYOJ442",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "BBQ",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "MA3TSC4BXGTORHF36EBK35K3",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Spicy",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "XACXEM7NKRQOQETHRJG2ITZZ",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Mild",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 2,
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M"
}
},
{
"type": "MODIFIER",
"id": "IZ4ZJIH3RBP7AXNTVDHMAGVD",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Medium",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": true,
"ordinal": 0,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
},
{
"type": "MODIFIER",
"id": "JMP4KPGWKM4R7LA7HK6VZSET",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"modifier_data": {
"name": "Well Done",
"price_money": {
"amount": 0,
"currency": "USD"
},
"on_by_default": false,
"ordinal": 1,
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ"
}
},
{
"type": "ITEM",
"id": "TDQ4GS3ATSYUEWH5YEBHQETC",
"updated_at": "2025-06-10T22:44:07.766Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595447766,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_data": {
"name": "Loaded Nachos",
"description": "Crispy tortilla chips topped with melted cheese, jalapenos, sour cream, and salsa.",
"is_taxable": true,
"variations": [
{
"type": "ITEM_VARIATION",
"id": "57M2377J6RKASJH5JHY5NCZ2",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "TDQ4GS3ATSYUEWH5YEBHQETC",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1200,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
}
],
"product_type": "FOOD_AND_BEV",
"ecom_uri": "https://flamingredphoto.square.site/product/loaded-nachos/34",
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"categories": [
{
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"ordinal": 1
},
{
"id": "7EN7VWSPUI25PJPS6XEEUV5G",
"ordinal": 1
}
],
"description_html": "Crispy tortilla chips topped with melted cheese, jalapenos, sour cream, and salsa.
",
"description_plaintext": "Crispy tortilla chips topped with melted cheese, jalapenos, sour cream, and salsa.",
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"is_archived": false,
"reporting_category": {
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"ordinal": 1
},
"is_alcoholic": false
}
},
{
"type": "ITEM",
"id": "WMESBNU3X25KAZ7MOSEBKNHC",
"updated_at": "2025-06-10T22:44:08.012Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595448012,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_data": {
"name": "Buffalo Wings",
"description": "Spicy chicken wings served with blue cheese dressing and celery sticks.",
"is_taxable": true,
"modifier_list_info": [
{
"modifier_list_id": "CQZ6SECYCB5E2JM2OJU6WO2M",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true,
"hidden_from_customer": false,
"ordinal": 1,
"allow_quantities": "NOT_SET",
"is_conversational": "NOT_SET",
"hidden_from_customer_override": "NOT_SET"
}
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "I573TS32QL4CESCFYG5T3Y7A",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "WMESBNU3X25KAZ7MOSEBKNHC",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1000,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
}
],
"product_type": "FOOD_AND_BEV",
"ecom_uri": "https://flamingredphoto.square.site/product/buffalo-wings/35",
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"categories": [
{
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"ordinal": 0
},
{
"id": "7EN7VWSPUI25PJPS6XEEUV5G",
"ordinal": 0
}
],
"description_html": "Spicy chicken wings served with blue cheese dressing and celery sticks.
",
"description_plaintext": "Spicy chicken wings served with blue cheese dressing and celery sticks.",
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"is_archived": false,
"reporting_category": {
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"ordinal": 0
},
"is_alcoholic": false
}
},
{
"type": "ITEM",
"id": "GDAYYASFCCF6QUGM4URTS7BN",
"updated_at": "2025-06-10T22:44:08.232Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595448232,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_data": {
"name": "Classic Burger",
"description": "Juicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.",
"is_taxable": true,
"modifier_list_info": [
{
"modifier_list_id": "UBG5GMFXG4GABAHNIY4DNHWQ",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true,
"hidden_from_customer": false,
"ordinal": 2,
"allow_quantities": "NOT_SET",
"is_conversational": "NOT_SET",
"hidden_from_customer_override": "NOT_SET"
}
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "B5IDPADMOT7MQ2NK26FKNJQU",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": false,
"present_at_location_ids": [
"E78VDDVFW1EYX"
],
"item_variation_data": {
"item_id": "GDAYYASFCCF6QUGM4URTS7BN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 1500,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
]
}
}
],
"product_type": "FOOD_AND_BEV",
"ecom_uri": "https://flamingredphoto.square.site/product/classic-burger/36",
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"categories": [
{
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"ordinal": 0
},
{
"id": "JNC2O2TJ534GSLDLSIE35NMH",
"ordinal": 0
}
],
"description_html": "Juicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.
",
"description_plaintext": "Juicy beef patty with lettuce, tomato, onions, and pickles on a sesame seed bun.",
"channels": [
"CH_QsN9pXIZiVwCMWjFr8NXQqPO54qnOXkyQRkiBQlQuYC"
],
"is_archived": false,
"reporting_category": {
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"ordinal": 0
},
"is_alcoholic": false
}
}
],
"related_objects": [
{
"type": "CATEGORY",
"id": "U3G2UZ75UWIVG3JWQL5BCLH4",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Sandwiches",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 412317061904
},
"is_top_level": true,
"online_visibility": true
}
},
{
"type": "CATEGORY",
"id": "Z6O6YJFE37DLY37G4OULXDHY",
"updated_at": "2025-06-10T22:43:22.122Z",
"created_at": "2025-06-10T22:43:22.259Z",
"version": 1749595402122,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Starters",
"category_type": "REGULAR_CATEGORY",
"parent_category": {
"ordinal": 481036538640
},
"is_top_level": true,
"online_visibility": true
}
}
],
"latest_time": "2025-06-11T21:39:58.991Z"
}
```
{% /tab %}
{% /tabset %}
{% accordion expanded=false %}
{% slot "heading" %}
### Best practices for menu syncing
{% /slot %}
1. **Initial load**
- Perform the initial sync during off-peak hours.
- Process objects in the correct order (categories → items → modifiers).
- Validate relationships as you build the menu structure.
2. **Incremental updates**
- Store the last sync timestamp.
- Include related objects in update queries.
- Handle deleted objects appropriately.
3. **Error handling**
- Implement retry logic for failed requests.
- Log sync errors for troubleshooting.
- Maintain a sync status dashboard.
4. **Data validation**
- Verify category relationships.
- Validate price points.
- Check for required attributes.
{% /accordion %}
## Understanding menu categories vs. regular categories
When working with the Catalog API, it's important to understand the distinction between menu categories and regular categories:
* **Menu categories**
- Created through the Square Dashboard's menu builder.
- Have `category_type = "MENU_CATEGORY"`.
- Used specifically for menu organization.
- Like regular categories, support parent-child relationships.
- Can be synchronized across channels.
* **Regular categories**
- Created through the Catalog API.
- Have `category_type = "REGULAR_CATEGORY"`.
- Used for general item organization.
- Might appear as duplicates of menu categories.
{% aside type="important" %}
When retrieving categories through the Catalog API, you might see what appears to be duplicate categories. This happens because the menu builder creates separate menu categories (`MENU_CATEGORY`) from regular categories (`REGULAR_CATEGORY`). To work specifically with menu structures, always filter for categories where `category_type = "2" (`MENU_CATEGORY`).
{% /aside %}
## Kitchen display names
For Food & Beverage operations, Square supports separate kitchen display names to streamline back-of-house operations. These properties allow restaurants to use different names for kitchen staff versus customer-facing displays, improving order accuracy and kitchen efficiency.
**Available properties:**
- [CatalogItem.kitchen_name](https://developer.squareup.com/reference/square/objects/CatalogItem#definition__property-kitchen_name) - A kitchen-friendly name for the menu item.
- [CatalogItem.buyer_facing_name](https://developer.squareup.com/reference/square/objects/CatalogItem#definition__property-buyer_facing_name) - The customer-facing name displayed to buyers.
- [CatalogItemVariation.kitchen_name](https://developer.squareup.com/reference/square/objects/CatalogItemVariation#definition__property-kitchen_name) - Kitchen name for specific item variations (sizes and options).
- [CatalogModifier.kitchen_name](https://developer.squareup.com/reference/square/objects/CatalogModifier#definition__property-kitchen_name) - Kitchen name for modifiers (such as add-ons and customizations).
**Benefits for restaurant operations:**
These properties help restaurants:
- Use abbreviated or coded names on kitchen display systems (KDSs).
- Maintain appetizing, descriptive names for customer receipts and online ordering.
- Reduce confusion during food preparation with standardized kitchen terminology.
- Speed up order fulfillment by using familiar kitchen shorthand.
- Support multi-language operations (kitchen names in one language, buyer names in another).
**Example: Creating items with kitchen names**
````
**Example: Adding kitchen names to modifiers**
````
**Best practices for kitchen names:**
1. **Keep it concise** - Kitchen names should be short and easy to read on kitchen display screens.
2. **Use standard abbreviations** - Develop consistent abbreviations your kitchen staff understands.
3. **Consider screen space** - Kitchen display systems often have limited character width.
4. **Test with staff** - Ensure kitchen names are clear and unambiguous to your team.
5. **Update consistently** - When adding new items, maintain your naming conventions.
**Common kitchen name patterns:**
| Customer Name | Kitchen Name | Purpose |
|--------------|--------------|---------|
| Grilled Chicken Caesar Salad | GRL CKN CAESAR | Abbreviated ingredients |
| Mediterranean Veggie Wrap | MED VEG WRAP | Shortened descriptors |
| Extra Virgin Olive Oil | EVOO | Industry standard abbreviations |
| Add Avocado (+$2.00) | +AVO | Modifier shorthand |
| No Onions | NO ONION / -ONION | Exclusion indicators |
| Gluten-Free Bun | GF BUN | Dietary abbreviations |
## Create a menu
### 1. Retrieving menu categories
Use the Catalog API to retrieve existing menu categories.
````
### 2. Creating location-specific menu categories
When creating categories for different locations, ensure that you:
* Set the correct `category_type`.
* Establish proper parent-child relationships.
* Use consistent naming across locations.
The following shows an example for a delivery service menu category:
{% tabset %}
{% tab id="Request" %}
````
{% aside type="info" %}
Menu objects are automatically enabled across all locations by default. When creating or updating menu objects using the API:
- Set `present_at_all_locations` to `true` or omit it entirely.
- Don't set `present_at_location_ids` or `absent_at_location_ids` (leave these fields empty).
Location-specific menu configuration can only be managed through the Square Dashboard. This includes:
- Enabling or disabling menus for specific locations.
- Setting location-specific menu availability.
- Managing location-based menu variations.
{% /aside %}
{% /tab %}
{% tab id="Response" %}
```json
{
"catalog_object": {
"type": "CATEGORY",
"id": "ILBEI56EXWHBBHC7LH7HP7CZ",
"updated_at": "2025-06-10T23:39:45.984Z",
"created_at": "2025-06-10T23:39:45.984Z",
"version": 1749598785984,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Delivery Menu",
"category_type": "MENU_CATEGORY",
"parent_category": {
"ordinal": 618475492112
},
"is_top_level": true,
"online_visibility": true
}
},
"id_mappings": [
{
"client_object_id": "#delivery_menu",
"object_id": "ILBEI56EXWHBBHC7LH7HP7CZ"
}
]
}
```
{% /tab %}
{% /tabset %}
### 3. Creating subcategories
When creating subcategories, always reference the parent menu category.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"catalog_object": {
"type": "CATEGORY",
"id": "YUJLJGPTN5OSDE5ZJOTNBK47",
"updated_at": "2025-06-10T23:52:08.586Z",
"created_at": "2025-06-10T23:52:08.586Z",
"version": 1749599528586,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Appetizers",
"category_type": "MENU_CATEGORY",
"parent_category": {
"id": "ILBEI56EXWHBBHC7LH7HP7CZ",
"ordinal": -2251731094208512
},
"is_top_level": false,
"online_visibility": true,
"root_category": "ILBEI56EXWHBBHC7LH7HP7CZ"
}
},
"id_mappings": [
{
"client_object_id": "#delivery_appetizers_2",
"object_id": "YUJLJGPTN5OSDE5ZJOTNBK47"
}
]
}
```
{% /tab %}
{% /tabset %}
### 4. Menu structures
When working with menu categories, it's important to understand that the structure you see in the Square Dashboard is represented by `MENU_CATEGORY` types in the Catalog API. The following example shows how different menu structures might look:
#### Dashboard menu structure
```
Restaurant Menu (MENU_CATEGORY)
├── Beverages
│ ├── Non-Alcoholic
│ │ ├── Iced Tea (Small/Large)
│ │ ├── Soft Drinks (Regular/Large)
│ │ └── Coffee (Small/Large)
│ ├── Beer
│ │ ├── Draft (Domestic/Craft)
│ │ └── Bottled (Domestic/Imported)
│ └── Wine
│ ├── Red (Glass/Bottle)
│ └── White (Glass/Bottle)
├── Appetizers
│ ├── Mozzarella Sticks
│ ├── Wings (6pc/12pc)
│ └── Nachos
└── Entrees
├── Sandwiches
│ ├── Club
│ └── BLT
└── Salads
├── Caesar
└── Garden
```
#### Delivery service menu structure
```
Delivery Menu (MENU_CATEGORY)
├── Beverages
│ ├── Iced Tea (Small/Large)
│ ├── Soft Drinks (Regular/Large)
│ └── Coffee (Small/Large)
├── Appetizers
│ ├── Mozzarella Sticks
│ ├── Wings (6pc/12pc)
│ └── Nachos
└── Entrees
├── Sandwiches
│ ├── Club
│ └── BLT
└── Salads
├── Caesar
└── Garden
```
## Common issues and solutions
### Issue: Duplicate categories
- **Cause**: Items appearing in both menu and regular categories.
- **Solution**: Filter specifically for `MENU_CATEGORY` types.
- **Prevention**: Use proper category type filtering in API calls.
### Issue: Missing menu items
- **Cause**: Looking at the wrong category type.
- **Solution**: Check both menu and regular category associations.
- **Prevention**: Implement proper category type checking.
### Issue: Incorrect menu structure
- **Cause**: Mixing menu and regular categories.
- **Solution**: Maintain proper parent-child relationships.
- **Prevention**: Validate category types and relationships.
## Implementation tips
1. **Category filtering**
````
2. **Relationship maintenance**
- Track both menu and regular category IDs.
- Update all relevant category associations.
- Maintain a proper hierarchy.
3. **Data validation**
- Verify category types before updates.
- Check parent-child relationships.
- Validate item associations.
### Next steps after syncing
1. **Verify data**
- Compare item counts.
- Validate category structures.
- Check modifier associations.
2. **Monitor performance**
- Track sync times.
- Monitor API usage.
- Optimize query patterns.
3. **Setup alerts**
- Configure sync failure notifications.
- Monitor for pricing discrepancies.
- Alert when structure changes occur.
---
# Manage Scheduled Shifts
> Source: https://developer.squareup.com/docs/labor-api/manage-scheduled-shifts
> Status: BETA
> Languages: All
> Platforms: All
Learn how to create and manage future scheduled shifts for team members using scheduling endpoints in the Labor API.
**Applies to:** [Labor API](labor-api/what-it-does) | [Team API](team/overview) | [Locations API](locations-api) | [Webhooks](webhooks/overview)
{% subheading %}Use the [Labor API](https://developer.squareup.com/reference/square/labor-api) to create and manage future scheduled shifts for team members.{% /subheading %}
{% toc hide=true /%}
## Overview
Applications can use the Labor API to manage team schedules. The basic process includes creating draft scheduled shifts, publishing the scheduled shifts to make them visible to team members, and optionally updating or deleting scheduled shifts.
The following diagram shows the API call flow for managing a scheduled shift and the webhook events triggered by each request:
All updates to a scheduled shift are made to the `draft_shift_details` field. When a scheduled shift is published, Square copies `draft_shift_details` to `published_shift_details`.
*If the shift was never published, setting `draft_shift_details.is_deleted` to `true` in an `UpdateScheduledShift` request deletes the shift. Otherwise, the shift is just marked for deletion and you must publish the change to delete it.
{% aside type="info" %}
The Labor API defines two types of objects; be careful not to confuse them:
- A [ScheduledShift](https://developer.squareup.com/reference/square/objects/ScheduledShift) is used to manage team schedules.
- A [Timecard](https://developer.squareup.com/reference/square/objects/Timecard) represents a single work shift for a team member. Each `Timecard` captures:
- The actual time worked during one shift
- Information needed for payroll processing
For example, if an employee works five different shifts in a week, they will have five separate Timecard records - one for each shift.
**Note:** The older `Shift` object type is deprecated. Use Timecards instead. For information about migration, see [Migration notes](labor-api/what-it-does#migration-notes).
{% /aside %}
## Requirements and limitations
The following requirements and limitations apply when managing scheduled shifts using the Labor API:
* **Square API version** - Square API version 2025-05-21 or later is required to access or manage scheduled shifts.
* **Valid access token** - Square API requests require an `Authorization` header with a bearer access token. The examples in this topic use the {% tooltip text="Square Sandbox" %}An isolated server environment used for testing. API calls in the Sandbox use the "connect.squareupsandbox.com" domain and require an access token that's valid for Sandbox.{% /tooltip %}, so you can test using your [Sandbox access token](build-basics/access-tokens#get-a-personal-access-token).
{% accordion expanded=false %}
{% slot "heading" %}
#### More details
{% /slot %}
Applications using [OAuth](oauth-api/overview) access tokens to authorize requests typically require the following permissions when working with team schedules:
- `MERCHANT_PROFILE_READ` to retrieve location information.
- `EMPLOYEES_READ` to retrieve team member and job information.
- `TIMECARDS_READ` to retrieve scheduled shifts.
- `TIMECARDS_WRITE` to create, update, and publish scheduled shifts.
To call Square APIs in the production environment, change the base URL to `https://connect.squareup.com` and use your production (personal) access token.
{% /accordion %}
* **Two-week window for bulk publishing** - The minimum `start_at` and maximum `end_at` timestamps of all shifts in a `BulkPublishScheduledShifts` request must fall within a two-week period.
{% anchor id="time-zone-offset" /%}
* **Time zone + offset for start and end times** - The `start_at` and `end_at` timestamps are provided in RFC 3339 format and represent the local time for the shift location specified in `location_id`. Precision up to the minute is respected; seconds are truncated.
{% accordion expanded=false %}
{% slot "heading" %}
#### More details
{% /slot %}
For example, 9:00 AM local PST time can be specified as `2025-04-13T09:00:00-08:00` or `2025-04-13T17:00:00Z`.
Square stores the location's time zone (for example, "America/Los_Angeles") in the read-only `timezone` field of the scheduled shift. Square uses the time zone to calculate the correct local time for shifts and display times appropriately to team members.
When providing Daylight Saving Time (DST) timestamps, be aware that:
- Times during the DST start transition (typically 2:00-2:59 AM) don't exist.
- Times during the DST end transition (typically 1:00-1:59 AM) occur twice.
{% /accordion %}
For scheduling capabilities, see general [Requirements and limitations](labor-api/scheduling#requirements-and-limitations).
{% anchor id="create-scheduled-shifts" /%}
## Create scheduled shifts
To create a scheduled shift, call [CreateScheduledShift](https://developer.squareup.com/reference/square/labor-api/create-scheduled-shift) and provide `draft_shift_details`. You can then review and update the shift and publish it when you're ready to make it visible to all team members. When a scheduled shift is published, Square keeps `draft_shift_details` as is and copies it to the `published_shift_details` field.
Be ready to provide `draft_shift_details` with the following required fields:
- `location_id` - The ID of the location where the shift occurs. Call [ListLocations](https://developer.squareup.com/reference/square/locations-api/list-locations) to get location IDs.
- `job_id` - The ID of the job for the shift. Call [ListJobs](https://developer.squareup.com/reference/square/team-api/list-jobs) to get job IDs.
- `start_at` and `end_at` - Start and end times for the shift in the [time zone + offset](#time-zone-offset) of the location.
You can also provide the following optional `draft_shift_details` fields:
- `team_member_id` - The ID of the [team member to assign to the shift](#manage-team-member-assignments).
- `notes` - Notes for the shift.
{% line-break /%}
{% tabset %}
{% tab id="Request" %}
The following example request includes all draft shift details
````
{% /tab %}
{% tab id="Response" %}
The response returns the new scheduled shift with draft shift details.
```json
{
"scheduled_shift": {
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 1,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T14:58:49-07:00"
}
}
```
{% /tab %}
{% /tabset %}
### Webhooks
Creating a scheduled shift triggers the following [webhook event](webhooks/overview):
- [labor.scheduled_shift.created](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.created)
### Next steps
- [Update the scheduled shift](#update-scheduled-shifts) as needed. Updates might include [managing the team member assignment](#manage-team-member-assignments) or [deleting the shift](#delete-scheduled-shifts).
- [Publish the scheduled shift](#publish-scheduled-shifts) to make it public.
## Update scheduled shifts
To make changes to a scheduled shift, call [UpdateScheduledShift](https://developer.squareup.com/reference/square/labor-api/update-scheduled-shift) and provide `draft_shift_details` with any new, changed, or cleared fields. When you're ready to make the changes visible to all team members, publish the shift.
Be ready to provide the following information:
- `id` - The shift ID as a path parameter. Get the shift ID from the [CreateScheduledShift](https://developer.squareup.com/reference/square/labor-api/create-scheduled-shift) response or call [SearchScheduledShifts](https://developer.squareup.com/reference/square/labor-api/search-scheduled-shifts).
- `draft_shift_details` - Any new, changed, or cleared fields. You can make the following changes:
- Change the value of required fields.
- `location_id` - The ID of the location where the shift occurs. Call [ListLocations](https://developer.squareup.com/reference/square/locations-api/list-locations) to get location IDs.
- `job_id` - The ID of the job for the shift. Call [ListJobs](https://developer.squareup.com/reference/square/team-api/list-jobs) to get job IDs.
- `start_at` and `end_at` - Start and end times for the shift in [time zone + offset format](#time-zone-offset).
- Add, change, or clear optional fields. To clear these fields, set the value to `null`.
- `team_member_id` - The ID of the [team member to assign to the shift](#manage-team-member-assignments).
- `notes` - Notes for the shift.
- Use the `is_deleted` field to [delete the shift](#delete-scheduled-shifts).
- `version` (optional) - The current version of the shift, used to enable [optimistic concurrency control](build-basics/common-api-patterns/optimistic-concurrency) for the request. Get the current version when you get the shift ID.
{% aside type="info" %}
`UpdateScheduledShift` supports [sparse updates](build-basics/clearing-fields#sparse-updates), so the request only needs to include your changes.
Any updates to the `published_shift_details` field are ignored.
{% /aside %}
{% tabset %}
{% tab id="Request" %}
The following example request changes the `team_member_id`, `start_at`, and `end_at` fields and clears the `notes` field:
````
{% /tab %}
{% tab id="Response" %}
The response returns the scheduled shift with updated draft shift details and incremented `version`.
In this example, the presence of the `published_shift_details` field indicates that the shift was previously published. Note that `draft_shift_details` differs from `published_shift_details` because the change isn't published yet.
```json
{
"scheduled_shift": {
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T11:00:00-07:00",
"end_at": "2025-04-15T18:00:00-07:00",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "1AVJj0DjkzbmbJw5r4KK",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
}
```
{% /tab %}
{% /tabset %}
### Webhooks
Updating a scheduled shift triggers the following [webhook events](webhooks/overview):
- [labor.scheduled_shift.updated](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.updated)
- [labor.scheduled_shift.deleted](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.deleted) - Only if `draft_shift_details.is_deleted` is set to `true` when [deleting a draft-only shift](#delete-scheduled-shifts).
### Next steps
- Update the scheduled shift with more changes as needed. This might include [managing the team member assignment](#manage-team-member-assignments) or [deleting the shift](#delete-scheduled-shifts).
- [Publish the scheduled shift](#publish-scheduled-shifts) to make your changes public.
## Publish scheduled shifts
After creating or updating a scheduled shift, you must call [PublishScheduledShift](https://developer.squareup.com/reference/square/labor-api/publish-scheduled-shift) or [BulkPublishScheduledShifts](https://developer.squareup.com/reference/square/labor-api/bulk-publish-scheduled-shifts) to make the new shift or latest draft details visible to all team members. When a scheduled shift is published, Square keeps `draft_shift_details` as is and copies it to the `published_shift_details` field.
Be ready to provide the following information:
- `id` - The shift ID. Get the shift ID from the [CreateScheduledShift](https://developer.squareup.com/reference/square/labor-api/create-scheduled-shift) response or call [SearchScheduledShifts](https://developer.squareup.com/reference/square/labor-api/search-scheduled-shifts).
- `idempotency_key` - A unique string used to ensure the [idempotency](build-basics/common-api-patterns/idempotency) of the operation. Required for `PublishScheduledShift`; not used for `BulkPublishScheduledShifts`.
- `scheduled_shift_notification_audience` - Indicates whether Square should send an email notification to team members. Valid values:
* `ALL` - Send a notification to all active team members.
* `AFFECTED` (default) - Send a notification to the team member assigned to the shift. When changing the team member assignment, both team members are notified.
* `NONE` - Don't send notifications.
Note that republishing an unchanged shift doesn't resend the notification if set to `AFFECTED` or `NONE`.
- `version` (optional) - The current version of the shift, used to enable [optimistic concurrency control](build-basics/common-api-patterns/optimistic-concurrency) for the request. Get the current version when you get the shift ID.
{% line-break /%}
{% accordion expanded=true %}
{% slot "heading" %}
### Publish a single scheduled shift
{% /slot %}
To publish a single scheduled shift, call [PublishScheduledShift](https://developer.squareup.com/reference/square/labor-api/publish-scheduled-shift) and provide the ID of the scheduled shift you want to publish (as a path parameter) and `idempotency_key`. Optionally provide `version` and `scheduled_shift_notification_audience`.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The response returns the published scheduled shift.
```json
{
"scheduled_shift": {
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
}
```
{% /tab %}
{% /tabset %}
{% /accordion %}
{% accordion expanded=true %}
{% slot "heading" %}
### Publish multiple scheduled shifts
{% /slot %}
To publish 1 – 100 scheduled shifts, provide `scheduled_shifts` as a map of key-value pairs that represent individual publish requests. The minimum `start_at` and maximum `end_at` timestamps of all shifts in a `BulkPublishScheduledShifts` request must fall within a two-week period.
- Each key is the ID of a scheduled shift you want to publish.
- Each value is a `BulkPublishScheduledShiftsData` object that contains the optional `version` field or is empty.
The optional `scheduled_shift_notification_audience` setting applies to the bulk operation.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The response returns a map of responses for the published scheduled shifts. Responses might not be returned in the same order as the individual publish requests sent to `BulkPublishScheduledShifts`.
```json
{
"responses": {
"kxR8FWJE8DT3x7": {
"scheduled_shift": {
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
},
"kxR8FWJE8DT4x8": {
"scheduled_shift": {
"id": "kxR8FWJE8DT4x8",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-4pZQKPKVk6gUXU_V5Qb",
"start_at": "2025-04-15T17:00:00-07:00",
"end_at": "2025-04-16T01:00:00-07:00",
"notes": "Closing shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-4pZQKPKVk6gUXU_V5Qb",
"start_at": "2025-04-15T17:00:00-07:00",
"end_at": "2025-04-16T01:00:00-07:00",
"notes": "Closing shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
},
"kxR8FWJE8DT5x9": {
"scheduled_shift": {
"id": "kxR8FWJE8DT5x9",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-5qZQKPKVk6gUXU_V5Qc",
"start_at": "2025-04-16T09:00:00-07:00",
"end_at": "2025-04-16T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-5qZQKPKVk6gUXU_V5Qc",
"start_at": "2025-04-16T09:00:00-07:00",
"end_at": "2025-04-16T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 1,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
}
}
}
```
{% /tab %}
{% /tabset %}
{% /accordion %}
### Webhooks
Publishing a scheduled shift triggers the following [webhook events](webhooks/overview):
- [labor.scheduled_shift.updated](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.updated)
- [labor.scheduled_shift.published](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.published)
- [labor.scheduled_shift.deleted](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.deleted) - Only if publishing a shift that has `draft_shift_details.is_deleted` set to `true` when [deleting the published shift](#delete-scheduled-shifts).
Each individual publish request in a bulk operation triggers these events.
### Next steps
- [Update the scheduled shift](#update-scheduled-shifts) with more changes as needed. This might include [managing the team member assignment](#manage-team-member-assignments) or [deleting the shift](#delete-scheduled-shifts).
{% anchor id="manage-team-member-assignments" /%}
## Managing team member assignments
In a scheduled shift, the optional `team_member_id` field references the ID of the [team member](https://developer.squareup.com/reference/square/objects/TeamMember) assigned to the shift.
>`"team_member_id": "K6JiNAakLUf5lUYmfjn"`
You can assign a team member when you first [create the shift](#create-scheduled-shifts) or add, change, or clear the assignment when you [update the shift](#update-scheduled-shifts). To clear the team member assignment, set the value to `null`.
>`"team_member_id": null`
You must [publish the shift](#publish-scheduled-shifts) to make the latest draft details public. When published, Square notifies team members according to the `scheduled_shift_notification_audience` setting.
### Team members and job assignments
Sellers can optionally record the jobs that team members are qualified to do. These jobs are stored in the `wage_setting.job_assignments` field, as shown in the following example:
```json
{
"team_member": {
"id": "1yJlHapkseYnNPETIU1B",
...
"wage_setting": {
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"job_assignments": [
{
"job_title": "Server",
"job_id": "FjS8x95cqHiMenw4f1NAUH4P",
"pay_type": "HOURLY",
"hourly_rate": {
"amount": 1700,
"currency": "USD"
}
},
{
"job_title": "Cashier",
"job_id": "VDNpRv8da51NU8qZFC5zDWpF",
"pay_type": "HOURLY",
"hourly_rate": {
"amount": 2000,
"currency": "USD"
}
}
],
...
}
}
}
```
### Find available team members
To find team members that can work a particular job:
1. Call [ListJobs](https://developer.squareup.com/reference/square/team-api/list-jobs) to get the ID of the job to schedule (if needed).
2. Call [SearchTeamMembers](https://developer.squareup.com/reference/square/team-api/search-team-members) and filter by location ID and `ACTIVE` status.
3. Iterate through the results to build a job pool of team members who can do the job:
1. If `wage_setting` is present, iterate through `job_assignments`.
2. Compare the `job_id` field to the ID of the job to schedule.
3. Copy the ID of team members who can do the job.
4. Call [SearchScheduledShifts](https://developer.squareup.com/reference/square/labor-api/search-scheduled-shifts) to find the team members who are already working during the scheduled shift so that you can remove them from the job pool.
````
This query finds all published and assigned shifts that overlap with the specified time period at the specified location. The overlap is detected by finding shifts that start before the period ends (`start.end_at`) and end after the period begins (`end.start_at`).
To find team members working on a specific calendar day, you can alternatively use the [workday filter](labor-api/retrieve-scheduled-shifts#workday-start-at), which is designed for date-based queries.
{% anchor id="delete-scheduled-shifts" /%}
## Deleting scheduled shifts
The `draft_shift_details.is_deleted` field is used to delete scheduled shifts. The deletion process differs based on whether the shift was previously published.
### Draft-only shifts
For shifts that were never published, you need to [update the shift](#update-scheduled-shifts).
1. Call `UpdateScheduledShift` and set `draft_shift_details.is_deleted` to `true`.
This operation performs a hard delete — the shift is permanently deleted and is no longer accessible through API endpoints. This operation triggers these [webhook events](webhooks/overview):
- [labor.scheduled_shift.updated](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.updated)
- [labor.scheduled_shift.deleted](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.deleted)
### Published shifts
For shifts that were previously published, you need to [update the shift](#update-scheduled-shifts) and then [publish the shift](#publish-scheduled-shifts).
1. Call `UpdateScheduledShift` and set `draft_shift_details.is_deleted` to `true`.
This operation marks the shift for deletion and triggers this [webhook event](webhooks/overview):
- [labor.scheduled_shift.updated](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.updated)
In this state, the shift remains accessible and `draft_shift_details.is_deleted` can be set back to `false` to cancel the deletion.
2. Call `PublishScheduledShift` to make the change public.
This operation performs a hard delete — the shift is permanently deleted and is no longer accessible through API endpoints. This operation triggers these webhook events:
- [labor.scheduled_shift.updated](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.updated)
- [labor.scheduled_shift.deleted](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.deleted)
- [labor.scheduled_shift.published](https://developer.squareup.com/reference/square/labor-api/webhooks/labor.scheduled_shift.published)
Square notifies team members according to the `scheduled_shift_notification_audience` setting.
Note that the `ScheduledShift` object in the event data has different `is_deleted` settings:
- For `labor.scheduled_shift.updated`:
- `draft_shift_details.is_deleted` is `true`
- `published_shift_details.is_deleted` is `false`
- For `labor.scheduled_shift.published`:
- `draft_shift_details.is_deleted` is `true`
- `published_shift_details.is_deleted` is `true`
## See also
* [Scheduling with the Labor API](labor-api/scheduling)
* [Labor API](labor-api/what-it-does)
* [Team API](team/overview)
---
# Scheduling with the Labor API
> Source: https://developer.squareup.com/docs/labor-api/scheduling
> Status: BETA
> Languages: All
> Platforms: All
Use the Square Labor API to create and manage team schedules.
**Applies to:** [Labor API](labor-api/what-it-does) | [Team API](team/overview) | [Locations API](locations-api) | [Webhooks](webhooks/overview) | [GraphQL](devtools/graphql)
{% subheading %}Learn how to manage team schedules using the Labor API.{% /subheading %}
{% toc hide=true /%}
## Overview
The Labor API provides scheduling capabilities that let third-party scheduling applications integrate with Square. You can manage team member schedules, synchronize schedule data between external systems and Square, and access data for labor forecasting, labor cost reporting, and optimizing staffing levels. The API supports:
- Creating draft and published schedules.
- Managing shift assignments and changes.
- Searching scheduled hours by status, team member, and other parameters.
- Notifying team members about schedule updates.
Whether you're creating a standalone scheduling application or integrating with the Square Dashboard and Square Team application, you can use the Labor API to manage scheduled shifts.
{% aside type="info" %}
The Labor API defines two types of objects; be careful not to confuse them:
- A [ScheduledShift](https://developer.squareup.com/reference/square/objects/ScheduledShift) is used to manage team schedules.
- A [Timecard](https://developer.squareup.com/reference/square/objects/Timecard) represents a single work shift for a team member. Each `Timecard` captures:
- The actual time worked during one shift
- Information needed for payroll processing
For example, if an employee works five different shifts in a week, they will have five separate Timecard records - one for each shift.
**Note:** The older `Shift` object type is deprecated. Use Timecards instead. For information about migration, see [Migration notes](labor-api/what-it-does#migration-notes).
{% /aside %}
## Requirements and limitations
The following requirements and limitations apply when managing scheduled shifts using the Labor API.
- Square API version 2025-05-21 or later is required to access or manage scheduled shifts.
- The ability to schedule repeated shifts using templates isn't supported.
- Scheduled shifts created by the API are visible in the **Staff** section of the Square Dashboard under **Scheduling** and in the Square Team application. Note the following:
- Sellers must use [team permissions](https://squareup.com/help/article/5822-employee-permissions) in the **Shifts** category to allow other team members to access draft shifts. Published shifts are accessible by all team members.
- Some scheduling features require that the seller has an active [Shifts Plus](https://squareup.com/staff/shifts/pricing) subscription. For example, shifts that are scheduled more than 10 days in advance using the Labor API are visible in the Square Dashboard to sellers without a subscription but these shifts cannot be updated.
{% aside info="info" %}
The Labor API provides unrestricted access to schedule management, so these requirements don't apply to third-party scheduling applications.
{% /aside %}
- The color scheme for a scheduled shift cannot be changed. This property isn't exposed on the `ScheduledShift` object.
See additional [requirements and limitations](labor-api/manage-scheduled-shifts#requirements-and-limitations) for managing scheduled shifts.
## How scheduling works
Team schedules are made up of individual scheduled shifts spanning a given time period. To create a scheduled shift, first provide draft shift details such as the job ID, location ID, team member assignment, and start and end times. You can update draft shift details as needed and then publish the shift to make your changes public.
The following diagram shows the API call flow for managing a scheduled shift and the [webhook events](labor-api/webhooks) triggered by each request:
The simplest flow is from create to publish, but you can iteratively update and publish or republish. For more information about these flows, see [Manage Scheduled Shifts](labor-api/manage-scheduled-shifts).
*If the shift was never published, setting `draft_shift_details.is_deleted` to `true` in an `UpdateScheduledShift` request deletes the shift. Otherwise, the shift is just marked for deletion and you must publish the change to delete it.
{% aside type="info" %}
The diagram doesn't include calls used to obtain the `location_id`, `team_member_id`, and `job_id` from other Square APIs or calls to `RetrieveScheduledShift` and `SearchScheduledShifts` for retrieving information about a scheduled shift.
{% /aside %}
The following key concepts apply to scheduling with the Labor API:
{% accordion expanded=false %}
{% slot "heading" %}
### Scheduled shifts contain draft and published shift details
{% /slot %}
You work with two primary objects for shift management:
- [ScheduledShift](https://developer.squareup.com/reference/square/objects/ScheduledShift) - A specific time slot in a work schedule. This object is used to manage the draft and published versions of a shift:
- `draft_shift_details` - Stores the latest draft shift details.
- `published_shift_details` - Stores the current published shift details. This field is initially added when the scheduled shift is first published and then updated with every subsequent published version.
After the initial publish, you can determine whether there are unpublished changes by comparing `draft_shift_details` to `published_shift_details`.
- [ScheduledShiftDetails](https://developer.squareup.com/reference/square/objects/ScheduledShiftDetails) - The data type for the `draft_shift_details` and `published_shift_details` fields of a `ScheduledShift`. The following fields are required: `location_id`, `job_id`, `start_at`, and `end_at`.
Only the latest draft shift details and current published shift details are accessible for a scheduled shift.
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Draft shift details are writable, published shift details are read only
{% /slot %}
Draft shift details are writable using the `CreateScheduledShift` and `UpdateScheduledShift` endpoints.
To change the details for a published shift:
1. Call `UpdateScheduledShift` and provide the updated `draft_shift_details`.
2. Call `PublishScheduledShift` or `BulkPublishScheduledShifts` to make the changes public.
When a scheduled shift is published, Square copies `draft_shift_details` to `published_shift_details`.
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Team member notifications are optionally sent on publish
{% /slot %}
The `PublishScheduledShift` and `BulkPublishScheduledShifts` endpoints provide a `scheduled_shift_notification_audience` parameter that lets you control whether Square notifies team members about new, changed, or deleted shifts.
Notifications can be sent to affected team members only (default) or all active team members, or you can choose not to send notifications. Notifications are sent to the email address on record for [team members](https://developer.squareup.com/reference/square/objects/TeamMember).
{% /accordion %}
## Scheduling endpoints
The Labor API provides a set of endpoints used for managing team schedules. Applications using [OAuth](oauth-api/overview) to authorize API requests require the `TIMECARDS_WRITE` or `TIMECARDS_READ` permission to call scheduling endpoints.
### Managing scheduled shifts
Use the following endpoints to [create and manage](labor-api/manage-scheduled-shifts) scheduled shifts.
{% table %}
* Endpoint
* Permission {% width="145px" %}
* Description
-----
* [CreateScheduledShift](https://developer.squareup.com/reference/square/labor-api/create-scheduled-shift)
* `TIMECARDS_WRITE`
* Creates a scheduled shift by providing draft shift details such as job ID, team member assignment, and start and end times.
-----
* [UpdateScheduledShift](https://developer.squareup.com/reference/square/labor-api/update-scheduled-shift)
* `TIMECARDS_WRITE`
* Updates the draft shift details for a scheduled shift.
-----
* [PublishScheduledShift](https://developer.squareup.com/reference/square/labor-api/publish-scheduled-shift)
* `TIMECARDS_WRITE`
* Publishes a scheduled shift to make the current draft details visible to all team members.
-----
* [BulkPublishScheduledShifts](https://developer.squareup.com/reference/square/labor-api/bulk-publish-scheduled-shifts)
* `TIMECARDS_WRITE`
* Publishes 1 – 100 scheduled shifts to make the current draft details visible to all team members.
{% /table %}
### Retrieving scheduled shifts
Use the following endpoints to [retrieve and search](labor-api/retrieve-scheduled-shifts) scheduled shifts.
{% table %}
* Endpoint
* Permission {% width="135px" %}
* Description
-----
* [RetrieveScheduledShift](https://developer.squareup.com/reference/square/labor-api/retrieve-scheduled-shift)
* `TIMECARDS_READ`
* Retrieves a scheduled shift by ID.
-----
* [SearchScheduledShifts](https://developer.squareup.com/reference/square/labor-api/search-scheduled-shifts)
* `TIMECARDS_READ`
* Retrieves a paginated list of scheduled shifts, with optional filter and sort settings.
{% /table %}
{% aside type="info" %}
You can use the `scheduledShifts` entry point in [Square GraphQL](devtools/graphql) queries to access scheduling data through read-only operations. GraphQL queries can improve performance and reduce development time by letting you request exactly the data you need in fewer, more compact data transfers.
{% /aside %}
## See also
- [Manage Scheduled Shifts](labor-api/manage-scheduled-shifts)
- [Retrieve Scheduled Shifts](labor-api/retrieve-scheduled-shifts)
---
# Retrieve Scheduled Shifts
> Source: https://developer.squareup.com/docs/labor-api/retrieve-scheduled-shifts
> Status: BETA
> Languages: All
> Platforms: All
Use the Square Labor API to retrieve scheduled shifts and search for shifts by location, team member, date range, and assignment status.
**Applies to:** [Labor API](labor-api/what-it-does) | [Team API](team/overview) | [Locations API](locations-api)
{% subheading %}Use the [Labor API](https://developer.squareup.com/reference/square/labor-api) to search and retrieve scheduled shifts with flexible filtering options.{% /subheading %}
{% toc hide=true /%}
## Overview
Applications can use the Labor API to search and retrieve scheduled shifts. You can search shifts using various filters, including date ranges, locations, team members, assignment status, and published status.
{% aside type="info" %}
The Labor API defines two types of objects; be careful not to confuse them:
- A [ScheduledShift](https://developer.squareup.com/reference/square/objects/ScheduledShift) is used to manage team schedules.
- A [Timecard](https://developer.squareup.com/reference/square/objects/Timecard) represents a single work shift for a team member. Each `Timecard` captures:
- The actual time worked during one shift
- Information needed for payroll processing
For example, if an employee works five different shifts in a week, they will have five separate Timecard records - one for each shift.
**Note:** The older `Shift` object type is deprecated. Use Timecards instead. For information about migration, see [Migration notes](labor-api/what-it-does#migration-notes).
{% /aside %}
## Requirements and limitations
The following requirements and limitations apply when retrieving scheduled shifts using the Labor API.
* **Square API version** - Square API version 2025-05-21 or later is required to access or manage scheduled shifts.
* **Valid access token** - Square API requests require an `Authorization` header with a bearer access token. The examples in this topic use the {% tooltip text="Square Sandbox" %}An isolated server environment used for testing. API calls in the Sandbox use the "connect.squareupsandbox.com" domain and require an access token that's valid for Sandbox.{% /tooltip %}, so you can test using your [Sandbox access token](build-basics/access-tokens#get-a-personal-access-token).
{% accordion expanded=false %}
{% slot "heading" %}
#### More details
{% /slot %}
Applications using [OAuth](oauth-api/overview) access tokens to authorize requests typically require the following permissions when working with team schedules:
- `MERCHANT_PROFILE_READ` to retrieve location information.
- `EMPLOYEES_READ` to retrieve team member and job information.
- `TIMECARDS_READ` to retrieve scheduled shifts.
- `TIMECARDS_WRITE` to create, update, and publish scheduled shifts.
To call Square APIs in the production environment, change the base URL to `https://connect.squareup.com` and use your production (personal) access token.
{% /accordion %}
## Retrieve a specific shift
To retrieve a specific scheduled shift, call [RetrieveScheduledShift](https://developer.squareup.com/reference/square/labor-api/retrieve-scheduled-shift) and provide the shift ID.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The response returns the requested scheduled shift.
```json
{
"scheduled_shift": {
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
}
}
```
{% /tab %}
{% /tabset %}
## Search scheduled shifts
To search for scheduled shifts, call [SearchScheduledShifts](https://developer.squareup.com/reference/square/labor-api/search-scheduled-shifts) with optional filter and sort settings. By default, results are sorted by `start_at` in ascending order.
To list all scheduled shifts, call `SearchScheduledShifts` without any filters:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"scheduled_shifts": [
{
"id": "kxR8FWJE8DT3x7",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-3oZQKPKVk6gUXU_V5Qa",
"start_at": "2025-04-15T09:00:00-07:00",
"end_at": "2025-04-15T17:00:00-07:00",
"notes": "Opening shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 2,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T15:00:00-07:00"
},
{
"id": "kxR8FWJE8DT4x8",
"draft_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-4pZQKPKVk6gUXU_V5Qb",
"start_at": "2025-04-15T17:00:00-07:00",
"end_at": "2025-04-16T01:00:00-07:00",
"notes": "Closing shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"published_shift_details": {
"location_id": "KACM8A41GR60X",
"job_id": "jxR8EWJE8DT2x7",
"team_member_id": "-4pZQKPKVk6gUXU_V5Qb",
"start_at": "2025-04-15T17:00:00-07:00",
"end_at": "2025-04-16T01:00:00-07:00",
"notes": "Closing shift",
"is_deleted": false,
"timezone": "America/Los_Angeles"
},
"version": 1,
"created_at": "2025-04-02T14:58:49-07:00",
"updated_at": "2025-04-02T14:58:49-07:00"
}
]
}
```
{% /tab %}
{% /tabset %}
Use the optional `limit` field to control the {% tooltip text="page size" %}The maximum number of results to return in a single paged response.{% /tooltip %} (default 50, maximum 50) and the `cursor` field to page through the results. For more information, see [Pagination](build-basics/common-api-patterns/pagination).
### Filter and sort options
The following filter options can be used in a search query. Multiple filters in a query are combined as an `AND` operation, which means shifts must match all specified filters to be included in the results. For information about how some filters interact, see [Filter combinations](#filter-combinations).
{% table %}
* Field {% width="220px" %}
* Description
---
* `assignment_status`
* Returns shifts based on whether the `team_member_id` field is populated in the draft or published shift details. Valid values are `ASSIGNED` or `UNASSIGNED`. When omitted, it returns shifts with both statuses.
---
* `location_ids`
* Returns shifts for the specified locations. When omitted, it returns shifts for all locations. If needed, call [ListLocations](https://developer.squareup.com/reference/square/locations-api/list-locations) to get location IDs.
---
* `scheduled_shift_statuses`
* Returns shifts based on the draft or published status of the shift. A published shift has `published_shift_details`. Draft shifts either don't have that field or it differs from the draft details. Valid values are `DRAFT` or `PUBLISHED`. When omitted, it returns shifts with both statuses.
---
* `start`
* Returns shifts whose `start_at` time is within the specified time range (inclusive).
---
* `end`
* Returns shifts whose `end_at` time is within the specified time range (inclusive).
---
* `team_member_ids`
* Returns shifts assigned to the specified team members. When omitted, it returns all assigned and unassigned shifts. If needed, call [SearchTeamMembers](https://developer.squareup.com/reference/square/team-api/search-team-members) to get team member IDs.
---
* `workday`
* Returns shifts based on a workday date range. For more information, see [Workday filter](#workday-filter).
{% /table %}
Use the following fields to sort the query. By default, results are sorted by `START_AT` and `ASC`.
{% table %}
* Field {% width="120px" %}
* Description
---
* `field`
* The field to sort by. Valid values are `START_AT` (default), `END_AT`, `CREATED_AT`, or `UPDATED_AT`.
---
* `order`
* The sort order. Valid values are `DESC` (default) or `ASC`.
{% /table %}
#### Workday filter
The `workday` filter provides a way to search scheduled shifts using `YYYY-MM-DD` calendar dates. You define whether to match shifts based on their start time, their end time, or either their start time or end time.
```json
"query": {
"filter": {
"workday": {
"match_shifts_by": "START_AT",
"date_range": {
"start_date": "2024-10-14",
"end_date": "2024-10-27"
}
}
}
}
```
This filter has three components:
{% table %}
* Component
* Description
---
* `date_range`
* Specifies the `start_date` and `end_date` of the date range to match against.
---
* `match_shifts_by`
* Controls how shifts are matched against the date range. Valid values:
- `START_AT` - Match shifts that start within the date range.
- `END_AT` - Match shifts that end within the date range.
- `INTERSECTION` - Match shifts that start or end within the date range.
---
* `default_timezone`
* The time zone to use for date matching, in IANA format (for example, "America/Los_Angeles"). Required if the shift location doesn't define a time zone.
{% /table %}
{% anchor id="filter-combinations" /%}
#### Filter combinations
When combined in a query, certain filters might interact in ways that aren't immediately apparent. Understanding the interactions between the following combinations can help you create more effective queries:
* **Team member and assignment status**:
- Using `team_member_ids` alone returns shifts for the specified team members plus all unassigned shifts.
- Add `assignment_status: "ASSIGNED"` to only get shifts assigned to the specified team members.
* **Shift status and assignment status**:
- The `scheduled_shift_statuses` filter affects which shift details are checked:
- `DRAFT` - Evaluates `draft_shift_details` (includes unpublished shifts and shifts with modified drafts).
- `PUBLISHED` - Evaluates `published_shift_details`.
- `DRAFT` and `PUBLISHED` (default) - Evaluates both sets of details.
- The assignment status is evaluated against the specified shift details.
- Shifts marked for deletion (`is_deleted: true`) are ignored with the `DRAFT` status filter.
* **Date range filters**:
- The `start` and `end` filters use exact timestamps.
- The `workday` filter uses calendar dates and can match shifts based on different criteria.
- When both are specified, shifts must match both conditions.
### Example: Published shifts at a specified location and date range
The following example finds all published shifts that start during a specific time window at the specified location:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"scheduled_shifts": [
{
"id": "K0YH4CV5462JB",
"draft_shift_details": {
"team_member_id": "TMDHAOU2N4I8RWi2",
"location_id": "PAA1RJZZKXBFG",
"job_id": "gad1UVkdSodJ1F4PCzoA8y6d",
"start_at": "2025-01-25T03:00:00-05:00",
"end_at": "2025-01-25T09:00:00-05:00",
"notes": "Don't forget to prep the vegetables and pull the dough",
"is_deleted": false,
"timezone": "America/New_York"
},
"published_shift_details": {
"team_member_id": "TMDHAOU2N4I8RWi2",
"location_id": "PAA1RJZZKXBFG",
"job_id": "gad1UVkdSodJ1F4PCzoA8y6d",
"start_at": "2025-01-25T03:00:00-05:00",
"end_at": "2025-01-25T09:00:00-05:00",
"notes": "Don't forget to prep the vegetables and pull the dough",
"is_deleted": false,
"timezone": "America/New_York"
},
"version": 4,
"created_at": "2024-12-31T03:11:24Z",
"updated_at": "2024-12-31T06:52:01Z"
}
]
}
```
{% /tab %}
{% /tabset %}
{% anchor id="workday-start-at" /%}
### Example: Workday matching START_AT
The following example gets all published and assigned shifts on the specified date at the specified location, matching shifts based on their start time:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"scheduled_shifts": [
{
"id": "K0YH4CV5462JB",
"draft_shift_details": {
"team_member_id": "TMDHAOU2N4I8RWi2",
"location_id": "PAA1RJZZKXBFG",
"job_id": "gad1UVkdSodJ1F4PCzoA8y6d",
"start_at": "2025-01-25T03:00:00-05:00",
"end_at": "2025-01-25T09:00:00-05:00",
"notes": "Don't forget to prep the vegetables and pull the dough",
"is_deleted": false,
"timezone": "America/New_York"
},
"published_shift_details": {
"team_member_id": "TMDHAOU2N4I8RWi2",
"location_id": "PAA1RJZZKXBFG",
"job_id": "gad1UVkdSodJ1F4PCzoA8y6d",
"start_at": "2025-01-25T03:00:00-05:00",
"end_at": "2025-01-25T09:00:00-05:00",
"notes": "Don't forget to prep the vegetables and pull the dough",
"is_deleted": false,
"timezone": "America/New_York"
},
"version": 4,
"created_at": "2024-12-31T03:11:24Z",
"updated_at": "2024-12-31T06:52:01Z"
}
]
}
```
{% /tab %}
{% /tabset %}
## See also
* [Scheduling with the Labor API](labor-api/scheduling)
* [Manage Scheduled Shifts](labor-api/manage-scheduled-shifts)
* [Labor API](labor-api/what-it-does)
* [Team API](team/overview)
---
# Square Model Context Protocol Server
> Source: https://developer.squareup.com/docs/mcp
> Status: BETA
> Languages: All
> Platforms: All
Learn about the Square MCP server, which implements the MCP standard and provides a bridge between AI assistants and the Square REST API platform.
{% subheading %}The Square Model Context Protocol (MCP) server implements the [Model Context Protocol](https://modelcontextprotocol.io) standard, providing a bridge between AI assistants and the Square REST API platform.{% /subheading %}
## Overview
{% aside type="info" %}
The Square MCP server is currently in Beta. To provide feedback or report bugs, open [GitHub issues](https://github.com/square/square-mcp-server/issues).
{% /aside %}
To view the MCP server source or contribute to the project, see [GitHub - square/square-mcp-server](https://github.com/square/square-mcp-server/).
You can configure your AI agent to use the Square MCP server hosted by Block as a remote server or you can set up and run the server locally for your AI agent's use. For information about running the Square MCP server locally, see [Local Square MCP server quickstart](#local-server-quickstart).
## Square MCP server
The Square remote MCP server is hosted at:
```
https://mcp.squareup.com/sse
```
### MCP server tools
The Square MCP server connects your AI tools directly to the full Square API platform, giving you programmatic access to everything the APIs offer—customers, orders, items, and more. Use it to power natural language queries, generate code, and accelerate development with AI assistance.
Square recommends using the remote MCP server, which supports OAuth login with more control and granular permissions. This lets you securely sign in with your Square account and authorize only the scopes your application needs, with no manual token management required.
For testing, you can run a local instance configured to access a seller's Sandbox environment. Remote instances only access production resources.
{% aside type="important" %}
Square recommends that you become familiar with the server and test your prompts against a Square account Sandbox environment before using it in production.
{% /aside %}
## Integration with AI assistants
The Square MCP server works with many different AI assistants including:
* [Claude.ai](https://claude.ai)
* [Claude Desktop](https://claude.ai/download)
* [Goose](https://block.github.io/goose/)
* [Cursor](https://www.cursor.com/)
* [Windsurf](https://codeium.com/windsurf)
## Integrate with Claude.ai
Add the Square MCP server to Claude.
### For Claude Enterprise & Teams (owners and primary owners)
1. Navigate to **Settings > Integrations** (for Teams) or **Settings > Data management** (for Enterprise).
1. In the **Integrations** section, choose **Add more**.
1. Add the Square MCP server URL: `https://mcp.squareup.com/sse`.
1. To finish configuring your integration, choose **Add**.
### For Claude Max
1. Navigate to **Settings > Profile**.
1. In the **Integrations** section, choose **Add more**.
1. Add the Square MCP server URL: `https://mcp.squareup.com/sse`.
1. To finish configuring your integration, choose **Add**.
### Enable the Square integration
1. Open a chat with Claude.
2. In the chat interface, access the **Search and tools** menu.
3. Choose **Connect** to authenticate with your Square account.
4. After connecting, use the same menu to enable specific Square tools.
## Integrate with Claude Desktop
### Remote MCP
Add an entry to `claude_desktop_config.json` as shown in the following example:
```json
{
"mcpServers": {
"mcp_square_api": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.squareup.com/sse"]
}
}
}
```
This approach allows you to authenticate directly with your Square account credentials without needing to manage access tokens.
### Local MCP
Add an entry to `claude_desktop_config.json` as shown in the following example:
```json
{
"mcpServers": {
"mcp_square_api": {
"command": "npx",
"args": ["square-mcp-server", "start"],
"env": {
"ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
"SANDBOX": "true"
}
}
}
}
```
## Integrate with Goose
[Install Goose](https://block.github.io/goose/docs/getting-started/installation) and then configure the Square MCP server as an extension for the Goose Desktop and Goose CLI. The Goose Desktop and CLI share the same configuration file so you only need to configure the MCP server once.
### Remote MCP server
To install the Square remote MCP server in Goose, click the [Open Goose](goose://extension?cmd=npx&arg=mcp-remote&arg=https%3A%2F%2Fmcp.squareup.com%2Fsse&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote) link on any computer with Goose installed, choose **Open Goose**, and then choose **OK** to confirm the extension installation. You can also copy and paste the URL into your browser's address bar.
### Local MCP server
To install the Square remote MCP server in Goose, run the following command:
```bash
npx square-mcp-server install # Auto-install local MCP for Goose
npx square-mcp-server get-goose-url # Output a manual config URL
```
To learn more about using the Square MCP server with Goose, see [Square MCP Extension](https://block.github.io/goose/docs/tutorials/square-mcp).
## Integrate with Cursor
To connect [Cursor](https://www.cursor.com/) with the Square MCP server, following the instructions for a remote or local MCP server.
### Remote MCP server
Choose `Type`: "Command" and in the `Command` field, enter the following (recommended for OAuth authentication):
```
npx mcp-remote https://mcp.squareup.com/sse
```
This allows you to log in with your Square account directly instead of managing access tokens.
### Local MCP server
Choose `Type`: "Command" and in the `Command` field, enter the following:
```
npx square-mcp-server start
```
## Integrate with Windsurf
Connect the Square MCP server to [Windsurf](https://codeium.com/windsurf) by editing the [`mcp_config.json` file](https://docs.codeium.com/windsurf/mcp):
### Remote MCP server
```json
{
"mcpServers": {
"square_api": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.squareup.com/sse"]
}
}
}
```
Using the remote MCP server enables OAuth authentication, allowing you to connect with your Square account credentials without managing access tokens.
{% aside type="info" %}
Square maintains an allowlist of MCP clients in order to protect against malicious client registration attempts. If you want your client added to the allowlist, please request an addition in the [Square developer forum](https://developer.squareup.com/forums/c/mcp/14).
{% /aside %}
### Local MCP server
```json
{
"mcpServers": {
"square_api": {
"command": "npx",
"args": ["square-mcp-server", "start"],
"env": {
"ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
"SANDBOX": "true"
}
}
}
}
```
---
{% anchor id="local-server-quickstart" /%}
## Local Square MCP server quickstart
To run a local instance, you need to have [Node.js](https://nodejs.org/en/download) installed. You can then set up and run the Square MCP server with a single command:
```bash
npx square-mcp-server start
```
To configure environment variables inline:
```bash
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start
```
To configure environment variables for local development:
```bash
npx /path/to/project/square-mcp-server
```
{% aside type="info" %}
You need your Square access token. For more information, see [Access Tokens and Other Square Credentials](https://developer.squareup.com/docs/build-basics/access-tokens).
{% /aside %}
### Local configuration
Set the following environment variables as needed:
| Variable | Purpose | Example |
|----------------------|--------------------------------------|--------------------------------|
| `ACCESS_TOKEN` | Your Square API access token | `ACCESS_TOKEN=sq0atp-...` |
| `SANDBOX` | Use the Square sandbox environment | `SANDBOX=true` |
| `PRODUCTION` | Use the Square production environment | `PRODUCTION=true` |
| `DISALLOW_WRITES` | Restrict to read-only operations | `DISALLOW_WRITES=true` |
| `SQUARE_VERSION` | Specify the Square API version | `SQUARE_VERSION=2025-04-16` |
---
# Python SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/python/migration
> Status: PUBLIC
> Languages: Python
> Platforms: All
Upgrade from the legacy version of the Square Python SDK to version 42.0.0 or later.
Version `42.0.0.20250416` of the Python SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `41.0.0.20250319` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
The new version of the Python SDK introduces breaking changes in the client class.
```python
// LEGACY
import os
from square_legacy.client import Client as LegacySquare
client = LegacySquare(
environment="sandbox",
access_token=os.environ.get("SQUARE_TOKEN")
)
// NEW
import os
from square import Square
from square.environment import SquareEnvironment
client = Square(
environment=SquareEnvironment.SANDBOX,
token=os.environ.get("SQUARE_TOKEN")
)
```
{% table %}
* Legacy {% width="165px" %}
* New {% width="180px" %}
* Additional information
---
* `environment`
* `environment`
* An enumeration for specifying the environment (`SANDBOX` or `PRODUCTION`).
---
* `access_token`
* `token`
* The access token used for authentication.
---
* `custom_url`
* `base_url`
* The base URL for API requests.
---
* `square_version`
* `version`
* The Square API version to use.
---
* `additional_headers`
* `additional_headers`
* Additional headers can be set at individual methods.
---
* `http_call_back`
* Removed
* This option has been removed.
---
* `user_agent_detail`
* Removed
* This option has been removed.
{% /table %}
## Use the legacy and new SDK side by side
While the new SDK has many improvements, it takes time to upgrade when there are breaking changes. To make the migration easier, the old SDK is published as `squareup_legacy` so that the two SDKs can be used side by side in the same project.
The following example shows how to use the new and legacy SDKs inside a single file:
```python
from square_legacy.client import Client as LegacySquare
from square import Square
def main():
client = Square(token=os.environ.get("SQUARE_TOKEN"))
legacy_client = LegacySquare(access_token=os.environ.get("SQUARE_TOKEN"))
# List all payments with the new client.
new_response = client.payments.list()
# List all payments with the legacy client.
legacy_response = legacy_client.payments.list_payments()
```
You should migrate to the new SDK using the following steps:
1. Upgrade the PyPi package to `^42.0.0`.
2. Run `pip install squareup_legacy`.
3. Search and replace all requires and imports from `square` to `square_legacy`.
4. Gradually introduce methods from the new SDK by importing them from the Square import.
## TypedDict requests
The previous version of the SDK relied on simple Python dictionaries to represent request body properties. For example, consider the following method call required to create a customer:
```python
// LEGACY
response = client.customers.create_customer(
{
"idempotency_key": str(uuid.uuid4()),
"given_name": 'given-vs1',
"family_name": 'family-vs1',
"address": {
"address_line_1": '1955 Broadway',
"address_line_2": 'Oakland, CA 94612'
}
)
```
In the new SDK, requests are now defined with [`TypedDict`](https://typing.python.org/en/latest/spec/typeddict.html#typeddict) types. The UX is similar, but you're now presented with `**kwargs` for each parameter to better guide you through the expected set of parameters.
```python
// NEW
response = client.customers.create(
idempotency_key=str(uuid.uuid4()),
given_name="given-vs1",
family_name="family-vs1",
address={
"address_line_1": "1955 Broadway",
"address_line_2": "Oakland, CA 94612"
}
)
```
## Pydantic responses
The new SDK uses [Pydantic](https://docs.pydantic.dev), a popular Python validation library, to define response models. With this, response types now have a better
autocompletion experience and properties can be accessed with dot-notation rather than free-form dictionary access.
```python
// LEGACY
response = client.locations.list_locations()
location = response.body['locations'][0]
name = location['name']
// NEW
response = client.locations.list()
location_name = response.locations[0]
name = location.name
```
## Exceptions
The legacy SDK represents successful calls and errors with the same `ApiResponse` type. Users could distinguish between successes and errors as shown:
```python
// LEGACY
response = client.locations.list_locations()
if response.is_success():
for location in response.body['locations']:
print(f"{location['id']}: ", end="")
print(f"{location['name']}, ", end="")
print(f"{location['address']['address_line_1']}, ", end="")
print(f"{location['address']['locality']}")
elif response.is_error():
for error in response.errors:
print(error['category'])
print(error['code'])
print(error['detail'])
```
The new SDK represents errors as `Exceptions`, all of which inherit from the `ApiError` class. The `ApiError` class includes the Square `Error` type.
```python
from square.core.api_error import ApiError
try:
response = client.locations.list()
for location in response.items:
print(f"{location.id}: ", end="")
print(f"{location.name}, ", end="")
print(f"{location.address.address_line_1}, ", end="")
print(f"{location.address.locality}")
except ApiError as e:
for error in e.errors:
print(error.category)
print(error.code)
print(error.detail)
```
## Auto-pagination
Square's paginated endpoints now support auto-pagination with an iterator. Callers don't need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.
The following example shows the same code, with the legacy and new SDKs:
```python
// LEGACY
result = client.customers.list_customers(
limit=10,
sort_field='DEFAULT',
sort_order='DESC'
)
if result.is_success():
while (result.body != {}):
for cust in result.body['customers']:
print(f"customer: ID: {cust['id']}, ", end="")
print(f"Version: {cust['version']}, ", end="")
print(f"Given name: {cust['given_name']}, ", end="")
print(f"Family name: {cust['family_name']}")
if (result.cursor):
result = client.customers.list_customers(
limit=limit,
sort_field='DEFAULT',
sort_order='DESC',
cursor=result.cursor
)
else:
break
elif result.is_error():
for error in result.errors:
print(error['category'])
print(error['code'])
print(error['detail'])
// NEW
try:
response = client.customers.list(
limit=10,
sort_field='DEFAULT',
sort_order='DESC'
)
for customer in response:
print(f"customer: ID: {customer.id}, ", end="")
print(f"Version: {cutomer.version}, ", end="")
print(f"Given name: {customer.given_name}, ", end="")
print(f"Family name: {customer.family_name}")
except ApiError as e:
for error in e.errors:
print(error.category)
print(error.code)
print(error.detail)
```
---
# Develop for Japan
> Source: https://developer.squareup.com/docs/international-development/japan
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn about regional differences and requirements related to building integrations for Japanese sellers.
## Overview
You can use Square APIs and SDKs to build applications that support and process in-person or online payments for sellers in Japan. Before you begin development, be sure to familiarize yourself with which [payment methods](payment-card-support-by-country) are available in Japan and the [pricing models](payments-pricing) for payments made with Square APIs and Square hardware.
## In-Person Payment Solutions
### Integration Options for Your POS System
If you have an existing POS system and want to connect to Square in-person payment solutions in Japan, you have two integration options:
* The [Terminal API](terminal-api/overview) is compatible with Square Terminal devices. It connects directly to Square servers, making it available for almost any system, including Windows-based systems, web applications, or other platforms, because it connects directly to Square servers.
* The [Point-of-Sale API](pos-api/what-it-does) works with Square Reader devices and operates via mobile devices only. It uses the Square mobile app for checkout, utilizing deep link functionality to switch between your app and Square.
#### Key considerations when choosing an API:
* If your goal is to process itemized orders, the Terminal API is your only option.
* The Point-of-Sale API supports only custom amount-based transactions.
* If your external POS system manages itemized orders, syncing itemized sales with Square can allow you to:
* Print itemized receipts.
* Keep itemized transactions synchronized between systems.
When implementing in-person payment applications, you should process payments in-store with the [Square Terminal](https://squareup.com/jp/ja/hardware/terminal) or [Square Reader](https://squareup.com/jp/ja/hardware/reader) devices. Staff must be present in the store or close enough to attend at any time when payment processing is required.
### Itemized vs. Non-Itemized Approaches
When integrating with Square in-person payment APIs, you'll need to choose between two integration approaches based on your business needs:
{% tabset %}
{% tab id="Itemized" %}
This approach is best for merchants who want to log itemized transactions in Square and want the Square Terminal or Square's compatible printers to print itemized receipts.
**How it works**:
* Use the [Orders API](orders-api/what-it-does) to create orders with line items.
* Pass the Square order ID to the [Terminal API](terminal-api/overview) to process payments and print itemized receipts.
* Use the [Catalog API](catalog-api/what-it-does) to sync products between your system and Square.
* Optionally, use [Terminal Actions](terminal-api/advanced-features) to programmatically print receipts as a separate operation.
**Limitations**:
* Formal receipts are not currently supported - only normal receipts can be printed.
This approach is ideal when you want Square Terminal to handle receipt printing, want to leverage Square's reporting and analytics capabilities, or need product-level sales tracking for your business.
{% /tab %}
{% tab id="Non-Itemized (Custom Amount)" %}
This approach is best suited for merchants with a custom POS system and existing printer integration for order management.
**How it works**: You send only the total payment amount to Square. Square processes the payment but does not store details of the individual items. Only the custom payment amount is recorded.
**Limitations**:
* Square cannot track or print itemized receipts for these transactions.
* If you need detailed transaction records, you must print receipts using your own receipt printing system.
{% /tab %}
{% /tabset %}
### Supported Payment Methods for In-Person Payments
Japanese merchants can accept several payment methods for in-person transactions, including credit cards, digital wallet payments (Apple Pay and Google Pay), gift cards, e-money, prepaid IC cards (such as SUICA and PASMO), and QR code payments (such as PayPay, Alipay, Rakuten Pay, and au PAY).
{% aside type="important" %}
To support e-money or PayPay payments, Japanese sellers must submit an application form to activate those payment methods.
For more information, see:
- [Apply for Electronic Money](https://squareup.com/help/jp/ja/article/6711-jp-only-e-money-application)
- [Apply for QR Code](https://squareup.com/help/jp/ja/article/8370-apply-for-qr-code-payments)
{% /aside %}
### API Comparison for In-Person Payments
{% table %}
* Feature
* Terminal API
* Point-of-Sale API
* Mobile Payments SDK
---
* Device Type
* Square Terminal
* Square Reader
* Square Reader
---
* Connection Method
* Connection to Square server
* Link to Square Point of Sale app
* Direct SDK integration
---
* Itemized Orders Support
* ✅ Supported (with Orders API)
* ❌ Not supported
* -
---
* Custom Amount Support
* ✅ Supported
* ✅ Supported
* -
---
* Accepted Payment Methods
* credit card, e-money, QR, gift card
* credit card, e-money, QR, gift card
* -
---
* SDK/API Status in Japan
* ✅ Available
* ✅ Available
* ❌ Not yet available
---
* Documentation
* [Terminal API Overview](terminal-api/overview)
* [Point of Sale API Overview](pos-api/what-it-does)
* [Mobile Payments SDK Overview](mobile-payments-sdk)
{% /table %}
### Testing In-Person Payment Integrations
Square provides a Sandbox environment where you can test your in-person payment integrations before going live. However, there are important differences between Sandbox and production testing for physical devices.
#### Sandbox Testing (Without Physical Devices):
You can test Terminal API integrations in the Sandbox without connecting to a physical Square Terminal. Square provides special test device IDs that simulate different checkout scenarios, including successful payments, canceled payments, and timeout scenarios. This allows you to develop and test your integration logic without needing physical hardware.
The Sandbox environment supports testing various payment methods specific to Japan, including:
* **E-money (FELICA) payments** - Test e-money/FeLiCa transactions using dedicated test device IDs
* **QR code payments (PayPay)** - Test PayPay QR code payments (note: the Sandbox location must be based in Japan)
**Example Test Device IDs:**
{% table %}
* Payment Method
* Test Device ID
* Notes
---
* Credit Card (Successful)
* `9fa747a2-25ff-48ee-b078-04381f7c828f`
* Checkout successfully completed with credit card.
---
* E-money (FELICA)
* `19a01fbd-3dcd-4d9f-a499-a641684af745`
* eMoney/FeLiCa payment for the full amount is approved.
---
* QR Code (PayPay)
* `cae0ee02-f83b-11ec-b939-0242ac120002`
* PayPay QR code payment for the full amount is approved. Sandbox location must be based in Japan {% line-break /%} __Note:__ In the sandbox environment, PayPay is the only QR code brand name that appears.
{% /table %}
For a complete list of test device IDs and their behaviors, see [Terminal API Sandbox Testing](devtools/sandbox/testing#terminal-api-checkouts).
#### Production Testing (With Physical Devices):
Testing with an actual Square Terminal device is only supported in the production environment. The Sandbox environment does not support connections to physical Square Terminal devices. When testing with a physical device in production, you can use the minimum payment amount of 1 yen to minimize testing costs.
Use the following workflow for testing:
1. Conduct initial development and testing in Sandbox using test device IDs.
2. Perform final testing in production using a Square Terminal and small payment amounts (minimum 1 yen).
For more information, see [Test Square APIs in the Sandbox](devtools/sandbox/testing).
## Online Payment Solutions
### Payments Made on a Buyer's Screen
For online payments in Japan, merchants can accept credit cards, debit cards, gift cards, and digital wallet payments (Apple Pay and Google Pay) when customers purchase through a web browser or mobile app.
You can build custom checkout forms using either the [Web Payments SDK](web-payments/overview) or [In-App Payments SDK](in-app-payments-sdk/what-it-does), and you can [localize these forms](in-app-payments/localize-ios) from English to Japanese to provide a better customer experience.
* Use the **Web Payments SDK** for web applications or browser-based checkouts (desktop and mobile).
* Use the **In-App Payments SDK** for native mobile applications on iOS and Android.
### 3D Secure (3DS) Requirement for Online Payments
{% aside type="important" %}
This is a critical requirement for all merchants operating in Japan. [3D Secure (3DS) authentication](sca-overview) is **mandatory** for all online card payments in Japan. All merchants and integrations must comply with this regulation.
{% /aside %}
**What does this mean for your integration?**
* Depending on the card issuer, 3DS authentication may be required during card transactions.
* Use the [Web Payments SDK](web-payments/take-card-payment) or [In-App SDK](sca-overview-iap) to implement the 3DS flow.
* Merchants cannot disable or opt out of 3DS in Japan.
## Sales Reporting
### FELICA Payments
In a [Payment](https://developer.squareup.com/reference/square/objects/Payment) object, gift cards, credit cards, debit cards, and e-money (FELICA) payments are all recorded with a `source_type` of `CARD`. Detailed information is available through the `card_details` field. [Terminal checkout objects](https://developer.squareup.com/reference/square/objects/TerminalCheckout) also use the `CheckoutOptionsPaymentType` enum to denote whether the payment was made with a card, e-money, or QR.
To retrieve payment information, you can use the [GetTerminalCheckout]((https://developer.squareup.com/reference/square/square/terminal-api/get-terminal-checkout)), [RetrieveOrder](https://developer.squareup.com/reference/square/square/orders-api/retrieve-order), or [GetPayment](https://developer.squareup.com/reference/square/square/payments-api/get-payment) endpoints depending on your needs.
The `card_details` object includes a `card_brand` enum that helps you distinguish between different payment methods.
* Credit cards show the international brand name (such as `VISA` or `Mastercard`).
* E-money payments show `FELICA`.
The `electronic_money_details.felica_details` field shows details specific to FeliCa payments, including `felica_brand` (either `FELICA_QP`, `FELICA_TRANSPORTATION`, `FELICA_ID`, or `UNKNOWN`).
{% accordion expanded=false%}
{% slot "heading" %}
### Example Payment object
{% /slot %}
```json
{
"payment": {
"id": "{PAYMENT_ID}",
"created_at": "2023-10-13T21:14:29.577Z",
"updated_at": "2023-10-13T21:14:30.504Z",
"amount_money": {
"amount": 5000,
"currency": "JPY"
},
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "FELICA"
}
}
}
}
```
{% /accordion %}
{% accordion expanded=false%}
{% slot "heading" %}
### Example Order object
{% /slot %}
```json
{
"order": {
"id": "{ORDER_ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"updated_at": "2023-10-13T21:15:55.504Z",
"tenders": [
{
"id": "{PAYMENT_ID}",
"location_id": "{LOCATION_ID}",
"transaction_id": "{TRANSACTION_ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"amount_money": {
"amount": 5000,
"currency": "JPY"
},
"type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "FELICA",
"last_4": "{LAST_FOUR}"
},
"entry_method": "CONTACTLESS"
}
}
]
}
}
```
{% /accordion %}
#### Point of Sale API workflow for E-Money payments
1. Get a transaction ID from a completed checkout.
2. Retrieve the corresponding Order object using the Orders API.
3. Use the `tenders.id` value to get a Payment object with [GetPayment](https://developer.squareup.com/reference/square/square/payments-api/get-payment). The Payment object will return `CardPaymentDetails.Card.CardBrand` with the value `FELICA`.
**Terminal checkouts** use `payment_ids` for payments, so you can use `GetPayment` directly to get payment information without needing to go through the Order object first.
For non-itemized sales, the `item_type` for orders created with e-money payments, are `CUSTOM`, because there's a custom amount for the payment. Itemized sales use the `ITEM` item type instead.
For more information, see [Take E-Money Payments in Japan](pos-api/cookbook/electronic-payments).
### QR Code Payments
The [wallet_details](https://developer.squareup.com/reference/square/objects/Payment#definition__property-wallet_details) property in a `Payments` object supports several QR code brands, including:
* `PAYPAY`
* `ALIPAY`
* `RAKUTEN_PAY`
* `AU_PAY`
* `D_BARAI`
* `MERPAY`
* `WECHAT_PAY`.
If a different brand is used that doesn't match these values, it is recorded as `UNKNOWN`.
**Example Order object with a QR code payment:**
```json
{
"order": {
"id": "{ORDER_ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"updated_at": "2023-10-13T21:15:55.504Z",
"tenders": [
{
"id": "{PAYMENT_ID}",
"location_id": "{LOCATION_ID}",
"transaction_id": "{ORDER_ID}",
"created_at": "2023-10-13T21:15:55.504Z",
"note": "a custom note description",
"amount_money": {
"amount": 100,
"currency": "JPY"
},
"processing_fee_money": {
"amount": 3,
"currency": "JPY"
},
"type": "WALLET"
}
]
}
}
```
Note that the `tenders` object array in an order object doesn't have a value defined for `wallet_details`.
For implementation guides on accepting QR code payments, see
* [Accept PayPay Payments in Japan for the Point of Sale API](pos-api/qr-code-payments-paypay)
* [PayPay QR Code Payments for the Terminal API](terminal-api/international-payment-methods/paypay-qr-code-payments)
* [Take E-Money Payments in Japan](pos-api/cookbook/electronic-payments).
{% aside type="info" %}
**Data retention**
The Square Developer Console shows data for 1 year, but [API logs](devtools/api-logs) are retained for only 28 days. You can view API logs in the Developer Console or API Explorer. Use the Square API Explorer and API Logs to capture historical data about payments and purchases.
{% /aside %}
## Error Handling for Failed Requests
When a request fails, Square API endpoints return a response with an `errors` field containing one or more `Errors`.
### Key considerations for Japan
* **Error messages are always returned in English**. You need to retrieve the error object as a JSON object and translate the error details for Japanese users. Your application should take appropriate action based on the `error.category`, `error.code`, and `error.field` (which indicates where the error occurred).
* **Specific refund limitations for transportation cards**. If a buyer uses a PASMO or SUICA transportation card for a payment, you encounter a `REFUND_DECLINED` error. The seller cannot issue a refund for those payment cards.
**Example refund decline error response:**
```json
{
"errors": [
{
"code": "REFUND_DECLINED",
"detail": "Payment could not be refunded",
"category": "REFUND_ERROR"
}
]
}
```
### Errors with Canceling an E-Money Payment
Using [CancelTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/cancel-terminal-checkout) to cancel an e-money payment after getting an error on the Square Terminal is not supported.
If an error occurs on Square Terminal during an e-money payment, the checkout request has the `IN_PROGRESS` or `PENDING` state. In this situation, the buyer must manually cancel the checkout. To do so:
* Close the error message window
* Tap the navigation button back to the checkout screen
* Cancel the checkout manually.
---
# Add a Content Security Policy
> Source: https://developer.squareup.com/docs/web-payments/content-security-policy
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to add a content security policy to your application that takes payments with Web Payments SDK.
{% subheading %} Learn how to implement a Content Security Policy with vendor scripts in your Web Payments SDK integration. {% /subheading %}
## Overview
A [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP) is a critical security feature that helps protect your Web Payments SDK integration from various attacks, specifically cross-site scripting (XSS) attacks. To comply with the latest PCI DDS security requirements, your application must provide a CSP vendor script for a supported payment method, so that the Web Payments SDK can securely process payments through the payment method, and enable the CSP to protect your application from external scripting attacks.
## What CSP provides
CSP provides several key security benefits:
- Controls which resources (scripts, styles, images) can load
- Specifies allowed origins for content
- Prevents malicious script injection
- Manages secure communication with payment endpoints
## Requirements and limitations
- Web Payments SDK installed and integrate with an application
- Access to modify your application's headers
- An HTTPS-enabled environment for development
## Set up CSP
If your application deploys a Content Security Policy (CSP) with the Web Payments SDK, you must enable the following CSP directives to add an additional security layer.
1. Modify the headers.
In `index.html`, add the CSP meta tag or header to your application:
For Sandbox Environment:
```html
```
For Production:
```html
```
2. Add the vendor scripts.
Include the necessary payment scripts in your HTML:
{% tabset %}
{% tab id="Square" %}
```html
```
{% /tab %}
{% tab id="Cash App Pay" %}
```html
```
{% /tab %}
{% tab id="Afterpay" %}
```html
```
{% /tab %}
{% tab id="ACH" %}
```html
```
{% /tab %}
{% tab id="Google Pay" %}
```html
```
{% /tab %}
{% /tabset %}
3. Implement error handling in the application.
Add error handling for the following script loading failures in the application:
```javascript
// Monitor script loading
window.addEventListener('error', function(e) {
if (e.target.src && e.target.src.includes('square.js')) {
console.error('Square script failed to load:', e);
handleScriptLoadError();
}
});
function handleScriptLoadError() {
// Implement your fallback logic
const paymentForm = document.getElementById('payment-form');
if (paymentForm) {
paymentForm.innerHTML = 'Payment temporarily unavailable. Please try again later.';
}
// Notify your error monitoring service
notifyErrorService('Square script load failure');
}
```
4. Verify the CSP implementation.
1. Check the console with a web browser:
- Look for CSP violation messages.
- Verify script loading success.
2. Test a payment flow:
```javascript
async function testPaymentFlow() {
try {
const payments = Square.payments(appId, locationId);
const card = await payments.card();
await card.attach('#card-container');
console.log('Payment flow initialized successfully');
} catch (e) {
console.error('Payment flow test failed:', e);
}
}
```
3. Validate in different environments:
- Test in sandbox environment first.
- Verify in staging (if applicable).
- Confirm in production.
## Common issues and solutions
Script loading failures:
- Verify CSP directives match script sources.
- Check for network connectivity.
- Confirm that the script URLs are correct.
CSP violations:
- Review browser console for specific violation messages.
- Update CSP to include missing sources.
- Verify all resource domains are included.
Integration conflicts:
- Check for conflicts with other security headers.
- Verify compatibility with other third-party scripts.
- Test with all payment methods.
## Best practices
Security:
- Use specific source URLs rather than wildcards
- Minimize use of 'unsafe-inline' and 'unsafe-eval'
- Regularly review and update CSP rules
Performance:
- Load scripts asynchronously when possible
- Implement proper error handling
- Monitor script loading performance
Maintenance:
- Document all CSP modifications
- Keep track of vendor script versions
- Regular testing of all payment flows
## Additional resources
- [Mozilla - Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
- [CSP Evaluator tool](https://csp-evaluator.withgoogle.com/)
---
# Set Up the Web Client Application
> Source: https://developer.squareup.com/docs/web-payments/quickstart/set-up-web-client-app
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to set up a web client application with the Web Payments SDK quickstart sample project.
**Applies to:** [Web Payments SDK](web-payments/overview) | [Payments API](payments-refunds)
{% subheading %}Learn how to set up a web client app with the [Web Payments SDK quickstart](https://github.com/square/web-payments-quickstart) sample project.{% /subheading %}
{% toc hide=true /%}
## Overview
If you don't already have a web client set up that you're working in, the [Web Payments SDK quickstart](https://github.com/square/web-payments-quickstart) includes a template front-end and backend.
### Set up the application
1. Clone the [Web Payments SDK quickstart](https://github.com/square/web-payments-quickstart) GitHub repo.
2. Run `npm install` and then `npm run dev`.
3. Navigate to `http://localhost:3000` to verify that the server is running.
The server displays the following web page:
{% aside type="success" %}
If your web page renders as shown in the previous image, you're ready to write the code that adds the [Card](https://developer.squareup.com/reference/sdks/web/payments/card-payments) payment method to the page.
{% /aside %}
The following files are key to the quickstart:
* The `public/index.html` file lists specific payment method sub-examples. If you continue this quickstart, you replace this list with the default credit card payment acceptance logic.
* The top-level `server.js` file contains the server call to the [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) endpoint for charging the payment source. The quickstart application must include server.js to make the server call; otherwise, the application cannot create a payment.
{% aside type="important" %}
* The value in `server.js` [line 45](https://github.com/square/web-payments-quickstart/blob/main/server.js#L45) sets the currency for the quickstart to US dollars. If your default test account is based in another country, be sure to update `server.js` with the currency code for your country before you run the quickstart.
* If you're using a non-US account, you must change the currency to match the country in which you're accepting the payment.
{% /aside %}
## Next step
* [Add the Web Payments SDK to the Web Client](web-payments/quickstart/add-sdk-to-web-client)
---
# Charge and Store Cards for Online Payments
> Source: https://developer.squareup.com/docs/web-payments/charge-and-store-cards
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to use the Web Payments SDK to charge a card and store card details for future online payments with a card on file.
**Applies to:** [Web Payments SDK](web-payments/overview) | [Payments API](payments-refunds) | [Cards API](cards-api/overview) | [Customers API](customers-api/what-it-does)
{% subheading %} Learn how to use the Web Payments SDK to charge a card and store card details for future online payments with a card on file.{% /subheading %}
## Overview
After configuring your application with the Web Payments SDK to accept card-not-present payments, you can use the Web Payments SDK to store card details with Square as a card on file and charge the card on file for future online payments.
## How the card-on-file workflows work
During payment tokenization, Square checks the tokenize request to determine whether [buyer verification](sca-overview) is needed based on the buyer's information. After receiving the payment token and verifying the buyer, the application performs one of the following card-on-file workflows:
* **Store card details** - The application includes the payment token in a Cards API call to store card details as a card on file with [CreateCard](https://developer.squareup.com/reference/square/cards-api/create-card).
* **Charge a card on file** - The application includes the payment token in a Payments API call to process a payment with [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment).
* **Charge a card and store card details** - The application charges the card and stores the card details as a card on file with a single request call. The application includes the payment token in a Payments API call to process a payment and then creates a card on file and stores the card details as a `Card` object with a new customer profile. When you call `CreateCard`, the `source_id` is the `payment_id` from the Payments API payment response object. This workflow is ideal for scenarios where buyers want to save their card details while making a payment.
To explore example implementations of the card-on-file workflows, see [Web Payments SDK Quickstart](web-payments/quickstart) or set up the [quickstart repository](https://github.com/square/web-payments-quickstart) and choose from the available examples.
The following are additional code examples of each card-on-file workflow setup:
- [Store card details](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-store.html)
- [Charge a card on file](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-charge-card-on-file.html)
- [Charge a card and store its details](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-charge-and-store.html)
## Set up a card-on-file workflow
### Requirements and limitations
Update your application to support the Web Payments SDK card payment flow by following the instructions in [Take a Card Payment](web-payments/take-card-payment) or [Add the Web Payments SDK to the Web Client](web-payments/quickstart/add-sdk-to-web-client).
Choose a workflow when you set up the application. Follow the example code by setting up the [quickstart repository](https://github.com/square/web-payments-quickstart).
The "store card details" workflow involves a `storeCard` method to store card details, while the "charge a card on file" workflow modifies a `CreatePayment` method to take the payment token and the customer ID. If your application needs to charge a card for a payment and store the card details from that same payment, use the "charge a card and store its details" workflow where the application combines both tasks in a single request call.
{% accordion expanded=false %}
{% slot "heading" %}
### Store card details
{% /slot %}
1. Add a helper `storeCard` method, as shown in the following example, that passes the `token` and `customerId` objects as arguments to your server. The server can then make the call to the Square [CreateCard](https://developer.squareup.com/reference/square/cards-api/create-card) endpoint.
```javascript
async function storeCard(token, customerId) {
const body = JSON.stringify({
locationId,
sourceId: token,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const paymentResponse = await fetch('/card', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (paymentResponse.ok) {
return paymentResponse.json();
}
const errorBody = await paymentResponse.text();
throw new Error(errorBody);
}
```
2. Modify the `tokenize` method with the following updates to `verificationDetails`. Set `intent` to `STORE`, `customerInitiated` to `true`, and `sellerKeyedIn` to `false`.
```javascript
async function tokenize(paymentMethod) {
const verificationDetails = {
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
intent: 'STORE',
customerInitiated: true,
sellerKeyedIn: false,
};
const tokenResult = await paymentMethod.tokenize(verificationDetails);
if (tokenResult.status === 'OK') {
return tokenResult.token;
} else {
throw new Error(
`Tokenization errors: ${JSON.stringify(tokenResult.errors)}`,
);
}
}
```
3. Replace the `handlePaymentMethodSubmission` method with a new method called `handleStoreCardSubmission`, pass the `event`, `card`, and `customerId` arguments to the method, and modify the following `try` statement declaration from the code example:
```javascript
async function handleStoreCardSubmission(event, card, customerId) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card);
const storeCardResults = await storeCard(
token,
customerId,
);
displayResults('SUCCESS');
console.debug('Store Card Success', storeCardResults);
} catch (e) {
cardButton.disabled = false;
displayResults('FAILURE');
console.error('Store Card Failure', e);
}
}
```
4. In the `cardButton.addEventListener` event listener, declare a new `customerId` object and call the `handleStoreCardSubmission` method as indicated in the following code example:
```javascript
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const textInput = document.getElementById('customer-input');
if (!textInput.reportValidity()) {
return;
}
const customerId = textInput.value;
handleStoreCardSubmission(event, card, customerId);
});
```
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Charge a card on file
{% /slot %}
1. In your application, initialize a [Card](https://developer.squareup.com/reference/sdks/web/payments/objects/Card) object.
2. Call [Card.tokenize()](https://developer.squareup.com/reference/sdks/web/payments/objects/Card#Card.tokenize) with the `verificationDetails` and `cardId` of the stored card.
The `Card.tokenize()` method passes the following properties in a `verificationDetails` object:
* `amount` - The amount of the card payment to be charged.
* `billingContact` - The buyer's contact information for billing.
* `intent` - The transactional intent of the payment.
* `sellerKeyedIn` - Indicates that the seller keyed in payment details on behalf of the customer. This is used to flag a payment as Mail Order / Telephone Order (MOTO).
* `customerInitiated` - Indicates whether the customer initiated the payment.
* `currencyCode` - The three-letter ISO 4217 currency code.
{% aside type="important" %}
Provide as much buyer information as possible for `billingContact` so that you get more accurate decline rate performance from 3DS authentication.
{% /aside %}
3. Modify the [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) endpoint by renaming the `createPaymentWithCardOnFile` function and passing in the `token` and `customerId`.
The following code example demonstrates the charge card-on-file setup.
```javascript
async function createPaymentWithCardOnFile(
token,
customerId,
) {
const body = JSON.stringify({
locationId,
sourceId: token,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const paymentResponse = await fetch('/payment', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (paymentResponse.ok) {
return paymentResponse.json();
}
const errorBody = await paymentResponse.text();
throw new Error(errorBody);
}
// status is either SUCCESS or FAILURE;
function displayPaymentResults(status) {
const statusContainer = document.getElementById(
'payment-status-container',
);
if (status === 'SUCCESS') {
statusContainer.classList.remove('is-failure');
statusContainer.classList.add('is-success');
} else {
statusContainer.classList.remove('is-success');
statusContainer.classList.add('is-failure');
}
statusContainer.style.visibility = 'visible';
}
async function tokenize(paymentMethod, sourceId) {
const verificationDetails = {
amount: '1.00',
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
currencyCode: 'GBP',
intent: 'CHARGE',
customerInitiated: true,
sellerKeyedIn: false,
};
const tokenResult = await paymentMethod.tokenize(verificationDetails, sourceId);
if (tokenResult.status === 'OK') {
return tokenResult.token;
} else {
let errorMessage = `Tokenization failed with status: ${tokenResult.status}`;
if (tokenResult.errors) {
errorMessage += ` and errors: ${JSON.stringify(
tokenResult.errors,
)}`;
}
throw new Error(errorMessage);
}
}
document.addEventListener('DOMContentLoaded', async function () {
if (!window.Square) {
throw new Error('Square.js failed to load properly');
}
let payments;
try {
payments = window.Square.payments(appId, locationId);
} catch {
const statusContainer = document.getElementById(
'payment-status-container',
);
statusContainer.className = 'missing-credentials';
statusContainer.style.visibility = 'visible';
return;
}
let card;
try {
card = await payments.card();
} catch (e) {
console.error('Initializing Card failed', e);
return;
}
async function handleChargeCardOnFileSubmission(
event,
card,
cardId,
customerId,
) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card, cardId);
const paymentResults = await createPaymentWithCardOnFile(
token,
customerId
);
displayPaymentResults('SUCCESS');
console.debug('Payment Success', paymentResults);
} catch (e) {
cardButton.disabled = false;
displayPaymentResults('FAILURE');
console.error(e.message);
}
}
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const customerTextInput = document.getElementById('customer-input');
const cardTextInput = document.getElementById('card-input');
if (
!customerTextInput.reportValidity() ||
!cardTextInput.reportValidity()
) {
return;
}
const cardId = cardTextInput.value;
const customerId = customerTextInput.value;
handleChargeCardOnFileSubmission(event, card, cardId, customerId);
});
});
```
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Charge a card and store its details
{% /slot %}
1. After the `CreatePayment` method in your application, create a new method called `storeCard`, pass the `paymentId` and `customerId` objects as arguments, and add the requisite properties and the `storeCardResponse` as shown in the following example:
```javascript
async function storeCard(paymentId, customerId) {
const body = JSON.stringify({
locationId,
sourceId: paymentId,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const storeCardResponse = await fetch('/card', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (storeCardResponse.ok) {
return storeCardResponse.json();
}
const errorBody = await storeCardResponse.text();
throw new Error(errorBody);
}
```
2. In the `tokenize` method, update the `verificationDetails` object by setting `intent` to `CHARGE_AND_STORE`.
```javascript
async function tokenize(paymentMethod) {
const verificationDetails = {
amount: '1.00',
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
currencyCode: 'GBP',
intent: 'CHARGE_AND_STORE',
customerInitiated: true,
sellerKeyedIn: false,
};
```
3. In the `document.addEventListener` event listener method, change the `handlePaymentMethodSubmission` method to `handleChargeAndStoreCardSubmission`, pass the `event`, `card`, and `customerId` objects as arguments, and modify the rest of the code as shown in the following example:
```javascript
async function handleChargeAndStoreCardSubmission(event, card, customerId) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card);
const paymentResults = await createPayment(token);
console.debug('Payment Success', paymentResults);
const storeCardResults = await storeCard(
paymentResults.payment.id,
customerId,
);
console.debug('Store Card Success', storeCardResults);
displayPaymentResults('SUCCESS');
} catch (e) {
cardButton.disabled = false;
displayPaymentResults('FAILURE');
console.error(e.message);
}
}
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const textInput = document.getElementById('customer-input');
if (!textInput.reportValidity()) {
return;
}
const customerId = textInput.value;
await handleChargeAndStoreCardSubmission(event, card, customerId);
});
```
{% /accordion %}
## Recommended next step
If your application doesn't yet have a Content Security Policy configured, see [Add a Content Security Policy](web-payments/content-security-policy).
---
# Charge and Store Cards for Online Payments
> Source: https://developer.squareup.com/docs/web-payments/sca-charge-and-store-card-on-file
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to use the Web Payments SDK to charge a card and store card details for future online payments with a card on file.
**Applies to:** [Web Payments SDK](web-payments/overview) | [Payments API](payments-refunds) | [Cards API](cards-api/overview) | [Customers API](customers-api/what-it-does)
{% subheading %} Learn how to use the Web Payments SDK to charge a card and store card details for future online payments with a card on file.{% /subheading %}
## Overview
After configuring your application with the Web Payments SDK to accept card-not-present payments, you can use the Web Payments SDK to store card details with Square as a card on file and charge the card on file for future online payments.
## How the card-on-file workflows work
During payment tokenization, Square checks the tokenize request to determine whether [buyer verification](sca-overview) is needed based on the buyer's information. After receiving the payment token and verifying the buyer, the application performs one of the following card-on-file workflows:
* **Store card details** - The application includes the payment token in a Cards API call to store card details as a card on file with [CreateCard](https://developer.squareup.com/reference/square/cards-api/create-card).
* **Charge a card on file** - The application includes the payment token in a Payments API call to process a payment with [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment).
* **Charge a card and store card details** - The application charges the card and stores the card details as a card on file with a single request call. The application includes the payment token in a Payments API call to process a payment and then creates a card on file and stores the card details as a `Card` object with a new customer profile. When you call `CreateCard`, the `source_id` is the `payment_id` from the Payments API payment response object. This workflow is ideal for scenarios where buyers want to save their card details while making a payment.
To explore example implementations of the card-on-file workflows, see [Web Payments SDK Quickstart](web-payments/quickstart) or set up the [quickstart repository](https://github.com/square/web-payments-quickstart) and choose from the available examples.
The following are additional code examples of each card-on-file workflow setup:
- [Store card details](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-store.html)
- [Charge a card on file](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-charge-card-on-file.html)
- [Charge a card and store its details](https://github.com/square/web-payments-quickstart/blob/273eb48c41ce189683e12d8628c7e81c8509854f/public/examples/card-charge-and-store.html)
## Set up a card-on-file workflow
### Requirements and limitations
Update your application to support the Web Payments SDK card payment flow by following the instructions in [Take a Card Payment](web-payments/take-card-payment) or [Add the Web Payments SDK to the Web Client](web-payments/quickstart/add-sdk-to-web-client).
Choose a workflow when you set up the application. Follow the example code by setting up the [quickstart repository](https://github.com/square/web-payments-quickstart).
The "store card details" workflow involves a `storeCard` method to store card details, while the "charge a card on file" workflow modifies a `CreatePayment` method to take the payment token and the customer ID. If your application needs to charge a card for a payment and store the card details from that same payment, use the "charge a card and store its details" workflow where the application combines both tasks in a single request call.
{% accordion expanded=false %}
{% slot "heading" %}
### Store card details
{% /slot %}
1. Add a helper `storeCard` method, as shown in the following example, that passes the `token` and `customerId` objects as arguments to your server. The server can then make the call to the Square [CreateCard](https://developer.squareup.com/reference/square/cards-api/create-card) endpoint.
```javascript
async function storeCard(token, customerId) {
const body = JSON.stringify({
locationId,
sourceId: token,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const paymentResponse = await fetch('/card', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (paymentResponse.ok) {
return paymentResponse.json();
}
const errorBody = await paymentResponse.text();
throw new Error(errorBody);
}
```
2. Modify the `tokenize` method with the following updates to `verificationDetails`. Set `intent` to `STORE`, `customerInitiated` to `true`, and `sellerKeyedIn` to `false`.
```javascript
async function tokenize(paymentMethod) {
const verificationDetails = {
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
intent: 'STORE',
customerInitiated: true,
sellerKeyedIn: false,
};
const tokenResult = await paymentMethod.tokenize(verificationDetails);
if (tokenResult.status === 'OK') {
return tokenResult.token;
} else {
throw new Error(
`Tokenization errors: ${JSON.stringify(tokenResult.errors)}`,
);
}
}
```
3. Replace the `handlePaymentMethodSubmission` method with a new method called `handleStoreCardSubmission`, pass the `event`, `card`, and `customerId` arguments to the method, and modify the following `try` statement declaration from the code example:
```javascript
async function handleStoreCardSubmission(event, card, customerId) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card);
const storeCardResults = await storeCard(
token,
customerId,
);
displayResults('SUCCESS');
console.debug('Store Card Success', storeCardResults);
} catch (e) {
cardButton.disabled = false;
displayResults('FAILURE');
console.error('Store Card Failure', e);
}
}
```
4. In the `cardButton.addEventListener` event listener, declare a new `customerId` object and call the `handleStoreCardSubmission` method as indicated in the following code example:
```javascript
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const textInput = document.getElementById('customer-input');
if (!textInput.reportValidity()) {
return;
}
const customerId = textInput.value;
handleStoreCardSubmission(event, card, customerId);
});
```
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Charge a card on file
{% /slot %}
1. In your application, initialize a [Card](https://developer.squareup.com/reference/sdks/web/payments/objects/Card) object.
2. Call [Card.tokenize()](https://developer.squareup.com/reference/sdks/web/payments/objects/Card#Card.tokenize) with the `verificationDetails` and `cardId` of the stored card.
The `Card.tokenize()` method passes the following properties in a `verificationDetails` object:
* `amount` - The amount of the card payment to be charged.
* `billingContact` - The buyer's contact information for billing.
* `intent` - The transactional intent of the payment.
* `sellerKeyedIn` - Indicates that the seller keyed in payment details on behalf of the customer. This is used to flag a payment as Mail Order / Telephone Order (MOTO).
* `customerInitiated` - Indicates whether the customer initiated the payment.
* `currencyCode` - The three-letter ISO 4217 currency code.
{% aside type="important" %}
Provide as much buyer information as possible for `billingContact` so that you get more accurate decline rate performance from 3DS authentication.
{% /aside %}
3. Modify the [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) endpoint by renaming the `createPaymentWithCardOnFile` function and passing in the `token` and `customerId`.
The following code example demonstrates the charge card-on-file setup.
```javascript
async function createPaymentWithCardOnFile(
token,
customerId,
) {
const body = JSON.stringify({
locationId,
sourceId: token,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const paymentResponse = await fetch('/payment', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (paymentResponse.ok) {
return paymentResponse.json();
}
const errorBody = await paymentResponse.text();
throw new Error(errorBody);
}
// status is either SUCCESS or FAILURE;
function displayPaymentResults(status) {
const statusContainer = document.getElementById(
'payment-status-container',
);
if (status === 'SUCCESS') {
statusContainer.classList.remove('is-failure');
statusContainer.classList.add('is-success');
} else {
statusContainer.classList.remove('is-success');
statusContainer.classList.add('is-failure');
}
statusContainer.style.visibility = 'visible';
}
async function tokenize(paymentMethod, sourceId) {
const verificationDetails = {
amount: '1.00',
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
currencyCode: 'GBP',
intent: 'CHARGE',
customerInitiated: true,
sellerKeyedIn: false,
};
const tokenResult = await paymentMethod.tokenize(verificationDetails, sourceId);
if (tokenResult.status === 'OK') {
return tokenResult.token;
} else {
let errorMessage = `Tokenization failed with status: ${tokenResult.status}`;
if (tokenResult.errors) {
errorMessage += ` and errors: ${JSON.stringify(
tokenResult.errors,
)}`;
}
throw new Error(errorMessage);
}
}
document.addEventListener('DOMContentLoaded', async function () {
if (!window.Square) {
throw new Error('Square.js failed to load properly');
}
let payments;
try {
payments = window.Square.payments(appId, locationId);
} catch {
const statusContainer = document.getElementById(
'payment-status-container',
);
statusContainer.className = 'missing-credentials';
statusContainer.style.visibility = 'visible';
return;
}
let card;
try {
card = await payments.card();
} catch (e) {
console.error('Initializing Card failed', e);
return;
}
async function handleChargeCardOnFileSubmission(
event,
card,
cardId,
customerId,
) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card, cardId);
const paymentResults = await createPaymentWithCardOnFile(
token,
customerId
);
displayPaymentResults('SUCCESS');
console.debug('Payment Success', paymentResults);
} catch (e) {
cardButton.disabled = false;
displayPaymentResults('FAILURE');
console.error(e.message);
}
}
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const customerTextInput = document.getElementById('customer-input');
const cardTextInput = document.getElementById('card-input');
if (
!customerTextInput.reportValidity() ||
!cardTextInput.reportValidity()
) {
return;
}
const cardId = cardTextInput.value;
const customerId = customerTextInput.value;
handleChargeCardOnFileSubmission(event, card, cardId, customerId);
});
});
```
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
### Charge a card and store its details
{% /slot %}
1. After the `CreatePayment` method in your application, create a new method called `storeCard`, pass the `paymentId` and `customerId` objects as arguments, and add the requisite properties and the `storeCardResponse` as shown in the following example:
```javascript
async function storeCard(paymentId, customerId) {
const body = JSON.stringify({
locationId,
sourceId: paymentId,
customerId,
idempotencyKey: window.crypto.randomUUID(),
});
const storeCardResponse = await fetch('/card', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body,
});
if (storeCardResponse.ok) {
return storeCardResponse.json();
}
const errorBody = await storeCardResponse.text();
throw new Error(errorBody);
}
```
2. In the `tokenize` method, update the `verificationDetails` object by setting `intent` to `CHARGE_AND_STORE`.
```javascript
async function tokenize(paymentMethod) {
const verificationDetails = {
amount: '1.00',
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
currencyCode: 'GBP',
intent: 'CHARGE_AND_STORE',
customerInitiated: true,
sellerKeyedIn: false,
};
```
3. In the `document.addEventListener` event listener method, change the `handlePaymentMethodSubmission` method to `handleChargeAndStoreCardSubmission`, pass the `event`, `card`, and `customerId` objects as arguments, and modify the rest of the code as shown in the following example:
```javascript
async function handleChargeAndStoreCardSubmission(event, card, customerId) {
event.preventDefault();
try {
// disable the submit button as we await tokenization and make a payment request.
cardButton.disabled = true;
const token = await tokenize(card);
const paymentResults = await createPayment(token);
console.debug('Payment Success', paymentResults);
const storeCardResults = await storeCard(
paymentResults.payment.id,
customerId,
);
console.debug('Store Card Success', storeCardResults);
displayPaymentResults('SUCCESS');
} catch (e) {
cardButton.disabled = false;
displayPaymentResults('FAILURE');
console.error(e.message);
}
}
const cardButton = document.getElementById('card-button');
cardButton.addEventListener('click', async function (event) {
const textInput = document.getElementById('customer-input');
if (!textInput.reportValidity()) {
return;
}
const customerId = textInput.value;
await handleChargeAndStoreCardSubmission(event, card, customerId);
});
```
{% /accordion %}
## Recommended next step
If your application doesn't yet have a Content Security Policy configured, see [Add a Content Security Policy](web-payments/content-security-policy).
---
# Manage Card-on-File Declines
> Source: https://developer.squareup.com/docs/cards-api/manage-card-on-file-declines
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn about Square features and guidance that can help reduce and manage card-on-file declines.
**Applies to:** [Cards API](cards-api/overview) | [Webhooks](webhooks/overview)
{% subheading %}Use Square features and guidance to help manage or reduce declines for [card-on-file payments](cards-api/overview#card-on-file-payments) and increase customer retention.{% /subheading %}
{% toc hide=true /%}
{% anchor id="card-automatically-updated-event-notifications" /%}
## card.automatically_updated event notifications
To proactively manage potential declines due to expired card data or closed accounts, subscribe to receive [card.automatically_updated](https://developer.squareup.com/reference/square/cards-api/webhooks/card.automatically_updated) event notifications when Square automatically updates cards on file. You can subscribe [manually](webhooks/step2subscribe) in the Developer Console or [programmatically](webhooks/webhook-subscriptions-api) using the Webhook Subscriptions API.
When you receive a `card.automatically_updated` notification, inspect the `card` object in the notification payload and take appropriate action:
* **Expiration updates** - When allowed by the issuing bank, Square automatically updates the expiration date and last 4 digits of expiring cards on file. By listening for these updates, you can help ensure that card information remains current if the expiration date or card number changes.
To use this feature:
1. In the notification payload, check the `exp_month`, `exp_year`, and `last_4` fields.
2. If you store this card information, update your records.
{% line-break /%}
* **Issuer alerts about closed accounts (Beta, select Mastercard cards only)** - For some Mastercard cards on file, the issuing bank alerts Square when the underlying account is closed. Square then marks the card as `ISSUER_ALERT_CARD_CLOSED`.
Issuer alerts aren't guaranteed to be accurate, but they're a strong signal that future charges to the card are likely to fail. In testing, 80% of cards with issuer alerts were declined at the time of payment. By proactively contacting customers to set up a new payment method on file, you can reduce the likelihood that recurring subscriptions become delinquent.
{% aside type="info" %}
To access issuer alerts, Square API version 2024-12-18 or later is required for your webhook subscription or when calling the Cards API.
{% /aside %}
To use this feature:
1. In the notification payload, check whether the `issuer_alert` field is present. If present and set to `ISSUER_ALERT_CARD_CLOSED`, check the `issuer_alert_at` field to determine whether this is a new alert.
2. If the account is newly marked as closed, request a new payment method from the customer.
{% accordion expanded=false %}
{% slot "heading" %}
#### More details
{% /slot %}
If notified by the issuing bank that the underlying account for the card on file is closed, Square sets the `issuer_alert` field to `ISSUER_ALERT_CARD_CLOSED`, updates the `issuer_alert_at` timestamp, and invokes a `card.automatically_updated` event.
The `issuer_alert` and `issuer_alert_at` fields are present only when the card has an active issuer alert. If notified by the issuing bank that the account is reopened, Square clears both fields and invokes a `card.automatically_updated` event.
The following example payload contains the `issuer_alert` and `issuer_alert_at` fields, which indicates that there's an active issuer alert:
```json
{
"merchant_id": "6SSW7HV8K2ST5",
"type": "card.automatically_updated",
"event_id": "d214f854-adb1-4f56-b078-4b8697a3187a",
"created_at": "2025-02-15T04:38:13Z",
"data": {
"type": "card",
"id": "ccof:uIbfJXhXETSP197M3GB",
"object": {
"card": {
"id": "ccof:uIbfJXhXETSP197M3GB",
"billing_address": {
"address_line_1": "500 Electric Ave",
"address_line_2": "Suite 600",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10003",
"country": "US"
},
"fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q",
"bin": "411111",
"card_brand": "VISA",
"card_type": "CREDIT",
"cardholder_name": "Amelia Earhart",
"customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
"enabled": true,
"exp_month": 11,
"exp_year": 2027,
"last_4": "1111",
"issuer_alert": "ISSUER_ALERT_CARD_CLOSED",
"issuer_alert_at": "2025-02-16T04:38:13Z",
"merchant_id": "6SSW7HV8K2ST5",
"prepaid_type": "NOT_PREPAID",
"reference_id": "user-id-2",
"version": 2
}
}
}
}
```
{% /accordion %}
Square also supports `card.created`, `card.updated`, `card.disabled`, and `card.forgotten` [webhook events](webhooks/v2webhook-events-tech-ref#cards-api) for the Cards API.
{% aside type="tip" %}
The [Events API](events-api/overview) can be used with webhook subscriptions for recovery and reconciliation of missed webhook events.
{% /aside %}
## SCA verification
[Strong Customer Authentication](sca-overview) (SCA) provides an additional layer of fraud protection in regions where SCA is required or for sellers that subscribe to Square Risk Manager to enforce 3-D Secure (3DS). SCA applies both when saving cards on file and making card-on-file payments.
To help reduce the likelihood of declines for card-on-file payments, provide as much buyer information as possible to the Web Payments SDK or In-App Payments SDK. For more information, see [Charge and Store Cards for Online Payments](web-payments/charge-and-store-cards) for Web Payments SDK integrations or [Verify a Buyer](in-app-payments-sdk/verify-buyer) for In-App Payments SDK integrations.
{% anchor id="health-account-cards-beta" /%}
{% anchor id="health-account-cards" /%}
## Health account cards (Beta)
Square uses the Bank Identification Number (BIN) to determine whether a card on file is for a Health Savings Account (HSA) or a Flexible Spending Account (FSA), which can be used for authorized medical expenses. For these cards, Square sets the `Card.hsa_fsa` field to `true`.
You can use the `hsa_fsa` field to identify HSA and FSA cards, which tend to have higher decline rates as the year progresses because they might run out of funds. Sellers accepting card-on-file payments should ask customers to provide a secondary payment method on file when saving an HSA or FSA card on file.
{% aside type="info" %}
Square API version 2024-12-18 or later is required to access the `hsa_fsa` field.
{% /aside %}
## Prepaid cards
A prepaid card is a type of payment card that can hold a certain amount of value. For these cards, Square sets the `Card.prepaid_type` field to `PREPAID`.
You can use the `prepaid_type` field to identify prepaid cards, which tend to have higher decline rates because they run out of funds. Sellers accepting card-on-file payments should ask customers to also provide a secondary payment method on file when saving a prepaid card on file.
## Additional best practices
### Logging and audits
Keep detailed logs of transaction attempts and declined payments to identify and address recurring issues. Conduct regular audits of transaction flows to ensure compliance with regulations and identify any potential issues.
### Retry strategy
Consider the following factors when designing your retry strategy:
- Check the decline reason to determine the appropriate action:
- `INSUFFICIENT_FUNDS` - Retrying after a few days might be effective.
- `GENERIC_DECLINE` error - Don't retry. Instead, inform the buyer that the specific reason for the decline isn't available and advise them to contact their issuer for further details and assistance. Sometimes the specific reason for a card decline is unavailable because of limitations in the information provided by the issuing bank.
- Wait at least 24 hours before retrying. Immediate retries can trigger fraud alerts or cause additional declines.
- Limit retries to 2 to 3 attempts over several days to avoid triggering fraud alerts. Excessive retries can be flagged as suspicious activity.
### Customer communication
When possible, inform buyers when a decline occurs and suggest they contact their issuing bank for further details and assistance, especially when the exact reason for the decline isn't available.
If a charge continues to fail, request a new payment method from the customer.
### Test decline scenarios
Test in production and Sandbox environments to ensure your application gracefully handles card-on-file declines. Square provides [card-on-file IDs](devtools/sandbox/payments#card-on-file-id-values) you can use for testing some common card-on-file decline scenarios in the {% tooltip text="Square Sandbox" %}An isolated server environment used for testing. API calls in the Sandbox use the "connect.squareupsandbox.com" domain and require an access token that's valid for Sandbox.{% /tooltip %}.
## See also
* [Cards API](cards-api)
* [Manage Customer Cards on File](cards-api/manage-cards)
* [Create a Card on File from a Payment ID](cards-api/walkthrough/card-from-payment-id)
* [Create a Card on File and a Payment](cards-api/walkthrough-seller-card)
* [Create a Shared Card on File and Make a Payment](cards-api/walkthrough-shared-card)
---
# .NET SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/dotnet/migration
> Status: PUBLIC
> Languages: All
> Platforms: All
Upgrade from the legacy version of the Square .NET SDK to version 42.0.0 or later.
Version `41.0.0` of the .NET SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `40.1.0` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
To create a new client, you construct it using `new` and passing in parameters, as opposed to the legacy client that uses a Java-esque builder pattern.
```csharp
using Square;
// new
var client = new SquareClient(
token, // optional if you configure SQUARE_TOKEN environment variable
new ClientOptions
{
BaseUrl = SquareEnvironment.Production // default, so you can omit ClientOptions parameter
}
);
// legacy
var legacyClient = new Square.Legacy.SquareClient.Builder()
.BearerAuthCredentials(new BearerAuthModel.Builder(token).Build())
.Environment(Square.Legacy.Environment.Production)
.Build();
```
{% table %}
* Legacy
* New {% width="200px" %}
* Additional information
---
* `AccessToken`
* `Token`
* The access token used for authentication.
---
* `BearerAuthCredentials`
* Removed
* Set using the `Token` or `SQUARE_TOKEN` environment variable.
---
* `CustomUrl`
* `ClientOptions.BaseUrl`
* Sets the base URL for API requests and defaults to `https://connect.squareup.com`.
---
* `SquareVersion`
* `ClientOptions.Version`
* The Square API version to use.
---
* `AdditionalHeaders`
* `ClientOptions.AdditionalHeaders`
* Available through `ClientOptions.AdditionalHeaders`.
---
* `UserAgentDetail`
* Removed
* Set the user agent header on `ClientOptions.DefaultHeaders`.
---
* `Timeout`
* `Timeout`
* Accepts a `TimeSpan` and the default is 30 seconds.
---
* `HttpCallback`
* Removed
* Configure the HTTP client and options on the `ClientOptions`.
---
* `HttpClientConfig`
* Removed
* Configure the HTTP client and options on the `ClientOptions`.
{% /table %}
## Use the legacy and new SDK side by side
While the new SDK has many improvements, it takes time to upgrade when there are breaking changes. To make the migration easier, the old SDK is available in the `Square.Legacy` NuGet package. The following example shows how to use the new and legacy SDKs inside a single file:
```csharp
using Square;
using Square.Legacy.Authentication;
using Square.Locations;
public class Program
{
public static async Task Main(string[] args)
{
var token = Environment.GetEnvironmentVariable("SQUARE_TOKEN") ??
throw new Exception("Missing SQUARE_TOKEN environment variable");
// LEGACY
var legacyClient = new Square.Legacy.SquareClient.Builder()
.BearerAuthCredentials(new BearerAuthModel.Builder(token).Build())
.Environment(Square.Legacy.Environment.Sandbox)
.Build();
// NEW
var client = new SquareClient(
token,
new ClientOptions
{
BaseUrl = SquareEnvironment.Sandbox
}
);
// use new client
var location = await GetLocationAsync(client);
// use legacy client
await CreateOrderAsync(legacyClient, location);
}
private static async Task GetLocationAsync(SquareClient client)
{
var response = await client.Locations.GetAsync(
new GetLocationsRequest
{
LocationId = "YOUR_LOCATION_ID"
}
);
return response.Location ?? throw new Exception("response.Location is null");
}
private static async Task CreateOrderAsync(
Square.Legacy.SquareClient legacyClient,
Location location
)
{
await legacyClient
.OrdersApi
.CreateOrderAsync(new Square.Legacy.Models.CreateOrderRequest.Builder()
.IdempotencyKey(Guid.NewGuid().ToString())
.Order(new Square.Legacy.Models.Order.Builder(location.Id).Build())
.Build());
}
}
```
You should migrate to the new SDK using the following steps:
1. Install the `Square.Legacy` NuGet package alongside the existing Square SDK.
2. Search and replace all `using` statements from `Square` to `Square.Legacy`.
3. Gradually introduce the new SDK by importing it from the `Square` namespace.
## Request construction
The legacy SDK allows you to instantiate a request either using a constructor and positional parameters or using a builder pattern. With the new SDK, you simply create a new instance of the request and use the property initializer to set the properties.
```csharp
// Legacy with builder pattern
var request = new Square.Legacy.Models.CreatePaymentRequest.Builder("SOURCE_ID", "IDEMPOTENCY_KEY")
.AmountMoney(new Square.Legacy.Models.Money.Builder().Amount(20L).Currency("USD").Build())
.TipMoney(new Square.Legacy.Models.Money.Builder().Amount(3L).Currency("USD").Build())
.Build();
// Legacy with positional constructor parameters
request = new Square.Legacy.Models.CreatePaymentRequest(
"SOURCE_ID",
Guid.NewGuid().ToString(),
new Square.Legacy.Models.Money(20L, "USD"),
new Square.Legacy.Models.Money(3L, "USD")
);
// New with property initializers
var request = new CreatePaymentRequest
{
SourceId = "SOURCE_ID",
IdempotencyKey = Guid.NewGuid().ToString(),
AmountMoney = new Money
{
Amount = 20L,
Currency = Currency.Usd
},
TipMoney = new Money
{
Amount = 3L,
Currency = Currency.Usd
}
};
```
## API classes and method name changes
Previously, API classes were named after the resource you're interacting with and suffixed with `Api`. To interact with customer resources, you use the `client.CustomersApi` property. Methods were named based on the action you want to perform and the same resource name specified earlier. To list customers, you call `client.CustomersApi.ListCustomersAsync()`.
```csharp
// Legacy
client.CustomersApi.ListCustomersAsync()
```
The new API classes are named by the resource without the `Api` suffix, and the methods now name the action without mentioning the resource a second time.
```csharp
// New
client.Customers.ListAsync()
```
When interacting with a nested resource, you can chain the resources using dot-notation.
```java
// New
client.Customers.Groups.ListAsync();
```
Some other class and method names might have changed. The differences are easiest to discover by exploring the new method signatures.
## Auto-pagination
Square's paginated endpoints now support auto-pagination with an iterator. Callers don’t need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.
The following example shows the same code, with the legacy and new SDKs:
```csharp
// Legacy
using Square.Legacy;
using Square.Legacy.Authentication;
var legacyClient = new SquareClient.Builder()
.BearerAuthCredentials(new BearerAuthModel.Builder("YOUR_TOKEN").Build())
.Build();
string? cursor = null;
do
{
var response = await legacyClient.PaymentsApi.ListPaymentsAsync(total: 100, cursor: cursor);
if (response.Payments is null) break;
var payments = response.Payments;
foreach (var payment in payments)
{
Console.WriteLine(
"payment: ID: {0}, Created at: {1}, Updated at: {2}",
payment.Id,
payment.CreatedAt,
payment.UpdatedAt
);
}
cursor = response.Cursor;
} while (!string.IsNullOrEmpty(cursor));
// New
using Square;
using Square.Payments;
var client = new SquareClient("YOUR_TOKEN");
var payments = await client.Payments.ListAsync(new ListPaymentsRequest{ Limit = 100 });
await foreach (var payment in payments)
{
Console.WriteLine(
"payment: ID: {0}, Created at: {1}, Updated at: {2}",
payment.Id,
payment.CreatedAt,
payment.UpdatedAt
);
}
```
If you need to paginate page by page, you can still do so.
```csharp
await foreach (var page in payments.AsPagesAsync())
{
foreach (var payment in page.Items)
{
Console.WriteLine(
"payment: ID: {0}, Created at: {1}, Updated at: {2}",
payment.Id,
payment.CreatedAt,
payment.UpdatedAt
);
}
}
```
## Synchronous calls
In the legacy SDK, you can make synchronous calls. Following modern .NET standards, synchronous API calls are no longer supported.
## Explicit null values
In the legacy SDK, explicit null values can be sent using `null` values. The new SDK uses `RequestOptions.AdditionalBodyProperties`.
```csharp
// Legacy
await legacyClient.LocationsApi.UpdateLocationAsync(
locationId,
new Square.Legacy.Models.UpdateLocationRequest.Builder()
.Location(new Square.Legacy.Models.Location.Builder()
.WebsiteUrl("https://developer.squareup.com")
.TwitterUsername(null)
.Build()
).Build()
);
// New
await client.Locations.UpdateAsync(
new UpdateLocationRequest
{
LocationId = locationId,
Location = new Location
{
WebsiteUrl = "https://developer.squareup.com"
}
},
new RequestOptions
{
AdditionalBodyProperties = new
{
location = new Dictionary
{
["twitter_username"] = null
}
}
}
);
```
{% aside type="info" %}
You can pass anything into `AdditionalBodyProperties` that translates to a JSON object, but you need to use a dictionary to ensure `null` values aren't omitted.
{% /aside %}
---
# Java SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/java/migration
> Status: PUBLIC
> Languages: All
> Platforms: All
Upgrade from the legacy version of the Square Java SDK to version 42.0.0 or later.
Version `44.0.0.20250319` of the Java SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `43.1.0.20250220` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
The new `Client` class has some breaking changes and is constructed in a slightly different way than the legacy version of the SDK.
{% table %}
* Legacy
* New {% width="100px" %}
* Additional information
---
* `accessToken`
* `token`
* The access token used for authentication.
---
* `bearerAuthCredentials`
* Removed
* Set using the `token` or `SQUARE_TOKEN` environment variable.
---
* `customUrl`
* `url`
* Sets the base URL for API requests and defaults to `https://connect.squareup.com`.
---
* `squareVersion`
* `version`
* The Square API version to use.
---
* `additionalHeaders`
* Removed
* Available through `ClientOptions` and `RequestOptions` objects.
---
* `userAgentDetail`
* Removed
* Configurable by setting the OkHttp client directly.
---
* `timeout`
* `timeout`
* Now takes an `int` rather than a `long`.
---
* `httpCallback`
* Removed
* Configurable by setting the OkHttp client directly.
---
* `httpClientConfig`
* Removed
* Configurable by setting the OkHttp client directly.
---
* `new Builder`
* `builder`
* See the following example.
{% /table %}
```java
// LEGACY
import com.squareup.square.legacy.Environment;
import com.squareup.square.legacy.SquareClient;
SquareClient client = new SquareClient.Builder()
.environment() // defaults to Environment.PRODUCTION
.accessToken("YOUR_TOKEN") // defaults to using "SQUARE_ACCESS_TOKEN" environment variable
.build();
// NEW
import com.squareup.square.Environment;
import com.squareup.square.SquareClient;
SquareClient client = SquareClient.builder()
.environment() // defaults to Environment.PRODUCTION
.token("YOUR_TOKEN"); // defaults to using "SQUARE_TOKEN" environment variable
.build();
```
## Use the legacy and new SDK side by side
While the new SDK has many improvements, it takes time to upgrade when there are breaking changes. To make the migration easier, the new SDK exports the legacy SDK as `com.squareup.square.legacy`. The following example shows how to use the new and legacy SDKs inside a single file:
```java
package com.square.examples;
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;
import com.squareup.square.legacy.exceptions.ApiException;
import com.squareup.square.legacy.models.CreateOrderRequest;
import com.squareup.square.legacy.models.CreateOrderResponse;
import com.squareup.square.legacy.models.Order;
import com.squareup.square.types.GetLocationResponse;
import com.squareup.square.types.GetLocationsRequest;
import com.squareup.square.types.Location;
import java.io.IOException;
import java.util.Optional;
import java.util.UUID;
public class SideBySide {
public static void main(String[] args) {
com.squareup.square.legacy.SquareClient legacyClient = new com.squareup.square.legacy.SquareClient.Builder()
.accessToken(System.getenv("SQUARE_TOKEN"))
.environment(com.squareup.square.legacy.Environment.SANDBOX)
.build();
SquareClient client = SquareClient.builder()
.token(System.getenv("SQUARE_TOKEN"))
.environment(Environment.SANDBOX)
.build();
Location location = getLocation(client).get();
CreateOrderResponse result = createOrder(legacyClient, location);
}
private static Optional getLocation(SquareClient client) {
GetLocationResponse response = client.locations()
.get(GetLocationsRequest.builder()
.locationId("YOUR_LOCATION_ID")
.build());
return response.getLocation();
}
private static CreateOrderResponse createOrder(
com.squareup.square.legacy.SquareClient legacyClient, Location location) {
try {
return legacyClient
.getOrdersApi()
.createOrder(new CreateOrderRequest.Builder()
.idempotencyKey(UUID.randomUUID().toString())
.order(new Order.Builder(location.getId().get()).build())
.build());
} catch (ApiException | IOException e) {
throw new RuntimeException(e);
}
}
}
```
You should migrate to the new SDK using the following steps:
1. Include the following dependencies in your project:
{% tabset %}
{% tab id="Maven" %}
```xml
com.squareup
square
47.0.1.20260715
com.squareup
square-legacy
47.0.1.20260715
```
{% /tab %}
{% tab id="Gradle" %}
```groovy
dependencies {
implementation 'com.squareup:square:47.0.1.20260715'
implementation 'com.squareup:square-legacy:47.0.1.20260715'
}
```
{% /tab %}
{% /tabset %}
2. Search and replace all imports from `com.squareup.square` to `com.squareup.square.legacy`.
3. Gradually introduce the new SDK by importing it from the `com.squareup.square` import.
## Request builder constructors
There are two main differences between the request builders in the legacy SDK and the new SDK:
* **Instantiation** - The legacy SDK builders are instantiated through their internal class constructors, whereas the new SDK builders are instantiated through static `builder()` methods.
* **Required fields** - In the legacy SDK, required fields are passed in as parameters to the builder constructor, while the new SDK has staged builders that won't expose the `.build()` method until all required fields are set.
```java
// LEGACY
CreatePaymentRequest request = new CreatePaymentRequest.Builder("SOURCE_ID", "IDEMPOTENCY_KEY")
.amountMoney(new Money.Builder().amount(20L).currency("USD").build())
.tipMoney(new Money.Builder().amount(3L).currency("USD").build())
.build();
// NEW
CreatePaymentRequest request = CreatePaymentRequest.builder()
.sourceId("SOURCE_ID")
.idempotencyKey(UUID.randomUUID().toString())
.amountMoney(Money.builder().amount(20L).currency(Currency.USD).build())
.tipMoney(Money.builder().amount(3L).currency(Currency.USD).build())
.build();
```
## API classes and method name changes
Previously, API classes were named after the resource you're interacting with and suffixed with `Api`. To interact with customer resources, you use the `client.getCustomersApi()` method. The method was named based on the action you want to perform and the same resource name specified earlier. To list customers, you call `client.getCustomersApi().listCustomers();`.
```java
// LEGACY
client.getCustomersApi().listCustomers();
```
The new API classes are named by the resource without the `Api` suffix, and the methods now name the action without mentioning the resource a second time.
```java
// NEW
client.customers().list();
```
When interacting with a nested resource, you can chain the resources using dot-notation.
```java
// NEW
client.customers().groups().list();
```
Some other class and method names might have changed. The differences are easiest to discover by exploring the new method signatures.
## Auto-pagination
Square's paginated endpoints now support auto-pagination with an iterator. Callers don’t need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.
The following example shows the same code, with the legacy and new SDKs:
```java
// LEGACY
import com.squareup.square.legacy.SquareClient;
import com.squareup.square.legacy.models.ListPaymentsResponse;
import com.squareup.square.legacy.models.Payment;
import java.util.List;
SquareClient legacyClient = new SquareClient.Builder()
.accessToken("YOUR_TOKEN")
.build();
ListPaymentsResponse response = legacyClient.getPaymentsApi().listPayments(...);
List payments = response.getPayments();
String cursor = response.getCursor();
for (Payment payment : payments) {
System.out.printf("payment: ID: %s Created at: %s, Updated at: %s\n",
payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());
}
while (!response.getCursor().isEmpty()) {
response = legacyClient.getPaymentsApi().listPayments(..., cursor, ...);
payments = response.getPayments();
cursor = response.getCursor();
for (Payment payment : payments) {
System.out.printf("payment: ID: %s Created at: %s, Updated at: %s\n",
payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());
}
}
// NEW
import com.squareup.square.SquareClient;
import com.squareup.square.core.SyncPagingIterable;
import com.squareup.square.types.Payment;
import com.squareup.square.types.PaymentsListRequest;
SquareClient square = SquareClient.builder().token("YOUR_TOKEN").build();
SyncPagingIterable payments =
square.payments().list(PaymentsListRequest.builder().total(100L).build());
for (Payment payment : payments) {
System.out.printf(
"payment: ID: %s Created at: %s, Updated at: %s\n",
payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());
}
```
If you need to paginate page by page, you can still do so.
```java
// First page
List pagePayments = payments.getItems();
for (Payment payment : pagePayments) {
// ...
}
// Remaining pages
while (payments.hasNext()) {
pagePayments = payments.nextPage().getItems();
for (Payment payment : pagePayments) {
// ...
}
}
```
## Async calls
In the legacy SDK, asynchronous calls can be made on the same client as synchronous calls by appending `Async` to the method name. In the new SDK, async calls must be made to a class with the same name as the synchronous client with `Async` prepended:
```java
// LEGACY
SquareClient legacyClient = new SquareClient.Builder().accessToken("YOUR_TOKEN").build();
ListLocationsResponse syncResponse = legacyClient.getLocationsApi().listLocations();
CompletableFuture asyncResponse = legacyClient.getLocationsApi().listLocationsAsync();
// NEW
SquareClient client = SquareClient.builder().token("YOUR_TOKEN").build();
AsyncSquareClient asyncClient = AsyncSquareClient.builder().token("YOUR_TOKEN").build();
ListLocationsResponse syncResponse = client.locations().list();
CompletableFuture asyncResponse = asyncClient.locations().list();
```
## Explicit null values
In the legacy SDK, explicit null values can be sent using null values in the builder methods. In the new SDK, they can be set using `Nullable.ofNull()`.
```java
// LEGACY
new Transaction.Builder().clientId(null).build();
// NEW
Transaction.builder().clientId(Nullable.ofNull()).build();
Transaction.builder().clientId(Nullable.of(null)).build(); // also valid
```
---
# Take Payments for Orders
> Source: https://developer.squareup.com/docs/terminal-api/take-payments-for-orders
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to take payments for orders with the Terminal API and Square Terminal.
**Applies to:** [Terminal API](terminal-api/overview) | [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to use the Terminal API to process payments for orders created through the Orders API. {% /subheading %}
## Overview
The Terminal API supports the lifecycle of an order by integrating the Square Terminal and the [Orders API](https://developer.squareup.com/reference/square/orders-api). The Orders API enables the purchase of line items, calculates totals, confirms payments, tracks an order's progress through fulfillment, itemizes purchases, and generates receipts all within a [CreateTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/create-terminal-checkout) request. With support for orders interoperability, you can build complex payment workflows using the Terminal API with an order.
The Terminal API's integration with orders and itemization lets you build workflows that process complex payments on the Square Terminal, such as splitting payments for a restaurant order that itemizes several menu line items. With this integration, you can use Square products like Square Order Manager to manage orders that have been paid and processed by the Square Terminal.
### Requirements
* Square Terminal version 6.62 or later.
* Support for orders and itemization with the Square Terminal. For more information about regional support, see [Take Payments on Hardware](in-person-payment-options#checkout-flow-and-key-capabilities).
### Limitations
* The Terminal API doesn't support updates made to orders after the Terminal checkout with the `order_id` moves to the `IN_PROGRESS` state, which indicates that the Square Terminal is currently processing the checkout.
* Any updates made to the order while the Terminal checkout is in the `IN_PROGRESS` state might lead to errors on the Square Terminal during checkout, and problems with resolving the order.
* To correctly update an order after a Terminal checkout has already been created, send a cancel request using [CancelTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/cancel-terminal-checkout).
* If you successfully canceled the Terminal checkout and the order is still `OPEN`, update the order and create a new Terminal checkout with the same order. You can also create a new order and use its `order_id` to create a new Terminal checkout.
* Order must be `OPEN`.
* Square deletes completed checkouts after 30 days. If you need to store the Terminal checkouts for future reference, retain the checkout's payment IDs.
## About orders and the Terminal API
An `Order` object is a top-level container representing an order. The order can have line items attached to it to indicate that the order consists of the items attached. A Terminal checkout can link to an open order and allow a buyer to complete a payment on that order. The Square Terminal displays the itemized list of purchased items during checkout and on the printed and digital receipts.
## Process payments for orders
The following procedure shows how to use the Terminal API to process payments with an order.
### 1. Create an order
Using the Terminal API with orders and itemization support, create an `Order` object using the Orders API [CreateOrder](https://developer.squareup.com/reference/square/orders-api/create-order) endpoint, representing an order for a total amount of $5.00 USD, with two $1.00 items and a single $3.00 item.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
Note that when created, the order is in an `OPEN` state. The `OPEN` state allows you to update the order.
```json
{
"order": {
"id": "Cc2NJAhkrOd3aaHm2NQK9RM0kADZY",
"location_id": "W3Q7PHA6CMDH8",
"line_items": [
{
"uid": "kLgfgH63Jip5nIuyIB1Ir",
"quantity": "2",
"name": "One Dollar Item",
"base_price_money": {
"amount": 100,
"currency": "USD"
},
"gross_sales_money": {
"amount": 200,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 200,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 200,
"currency": "USD"
},
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
{
"uid": "tzVkst1R2mBXlxU4Qx5mc",
"quantity": "1",
"name": "Three Dollar Item",
"base_price_money": {
"amount": 300,
"currency": "USD"
},
"gross_sales_money": {
"amount": 300,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 300,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 300,
"currency": "USD"
},
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
}
],
"created_at": "2025-03-10T23:34:19.971Z",
"updated_at": "2025-03-10T23:34:19.971Z",
"state": "OPEN",
"version": 1,
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_tip_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 500,
"currency": "USD"
},
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 500,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
"source": {
"name": "Terminal API"
},
"net_amount_due_money": {
"amount": 500,
"currency": "USD"
}
}
}
```
The order is created after the checkout request passes the following validation rules:
* The order must belong to the location to which the Square Terminal is currently logged in.
* The order must be in an `OPEN` state.
* The order and checkout currency must match.
* The order and checkout amount must be equal to each other if `payment_options.autocomplete` is set to `true`. This moves the order to a `COMPLETED` state.
After the checkout request is sent to the Square Terminal, the buyer can complete or cancel the checkout.
{% /tab %}
{% /tabset %}
### 2. Link an order to a Terminal checkout
- Pass the order's `order_id` to a new Terminal checkout request to collect any payments associated with the order.
- Set the `show_itemized_cart` value to `true` in the Terminal checkout's [DeviceCheckoutOptions](https://developer.squareup.com/reference/square/objects/DeviceCheckoutOptions#definition__property-show_itemized_cart) property. This property shows the itemization screen on the Square Terminal prior to taking a payment. This field is active only if the Terminal checkout includes the `order_id`.
- Pass the rest of the details in the `checkout` property fields of the request.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"checkout": {
"id": "WJ5393OCcdkqO",
"amount_money": {
"amount": 500,
"currency": "USD"
},
"device_options": {
"device_id": "147CS149A7003873",
"collect_signature": false,
"tip_settings": {
"allow_tipping": false
},
"skip_receipt_screen": false,
"show_itemized_cart": true
},
"status": "PENDING",
"created_at": "2025-03-11T18:02:32.005Z",
"updated_at": "2025-03-11T18:02:32.005Z",
"app_id": "sq0idp-dcqnATUXGLZMGmES5uuG0Q",
"order_id": "Cc2NJAhkrOd3aaHm2NQK9RM0kADZY",
"location_id": "W3Q7PHA6CMDH8",
"payment_type": "CARD_PRESENT",
"payment_options": {
"autocomplete": true
}
}
}
```
{% /tab %}
{% /tabset %}
The `CreateOrder` response returns an `order_id` value, which you can pass into the `order_id` field in the `CreateTerminalCheckout` request. If the Terminal checkout request is successful, the `amount_money` value from the Terminal checkout is applied to the order.
The following image demonstrates how the Square Terminal shows a checkout order for coffee and a croissant, with discounts and service charges applied prior to the buyer confirming and paying for the order.
{% accordion expanded=false %}
{% slot "heading" %}
### (Optional) Take a split tender payment
{% /slot %}
By default, Terminal checkouts are designed to pay the full order total. In this case:
* The Terminal checkout sets `autocomplete` to `true`.
* The Terminal checkout amount must equal the order total.
* The order automatically transitions to a `COMPLETED` state when the checkout completes.
If `autocomplete` is set to `false` in the Terminal checkout, you can submit partial payments against the order, such as for splitting a restaurant bill between two cards. In this partial payment flow, the order does not move to a `COMPLETED` state automatically. To process all partial payments, you need to call [PayOrder](https://developer.squareup.com/reference/square/orders-api/pay-order) and include all payment IDs. For more information, see [Pay for Orders](orders-api/pay-for-orders).
1. Create an order with the Orders API.
2. Create one or more Terminal checkouts for part of the order total. Assign the `order_id` and verify `autocomplete=false` when calling Terminal API.
3. Collect the [`payment_id`](https://developer.squareup.com/reference/square/objects/TerminalCheckout#definition__property-payment_ids) from each Terminal checkout and any other payments created such as for cash payments.
4. Call the [PayOrder](https://developer.squareup.com/reference/square/orders/pay-order) endpoint with all of the payment IDs.
After calling `PayOrder`, the order's status changes to `COMPLETED`. The associated partial payments' statuses are also changed to `COMPLETED`.
Split tenders are available in regions that support order IDs for checkouts.
{% /accordion %}
### 3. Provide an itemized receipt when a Terminal checkout is completed
Including the `order_id` in the Terminal checkout request allows the Square Terminal to print a paper and digital receipt with itemization.
By default, the buyer sees the receipt options screen on the Terminal checkout and chooses a method to receive the receipt. The Square Terminal provides an itemized receipt using its built-in printer or a link to view the digital link from the buyer's email or a text message sent to the buyer's phone number.
The following animation shows the Square Terminal accepting a card payment and displaying the receipt options.
You can set the following additional receipt options:
{% accordion expanded=false %}
{% slot "heading" %}
#### Skip receipt options at checkout
{% /slot %}
By default, the `skip_receipt_screen` property is set to `false`. If this property is set to `true`, the Square Terminal skips the receipt options screen during checkout.
````
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
#### Set default to always print a receipt
{% /slot %}
You can set the Square Terminal to automatically print a receipt. This setting overrides the `skip_receipt_screen` value from the Terminal checkout request and doesn't display the receipt options screen.
To set the option to automatically print receipts on the Square Terminal, tap **Hardware**, **Printer**, **Receipts**, **Print Receipts**, and **Automatically**.
The following animation demonstrates how to set this option.
{% /accordion %}
{% accordion expanded=false %}
{% slot "heading" %}
#### Print formal receipts (Japan only)
{% /slot %}
For Square accounts in Japan, the Square Terminal prints both a standard receipt and a formal receipt called ryoshusho (領収書).
The Square Terminal provides the formal receipt option on the **Receipt Options** screen.
You can reissue formal receipts after checkout by using the `RECEIPT` Terminal action and include the `payment_id` that's returned from the completed Terminal checkout. For more information, see [Display the receipt options screen](terminal-api/advanced-features/issue-receipts#display-the-receipt-options-screen).
{% /accordion %}
### Take other types of payments and checkout features
Square Terminal supports processing other types of payments and additional checkout features. For more information, see [Additional Payment and Checkout Features](terminal-api/additional-payment-checkout-features).
---
# Additional Payment and Checkout Features
> Source: https://developer.squareup.com/docs/terminal-api/additional-payment-checkout-features
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to modify a Terminal checkout to accept other types of payments and enable additional checkout features.
**Applies to:** [Terminal API](terminal-api/overview) | [Orders API](orders-api/what-it-does) | [Payments API](payments-api/take-payments)
{% subheading %} Learn how to modify a Terminal checkout to accept other types of payments and enable additional checkout features.{% /subheading %}
## Overview
The Square Terminal supports processing additional types of payments for a given order that's [linked to a Terminal checkout](terminal-api/take-payments-for-orders) or for an [one-off payment](terminal-api/square-terminal-payments). Use a [CreateTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/creater-terminal-checkout) request to enable these features and a [PayForOrder](https://developer.squareup.com/reference/square/orders-api/pay-order) request to process the payment type for an order.
## Review payment types and checkout features
Each of the following sections demonstrate how to modify a `CreateTerminalCheckout` request to support a payment type or to enable a checkout feature.
## Take a delayed capture payment
The Square Terminal supports the delayed capture of payments made with the Square Point of Sale application. To learn how delayed capture works with card payments, see [Delayed Capture of a Card Payment](payments-api/take-payments/card-payments/delayed-capture).
The delayed capture flow with the Terminal API works as follows:
1. Create a [CreateTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/create-terminal-checkout) request and set `autocomplete` to `false` to authorize the payment but not capture it.
* The `autocomplete` attribute is a Boolean type that indicates whether `Payment` objects are automatically completed or left in an `APPROVED` state for later changes. The default value is `true`.
* The `delay_duration` attribute is a modifiable string type that indicates the length of time, in RFC 3339 format. By default, `delay_action` is set to `CANCEL`. If `delay_action` is set to `COMPLETE`, then payments will be automatically captured at the end of the delay window. 36 hours is the default, but more importantly 36 hours is the maximum duration for all Terminal checkouts. This property applies only when autocomplete is `false`.
````
2. When the buyer completes the checkout flow on the Square Terminal, the Terminal checkout transitions to `COMPLETED` and includes the resulting `payment_id`. The `Payment` object now has a status of `APPROVED`.
3. Call `UpdatePayment` using the `payment_id` to change the payment amount and tip amount after the payment is authorized.
4. Call `CompletePayment` to capture the payment or call `CancelPayment` to void the payment.
To learn more about updating payments, see [Update Payment and Tip Amounts](payments-api/update-payments).
## Take a partial authorized payment
The Square Terminal supports accepting partial payments with a Square gift card. The following information uses a Square gift card as an example.
A buyer swipes or manually enters a Square gift card on the Square Terminal. In the Terminal checkout request under `payment_options`, set `accept_partial_authorization` to `true` and `autocomplete` to `false`, which allows sellers to authorize a payment for less than the total amount when the Square gift card doesn't have sufficient funds.
The seller can then initiate a follow-up checkout request to authorize the remaining amount.
{% tabset %}
{% tab id="Request" %}
The Square Terminal displays the following warning message for the insufficient balance:
The following checkout request incorporates a partial payment authorization and a $20 order. The checkout request is for $20 USD and charging a Square gift card with a balance of $5.00.
````
{% /tab %}
{% tab id="Response" %}
After the buyer uses their gift card, the Terminal checkout is set to `COMPLETED` and the payment status is set to `APPROVED`.
```json
{
"checkout": {
"id": "WJ5393OCcdkqO",
"amount_money": {
"amount": 2000,
"currency": "USD"
},
"device_options": {
"device_id": "147CS149A7003873",
},
"status": "COMPLETED",
"created_at": "2025-03-11T18:02:32.005Z",
"updated_at": "2025-03-11T18:02:32.005Z",
"app_id": "sq0idp-dcqnATUXGLZMGmES5uuG0Q",
"order_id": "Cc2NJAhkrOd3aaHm2NQK9RM0kADZY",
"location_id": "W3Q7PHA6CMDH8",
"payment_type": "CARD_PRESENT",
"payment_options": {
"autocomplete": true
}
}
}
```
The Square Terminal displays the following receipt options screen for the $5.00 completed payment and indicates the remaining $15 due.
{% /tab %}
{% tab id="Pay remaining amount" %}
#### Pay the remaining amount of the order
To pay the remaining amount, which is $15 in this example, create another checkout with `autocomplete` set to `false` and `accept_partial_authorization` set to `true`. If you used an `order_id` for the first checkout, make sure to use the same `order_id` here.
````
After the buyer completes the Terminal checkout with a credit card, the seller must complete the order by using the [PayOrder](https://developer.squareup.com/reference/square/orders/pay-order) endpoint.
For more information about partial payments and how to pay for orders, see [Partial Payment Authorizations](payments-api/take-payments/card-payments/partial-payments-with-gift-cards) and [Pay for Orders](orders-api/pay-for-orders), respectively.
{% /tab %}
{% /tabset %}
## Take a payment with a manually entered card
The Square Terminal supports manual payment card entry by providing the [payment_type](https://developer.squareup.com/reference/square/objects/TerminalCheckout#definition__property-payment_type) field in the `TerminalCheckout` object and in the [CheckoutOptionsPaymentType](https://developer.squareup.com/reference/square/enums/CheckoutOptionsPaymentType) enumeration. When a `payment_type` with the value of `MANUAL_CARD_ENTRY` is specified in the checkout request, the Square Terminal displays the Manual Credit Card Entry form and a virtual keyboard for the input of card information.
The following command configures the Square Terminal checkout to accept manual payment card input:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The following response carries a checkout object with the `payment_type` requested:
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"note": "hamburger",
"payment_type": "MANUAL_CARD_ENTRY",
"device_id": "R5WNWB5BKNG9R",
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
## Take a payment with a signature
The Square Terminal supports the ability to require or skip collecting a signature for a payment by providing the `collect_signature` field for the [DeviceCheckoutOptions](https://developer.squareup.com/reference/square/objects/DeviceCheckoutOptions) object. If `collect_signature` is set to `true` in the checkout request, the Square Terminal displays the signature collection screen during checkout. The buyer is then required to provide a signature before proceeding to the next screen.
If `collect_signature` is set to `false`, the checkout skips the signature capture screen. The default value for `collect_signature` is `false`.
{% aside type="important" %}
* The Square API version must be 2022-04-20 or later to use the `collect_signature` field. If the `Square-Version` in the request header isn't set, the request defaults to using the API version from the Developer Console. For more information, see [How Square API versioning works](build-basics/versioning-overview#how-square-api-versioning-works).
* The `collect_signature` field is applicable only in the United States and Canada. In other regions, the Square Terminal determines whether it needs to collect signatures from buyers.
{% /aside %}
{% tabset %}
{% tab id="Request" %}
The following example demonstrates how to set up the Square Terminal checkout request to require signature collection:
````
{% /tab %}
{% tab id="Response" %}
The following response carries a checkout object with `collect_signature` requested:
```json
{
"checkout": {
"id": "jnaokd5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"note": "hamburger",
“device_options”: {
“device_id”: "R5WNWB5BKNG9R",
“collect_signature”: true
},
"payment_type": "CARD_PRESENT",
"device_id": "R5WNWB5BKNG9R",
"status": "PENDING",
"created_at": "2020-04-20T21:23:05.051Z",
"updated_at": "2020-04-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
## Take a fee from a payment
The Square Terminal supports collecting an application fee from a payment. The [app_fee_money](https://developer.squareup.com/reference/square/objects/TerminalCheckout#definition__property-app_fee_money) property has a value amount limit.
{% tabset %}
{% tab id="Request" %}
Create a [CreateTerminalCheckout](https://developer.squareup.com/reference/square/terminal-api/create-terminal-checkout) request and add `app_fee_money` with 100 ($1.00 USD) and USD as the amount and currency, respectively.
````
{% /tab %}
{% tab id="Response" %}
When the buyer completes the checkout flow on the Square Terminal, the Terminal checkout transitions to a `COMPLETED` state. A `payment_id` is attached to the Terminal checkout.
```json
{
"checkout": {
"id": "jnaokd5jsMbqO",
"amount_money": {
"amount": 500,
"currency": "USD"
},
"reference_id": "232323",
"note": "hamburger",
“device_options”: {
“device_id”: "R5WNWB5BKNG9R",
“collect_signature”: true
},
"payment_type": "CARD_PRESENT",
"device_id": "R5WNWB5BKNG9R",
"status": "COMPLETED",
"created_at": "2022-05-12T21:23:05.051Z",
"updated_at": "2022-05-12T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
Call the [GetPayment](https://developer.squareup.com/reference/square/payments/get-payment) endpoint using the `payment_id` from the Terminal checkout to verify that the application fee amount is properly attached to the payment and attributed to the application ID.
Sign in to the Square Dashboard as the seller associated with your application and navigate to the **Balances** section to verify that the expected amount has been added to your Square balance. After you've linked a bank account, the collected fees are transferred nightly to your linked bank account.
For more information about how to collect fees from payments, see [Collect Application Fees](payments-api/take-payments-and-collect-fees).
## Prompt the buyer for a tip at checkout
The following `device_options` settings configure the Square Terminal checkout to:
* Prompt for a tip on the Square Terminal.
* Show the receipt screen.
The `device_options` object sets the following behaviors:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The response is returned with a `PENDING` status. Note that the `PENDING` status changes to `IN_PROGRESS` when the Square Terminal acknowledges the request and shows the checkout display screen to the buyer while awaiting input. When the checkout is complete and Square has accepted the payment card, the status is `COMPLETED`.
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"note": "hamburger",
"device_options": {
"device_id": "R5WNWB5BKNG9R",
"tip_settings": {
"separate_tip_screen": true,
"custom_tip_field": false,
"allow_tipping": true
},
"skip_receipt_screen": false
},
"device_id": "R5WNWB5BKNG9R",
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
## Collect tip money prior to checkout
If the buyer uses the POS application to enter a tip amount before the checkout is sent to the Square Terminal, the seller doesn't need to use the Square Terminal to collect a tip. You already know the tip amount before calling the Terminal API, for which you use the `tip_money` parameter and the `amount_money` parameter in the checkout request.
A common scenario for this tip collection flow involves the seller using a kiosk POS application that calculates the tip and you don't want the buyer to enter the tip on the Square Terminal. The buyer-facing flow on the kiosk includes adding a tip and the kiosk then sends the total amount (including tip) to the Square Terminal as a checkout request.
The `tip_money` parameter can only be set and included in the request if the checkout request has tip settings disabled. The default value for the [allow_tipping](https://developer.squareup.com/reference/square/objects/TipSettings#definition__property-allow_tipping) field in the `TipSettings` object is `false`. For more information about how to process payments with tip money, see [Take Cash Payments](payments-api/take-payments/cash-payments) and [Update Payment and Tip Amounts](payments-api/update-payments).
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"note": "hamburger",
"device_options": {
"device_id": "R5WNWB5BKNG9R",
"tip_settings": {
"separate_tip_screen": true,
"custom_tip_field": false,
"allow_tipping": true
},
"skip_receipt_screen": false
},
"device_id": "R5WNWB5BKNG9R",
"tip_money": {
"amount": 100,
"currency": "USD",
},
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
## Assign a team member ID to the checkout
The team member ID is associated with an individual [TeamMember](https://developer.squareup.com/reference/square/objects/TeamMember) record and who is associated with creating the Terminal checkout.
The `team_member_id` is also passed to the final payment that was created during checkout.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"team_member_id": "7yJlHapkseXnNPETIU1B",
"note": "hamburger",
"device_options": {
"device_id": "R5WNWB5BKNG9R",
"tip_settings": {
"separate_tip_screen": true,
"custom_tip_field": false,
"allow_tipping": true
},
"skip_receipt_screen": false
},
"device_id": "R5WNWB5BKNG9R",
"tip_money": {
"amount": 100,
"currency": "USD",
},
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
For more information about setting up team members, see [Team API Integration Guide](team/integration).
## Add a statement description identifier to the checkout
Setting the `statement_description_identifier` field adds a custom identifier to the transaction description which appears on the buyer's bank statement.
For more information about statement descriptions, see [Card Payment and Statement Description](payments-api/take-payments/card-payments/statement-descriptions).
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"statement_description_identifier": "SQ *MYFASTFOOD*#05421",
"reference_id": "232323",
"team_member_id": "7yJlHapkseXnNPETIU1B",
"note": "hamburger",
"device_options": {
"device_id": "R5WNWB5BKNG9R",
"tip_settings": {
"separate_tip_screen": true,
"custom_tip_field": false,
"allow_tipping": true
},
"skip_receipt_screen": false
},
"device_id": "R5WNWB5BKNG9R",
"tip_money": {
"amount": 100,
"currency": "USD",
},
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
## Add a card surcharge
Auto Card Surcharging (ACS) automatically adds a surcharge to eligible card‑present transactions processed on Square Terminal via the Terminal API. The system completes the following tasks:
* **Applies a surcharge rate** - within network and jurisdictional rules. This setting is configured for each seller within the Square dashboard.
* **Provides developer API for transaction level control** - to allow an auto card surcharge on the payment.
* **Displays a UI element** - on the Square Terminal detailing surcharge amount.
* **Detects card type automatically** - (e.g. debit vs credit) to determine surcharge eligibility.
* **Itemizes the surcharge** - on Terminal screens and receipts.
* **Returns surcharge details** - in the Payment object for reporting and reconciliation.
{% aside type="important" %}
In order to create a payment with a card surcharge in the seller's Square Terminal, the following requirements need to be met:
* Square Terminal must be running OS version 5.57.0000 and App version 6.79 or higher to support Auto Card Surcharging
* To ensure the Terminal is running the latest version, swipe the screen from the left to open the menu screen, navigate to `Settings > Hardware > General > About Terminal`, and apply any software updates if available.
* Square seller must go through [surcharge onboarding](https://squareup.com/help/us/en/article/8596-set-up-and-manage-card-surcharges) in Square dashboard.
* Card surcharges are only supported in the US
* Only supported for `CARD_PRESENT` and `MANUAL_CARD_ENTRY` payment types
{% /aside %}
### Implementation
A new field is available within the [DeviceCheckoutOptions](https://developer.squareup.com/reference/square/objects/DeviceCheckoutOptions) to include in the [Create terminal checkout](https://developer.squareup.com/reference/square/terminal-api/create-terminal-checkout) request that allows an auto card surcharge if all Seller eligibility and payment instrument requirements are met.
When a card surcharge is added to a checkout request, the buyer-facing checkout UI shows details of the surcharge as shown in the following figure:
### Request and response examples
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"checkout": {
"id": "Dobuud5jsMbqO",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"reference_id": "232323",
"team_member_id": "7yJlHapkseXnNPETIU1B",
"device_options": {
"device_id": "R5WNWB5BKNG9R",
"tip_settings": {
"separate_tip_screen": true,
"custom_tip_field": false,
"allow_tipping": true
},
"skip_receipt_screen": false,
"allow_auto_card_surcharge": true
},
"device_id": "R5WNWB5BKNG9R",
"tip_money": {
"amount": 100,
"currency": "USD",
},
"status": "PENDING",
"created_at": "2020-03-20T21:23:05.051Z",
"updated_at": "2020-03-20T21:23:05.051Z",
"app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
}
}
```
{% /tab %}
{% /tabset %}
---
# Flutter Plugin
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/flutter
> Status: PUBLIC
> Languages: All
> Platforms: All
The Flutter plugin for the Square Mobile Payments SDK is an open source Dart interface for calling native Mobile Payments SDK implementations.
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios)
{% subheading %}Use Flutter to create applications that take payments on iOS and Android.{% /subheading %}
{% toc disabled=true /%}
## Overview
The Flutter plugin for the Mobile Payments SDK is an open source project that provides a Dart interface for calling the native Mobile Payments SDK implementations.
For more information and to start using the plugin, see the API Reference and sample application in the [Mobile Payments SDK Flutter repo on GitHub](https://github.com/square/mobile-payments-sdk-flutter).
## See also
* [React Native Plugin](mobile-payments-sdk/react-native)
---
# Tap to Pay on Android
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/tap-to-pay
> Status: BETA
> Languages: All
> Platforms: All
Use Tap to Pay on Android to accept payments with your own device, without the need for Square hardware.
Accept contactless payments with your Android phone and the Mobile Payments SDK without additional hardware.
## Requirements and limitations
* Tap to Pay requires a [compatible Android phone](https://squareup.com/us/en/compatibility?platform=Android) running Android 9 or later. Tap to Pay isn't available on Android tablets.
* Tap to Pay isn't available for [offline payments](mobile-payments-sdk/android/offline-payments#take-a-payment-offline).
## Device management
A compatible Android phone pairs automatically, unlike a Square Reader, which requires manual pairing. When the Mobile Payments SDK is operating on a compatible device, the device is enabled to accept payments. However, to take a payment with Tap to Pay, there cannot be any other Square Readers paired with the device. Before attempting a Tap to Pay payment, forget or disconnect any paired Square Readers.
Use the `ReaderInfo` class to learn details about connected readers and Tap to Pay devices available in the list of `readers`. For Tap to Pay devices, the `ReaderInfo.model` is always `TAP_TO_PAY`.
For more information, see [Pair and Manage Card Readers](mobile-payments-sdk/android/pair-manage-readers).
## Accept payments with Tap to Pay
To begin the payment flow in your application, you can use the `DEFAULT` `PromptParameters`, which displays a UI created by Square and lists the available payment methods from all connected readers.
{% aside type="important" %}
If you have a Square Reader paired with your device, only the payment options offered by that reader are displayed. To show the Tap to Pay on Android prompt, you must forget or disconnect any Square Readers paired to the device before starting the payment.
{% /aside %}
If you don't want to use the payment prompt built by Square, you can set your `PromptParameters.mode` to `CUSTOM` and create your own UI to prompt buyers to make their payment. If `paymentManager.getAvailableCardEntryMethods() = { CONTACTLESS }`, that means there are no hardware readers connected and you can display a Tap to Pay prompt in your UI. If `EMV` or `SWIPE` is listed as available card entry methods, there are other readers connected to your device and you shouldn't display a Tap to Pay prompt.
For any payment method, you should check whether the [reader status](mobile-payments-sdk/android/pair-manage-readers#reader-status) is `READY` (by setting up a callback with `ReaderManager.setReaderChangedCallback`) before displaying it as a payment option in your UI.
The rest of the [Mobile Payments SDK payment flow](mobile-payments-sdk/android/take-payments) is identical for Tap to Pay payments and other payment methods.
---
# Tap to Pay on iPhone
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/tap-to-pay
> Status: BETA
> Languages: All
> Platforms: All
Use Tap to Pay on iPhone to accept payments with your own device, without the need for Square hardware.
Accept contactless payments with your iPhone and the Mobile Payments SDK without additional hardware.
## Requirements and limitations
* Tap to Pay requires an iPhone XS or newer, running iOS 16.7 or later. Tap to Pay isn't available on iPads.
* Tap to Pay entitlement - You must [request the Tap to Pay entitlement for your Apple developer account](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone). To do so, you must have an organization-level developer account and be logged in as the account holder.
* When writing your integration, you should familiarize yourself with [Apple’s documentation for Tap to Pay on iPhone](https://developer.apple.com/tap-to-pay/).
* Tap to Pay isn't available for [offline payments](mobile-payments-sdk/ios/offline-payments).
## Link a Square seller account
Sellers using their iOS device to take payments must link their Square seller account with an Apple ID prior to taking payments with Tap to Pay. To present this option in your application, use the `ReaderManager.TapToPaySettings` to link an Apple account. The `linkAppleAccount()` function presents an Apple sheet to the user (the Square seller) prompting them to accept the Tap to Pay on iPhone terms and conditions.
As the application developer, you determine where in your application to launch this linking flow. You should ensure that this option is only available to admin users of your application or those with certain permissions. The seller doesn't need to be logged in to their Apple account on the device itself, they only need to log in to link their account when presented with the sheet.
The Mobile Payments SDK's `ReaderManager` also includes `relinkAppleAccount`, a method to relink (change) the associated Apple ID by presenting the Tap to Pay terms and conditions again, and `isAppleAccountLinked`, a method to check whether the device's Apple ID is already linked to a Square seller ID.
## Device management
The `ReaderManager` is used to pair and monitor changes in Square Readers and Tap to Pay devices linked to the authorized seller account. You can check `ReaderManager.TapToPaySettings.isDeviceCapable()` to determine whether the current device supports Tap to Pay.
A compatible iOS phone pairs automatically, unlike a Square Reader, which requires manual pairing. When the seller's Apple ID is linked to their Square account and the Mobile Payments SDK is operating on a compatible device, the device is enabled to accept payments.
Use the `ReaderInfo` class to learn details about connected readers and Tap to Pay devices available in the list of `readers`. For Tap to Pay devices, the `ReaderInfo.model` is always `tapToPay`.
For more information, see [Pair and Manage Card Readers](mobile-payments-sdk/ios/pair-manage-readers).
## Accept payments with Tap to Pay
To begin the payment flow in your application, you can use the `.default` `PromptParameters`, which displays a UI created by Square and lists the available payment methods from all connected readers, including Tap to Pay if the device is supported.
If you don’t want to use the payment prompt built by Square, you can set your `PromptParameters.mode` to `custom` and create your own UI to prompt buyers to make their payment based on the `readerInfo.supportedInputMethods` for each reader in `ReaderManager.readers`. You should check whether the [reader status](mobile-payments-sdk/ios/pair-manage-readers#reader-status) is `ready` (by setting up an observer) before displaying it as a payment option in your UI.
The rest of the [Mobile Payments SDK payment flow](mobile-payments-sdk/ios/take-payments) is identical for Tap to Pay payments and other payment methods.
---
# PHP SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/php/migration
> Status: PUBLIC
> Languages: All
> Platforms: All
Upgrade from the legacy version of the Square PHP SDK to version 41.0.0.20250220 or later.
Version `41.0.0.20250220` of the PHP SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `40.0.0.20250123` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
The new `Client` class has some breaking changes and is constructed in a slightly different way than the legacy version of the SDK.
{% table %}
* Legacy
* New
* Additional information
---
* `Environment`
* `baseUrl`
* An enum for specifying the environment (Sandbox or Production).
---
* `accessToken`
* `token`
* The access token used for authentication.
---
* `customUrl`
* `baseUrl`
* The base URL for API requests.
---
* `numberOfRetries`
* `maxRetries`
* The configuration used to control the number of retries.
---
* `additionalHeaders`
* `headers`
* Additional headers can be set at individual methods.
---
* `httpCallback`
* Removed
* This option has been removed.
---
* `userAgentDetail`
* Removed
* This option has been removed.
*
{% /table %}
```php
// LEGACY
use Square\Legacy\SquareClient as LegacySquareClient;
$client = new LegacySquareClient(
config: [
'accessToken' => getenv('SQUARE_ACCESS_TOKEN') ?? '',
'environment' => 'sandbox',
],
);
// NEW
use Square\Environments;
use Square\SquareClient;
$client = new SquareClient(
token: getenv('SQUARE_ACCESS_TOKEN') ?? '',
options: [
'baseUrl' => Environments::Sandbox->value,
],
);
```
## Use the legacy and new SDK side by side
While the new SDK has many improvements, we understand that it takes time to upgrade when there are breaking changes. To make the migration easier, the new SDK exports the legacy SDK as `Square/Legacy`. The following example shows how to use the new and legacy SDKs inside a single file:
```php
getenv('SQUARE_ACCESS_TOKEN') ?? '',
'environment' => 'sandbox',
]);
$client = new SquareClient(
token: getenv('SQUARE_ACCESS_TOKEN') ?? '',
options: [
'baseUrl' => Environments::Sandbox->value,
],
);
function getLocation($client) {
$response = $client->locations->get(
new GetLocationsRequest([
'locationId' => 'YOUR_LOCATION_ID',
]),
);
return $response->getLocation();
}
function createOrder($legacyClient, $location) {
$order = new Order($location['id']);
$request = new CreateOrderRequest;
$request->setIdempotencyKey(uniqid());
$request->setOrder($order);
return $legacyClient->getOrdersApi()->createOrder($request);
}
$location = getLocation($client);
$result = createOrder($legacyClient, $location);
```
You should migrate to the new SDK using the following steps:
1. Upgrade the square/square package to `^41.0.0.20250220`.
2. Search and replace all requires and imports from `Square` to `Square\Legacy`.
3. Gradually introduce methods from the new SDK by importing them from the `Square` import.
## Array constructors
The previous version of the SDK relied on using a mix of builders and setter methods, which created verbose integrations. For example, consider the following `createOrder` method call:
```php
// LEGACY
$order = new Order($location['id']);
$request = new CreateOrderRequest;
$request->setIdempotencyKey(uniqid());
$request->setOrder($order);
$legacyClient->getOrdersApi()->createOrder($request);
```
In the new SDK, you can consolidate all the parameters in a single statement. All the parameters are still specified by their name, which makes their meaning instantly clear.
```php
// NEW
$client->orders->create(
new CreateOrderRequest([
'idempotencyKey' => uniquid(),
'order' => new Order([
'locationId' => $location['id'],
]),
]),
)
```
## Enums
This SDK leverages the PHP 8.1 first-class enums to improve type safety and usability. To maintain forward compatibility with the API (where new enum values might be introduced in the future), enum properties are defined as `string` and use `value-of` annotations to specify the corresponding enum type.
The best example of this is when the client's base URL or environment is configured.
```php
// LEGACY
use Square\Legacy\SquareClient as LegacySquareClient;
$client = new LegacySquareClient(
config: [
'environment' => 'sandbox',
],
);
// NEW
use Square\Environments;
use Square\SquareClient;
$client = new SquareClient(
options: [
'baseUrl' => Environments::Sandbox->value, // Enums can be accessed with '->value'.
],
);
```
## API classes and method name changes
Previously, API classes were named after the resource you're interacting with and suffixed with `Api`. To interact with customer resources, you used the `client->getCustomersApi()` method.
The method was named based on the action you want to perform and the same resource name specified earlier. To list customers, you call `client->getCustomersApi()->listCustomers`.
```php
// LEGACY
$client->getCustomersApi()->listCustomers();
```
The new API classes are named after the resource without the `Api` suffix and their methods are named after the action without repeating the resource name.
```php
// NEW
$client->customers->list();
```
When interacting with a nested resource, you can chain the resources using the arrow-notation.
```php
// NEW
$client->customers->groups->list();
```
Other class and method names might have changed. The differences are easiest to discover by exploring the new method signatures.
## Auto-pagination
The Square paginated endpoints now support auto-pagination with an iterator. Callers don’t need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes. The following example shows the same code, with the legacy and new SDK:
```php
// LEGACY
$limit = 10;
$listCustomersResponse = $legacyClient->getCustomersApi()->listCustomers(
limit: $limit,
sortField: 'DEFAULT',
sortOrder: 'DESC'
);
while (!empty($listCustomersResponse->getCustomers())) {
$customers = $listCustomersResponse->getCustomers();
foreach ($customers as $customer) {
echo sprintf(
"customer: ID: %s Version: %s, Given name: %s, Family name: %s\n",
$customer->getId(),
$customer->getVersion(),
$customer->getGivenName(),
$customer->getFamilyName()
);
}
$cursor = $listCustomersResponse->getCursor();
if ($cursor) {
$listCustomersResponse = $legacyClient->getCustomersApi()->listCustomers(
cursor: $cursor,
limit: $limit,
sortField: 'DEFAULT',
sortOrder: 'DESC'
);
} else {
break;
}
}
// NEW
$customers = $client->customers->list(
new ListCustomersRequest([
'limit' => 10,
'sortField' => 'DEFAULT',
'sortOrder' => 'DESC'
]),
]);
foreach ($customers as $customer) {
echo sprintf(
"customer: ID: %s Version: %s, Given name: %s, Family name: %s\n",
$customer->getId(),
$customer->getVersion(),
$customer->getGivenName(),
$customer->getFamilyName()
);
}
```
If you need to paginate page by page, you can still do so with a lot less code:
- Use `$customers->getPages()` to iterate over each page individually.
- Use `$customers->getItems()` to get the customers of the current page.
```php
$customers = $client->customers->list(
new ListCustomersRequest([
'limit' => 10,
'sortField' => 'DEFAULT',
'sortOrder' => 'DESC'
]),
]);
foreach ($customers->getPages() as $page) {
foreach($customer as $page->getItems()) {
echo sprintf(
"customer: ID: %s Version: %s, Given name: %s, Family name: %s\n",
$customer->getId(),
$customer->getVersion(),
$customer->getGivenName(),
$customer->getFamilyName()
);
}
}
```
If you need to paginate page by page, you can still do so with a lot less code:
- Use `$customers.getPages()` to iterate over each page individually.
- Use `$customers.getItems()` to get the customers of the current page.
```php
$customers = $client->customers->list(
new ListCustomersRequest([
'limit' => 10,
'sortField' => 'DEFAULT',
'sortOrder' => 'DESC'
]),
]);
foreach ($customers->getPages() as $page) {
foreach($customer as $page->getItems()) {
echo sprintf(
"customer: ID: %s Version: %s, Given name: %s, Family name: %s\n",
$customer->getId(),
$customer->getVersion(),
$customer->getGivenName(),
$customer->getFamilyName()
);
}
}
```
---
# Build a Developer Team
> Source: https://developer.squareup.com/docs/devtools/developer-permissions
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to add a developer to your Square development team and give them the right set of permissions.
{% subheading %}Learn how to add a developer to your Square development team and give them the correct set of permissions.{% /subheading %}
{% toc hide=true /%}
## Overview
When you create team member profiles in the [Square Dashboard](https://app.squareup.com/dashboard/team/team-members), new team members are invited to your developer organization. You define jobs and permissions for team members in this process flow. It's the same flow that a seller uses to invite a new team member except that a new developer is assigned permissions for the Developer Console and optionally assigned permissions to your Square account.
## Pricing
When you create a new Square account, you get a default team permissions set and one custom permission set. For more than two levels of access, you need an [Advanced Access](https://squareup.com/staff/advanced-access) subscription, which includes customized access, team insights, and enhanced security. In order to get the Advanced Access subscription, your Square account needs to be based in one of the following countries:
* Australia
* Canada
* France
* Ireland
* Japan
* Spain
* United Kingdom
* United States
## Team roles
The default team permissions set can be customized to include developers permissions for Developer Console access. This is useful if all team members are developers. If your team includes non-developers, such as coffee shop staff using Square Point of Sale, you shouldn't add developer permissions to the default set. Instead, create a new permission set specifically for developers.
Your development team might include roles for:
* **Developers** - People who write code, create or manage application registrations, set application credentials, manage OAuth parameters, or work with other configurations.
* **Technical support** - People on your team who set up your application in production at a seller's site.
* **Product marketing** - Team members who manage communication and marketing.
{% aside type="info" %}
If you need to provide a permission set for each of these developer roles, you must have an Advanced Access subscription.
{% /aside %}
All of these roles need access to different parts of the Developer Console. It's a good practice to scope team member access to only the functions in the Developer Console that a team member needs to do their job. For example, settings on the **OAuth** tab shouldn't be accessible to a team member in the product marketing role.
## Developer Console permissions
The following image shows the developer permission selection dialog in the Team application.
To support building a team of developers for your organization, the Square Dashboard is used to manage developer team members as you might manage other team members. Use the Square Dashboard to [create team members](https://squareup.com/help/us/en/article/8356-add-and-manage-team-members). You can create and assign developer jobs and permission sets that contain developer permissions. If your team is building an application in the Developer Console, it's a good practice to set appropriate levels of access to console features.
To create a team for your organization, complete these steps:
1. **Add a team member** - Each new team member is assigned a permission set and a job title.
1. **Assign a job title** - Assign a new or existing job title.
{% aside type="important" %}
Job titles are case-sensitive. You can create both a 'Developer' and a 'developer' job. When adding a team member with the title 'Developer,' ensure you select the correct 'Developer' job title again for consistency.
{% /aside %}
2. **Customize or create a permission set** - Add developer permissions to an existing permission set or create a new permission set enabled for developers.
3. **Assign the permission set** - Assign the developer-enabled permission set to the team member.
{% aside type="tip" %}
After you've got a developer permission set, you can assign it to the next developer team members you create.
{% /aside %}
## Create a permission set
Create permission sets in the Square Dashboard to control access to the Developer Console. If you've given the default team permissions to non-developers, don't customize it for developers. Instead, make new permission sets for your developer team. For more information, see [Create Permission Sets](https://squareup.com/help/article/5822-employee-permissions). If you often use the Developer Console, choose **Account** and then **Settings**. On the **Settings** menu, choose **Manage team** to reach the Team page in the Square Dashboard.
The jobs and permission sets usually created include **Product Marketing**, **IT Support**, and **Developer** - This job needs access to tools such as [API Explorer](devtools/api-explorer), [API Logs](devtools/api-logs), [webhook configurations](webhooks/overview), the [Sandbox](devtools/sandbox/overview) for testing, and limited seller account permissions to verify that the application integration code is working correctly. If all roles use the same permissions, then customize the default team permissions set instead of creating a new permission set for each role.
### Recommended permissions and roles
When you add a new member to your development team, you can give them access to Square Point of Sale apps like Checkout, Orders, Invoices, and Appointments. They might need these apps to test the integration code they write.
Besides these apps, the new team member needs access to features in the Developer Console to do their job. You assign developer-specific permissions in the **Team** app on the Square Dashboard. There are three developer permissions, and two of them have an extra permission, as shown in the [Developer Console permissions](#developer-console-permissions) section.
{% accordion expanded=false %}
{% slot "heading" %}
### Developer permissions
{% /slot %}
{% line-break /%}
{% line-break /%}
These development-specific permissions provide access to Developer Console functions as shown in the following table:
{% table %}
* Permission {% width="170px" %}
* View basic application information {% width="100px" %}
* Access all developer tools{% width="100px" %}
* Create and view personal access tokens{% width="110px" %}
* View App Marketplace submissions{% width="110px" %}
* Manage App Marketplace listings{% width="110px" %}
---
* View an account owner's email address
* ✅
* ⛔
* ⛔
* ⛔
* ⛔
---
* Add, change, and delete an account owner's email address
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* View and open applications
* ✅
* ⛔
* ⛔
* ⛔
* ⛔
---
* Add new applications
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Open Sandbox test accounts and read Sandbox credentials
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Create new Sandbox test accounts, replace Sandbox credentials
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Read production application credentials and locations
* ⛔
* ⛔
* ✅
* ⛔
* ⛔
---
* Replace production application credentials and application version
* ⛔
* ⛔
* ✅
* ⛔
* ⛔
---
* Read production OAuth credentials
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Update production OAuth credentials
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* View application webhook subscriptions and webhook logs
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Add application webhook subscriptions
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* View a Reader SDK application repository password
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Replace a Reader SDK application repository password
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Read a Point of Sale API configuration - iOS
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Add an Android Point of Sale package
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* View the Apple Pay domain URL
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* Add and verify the Apple Pay domain URL
* ⛔
* ✅
* ⛔
* ⛔
* ⛔
---
* View API logs for an application
* ✅
* ⛔
* ⛔
* ⛔
* ⛔
---
* Respond to App Marketplace reviews
* ⛔
* ⛔
* ⛔
* ⛔
* ✅
---
* View App Marketplace listings and submissions
* ⛔
* ⛔
* ⛔
* ✅
* ⛔
---
* Edit and submit an App Marketplace listings or submission
* ⛔
* ⛔
* ⛔
* ⛔
* ✅
{% /table %}
{% /accordion %}
## Manage ownership of a Square account
As your team of developers evolves and your business grows, you might find it necessary to update information about your Square account. For information about editing your account, see [Manage Your Account and Business Settings](https://squareup.com/help/article/3861-edit-your-account-and-business-settings) to secure your account, change language preferences, and keep your business information up to date.
You can transfer your Square account to a new owner or accept a transfer to become the new owner of an existing Square account. For information, see [Transfer Ownership of Your Square Account](https://squareup.com/help/article/7675-transfer-ownership-of-your-square-account).
## Additional resources
* [Team API](team/overview) - Your team of developers along with their job details can be retrieved and managed using the Team API.
* [Labor API](labor-api/what-it-does) - If you need to track the hours that a team member works on a project, you can use the Labor API to create a time clock that lets a member of your team record their hours. These same APIs let you build labor reports for costing purposes.
---
# React Native Plugin
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/react-native
> Status: PUBLIC
> Languages: All
> Platforms: All
The React Native plugin for the Square Mobile Payments SDK is an open source JavaScript interface for calling native Mobile Payments SDK implementations.
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios)
{% subheading %}Use React Native to create applications that take payments on iOS and Android.{% /subheading %}
{% toc disabled=true /%}
## Overview
The React Native plugin for the Mobile Payments SDK is an open source project that provides a JavaScript interface for calling native Mobile Payments SDK implementations.
For more information and to start using the plugin, see the API Reference and sample application in the [Mobile Payments SDK React Native repo on GitHub](https://github.com/square/mobile-payments-sdk-react-native/tree/main).
## See also
* [Flutter Plugin](mobile-payments-sdk/flutter)
---
# Node.js SDK Migration Guide
> Source: https://developer.squareup.com/docs/sdks/nodejs/migration
> Status: PUBLIC
> Languages: All
> Platforms: All
Upgrade from the legacy version of the Square Node.js SDK to version 40.0.0 or later.
Version `40.0.0` of the Node.js SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.
SDK versions `39.1.0` and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.
## Client construction
The new `Client` class has some breaking changes and is constructed in a slightly different way than the legacy version of the SDK.
{% table %}
* Legacy
* New
* Additional information
---
* `Client`
* `SquareClient`
* The main client class for interacting with Square APIs.
---
* `Environment`
* `SquareEnvironment`
* An enum for specifying the environment (Sandbox or Production).
---
* `bearerAuthCredentials.accessToken`
* `token`
* The access token used for authentication.
---
* `customUrl`
* `baseUrl`
* The base URL for API requests.
---
* `squareVersion`
* `version`
* The Square API version to use.
---
* N/A
* `fetcher`
* Provide your own fetch function for making HTTP requests.
---
* `timeout`
* Removed
* Timeout can be set at individual methods.
---
* `additionalHeaders`
* Removed
* Additional headers can be set at individual methods.
---
* `httpClientOptions`
* Removed
* HTTP options can be set at individual methods.
---
* `unstable_httpClientOptions`
* Removed
* This option has been removed.
---
* `userAgentDetail`
* Removed
* This option has been removed.
*
{% /table %}
```javascript
// LEGACY
import { Client, Environment } from "square/legacy";
const client = new Client({
bearerAuthCredentials: {
accessToken: process.env.SQUARE_ACCESS_TOKEN,
},
environment: Environment.Sandbox,
});
// NEW
import { SquareClient, SquareEnvironment } from "square";
const client = new SquareClient({
token: process.env.SQUARE_ACCESS_TOKEN,
environment: SquareEnvironment.Sandbox,
});
```
## Use the legacy and new SDK side by side
While the new SDK has many improvements, we understand that it takes time to upgrade when there are breaking changes. To make the migration easier, the new SDK exports the legacy SDK as `square/legacy`. The following example shows how to use the new and legacy SDKs inside a single file:
```javascript
import { randomUUID } from "crypto";
import { Square, SquareClient } from "square";
import { Client } from "square/legacy";
const client = new SquareClient({
token: process.env.SQUARE_ACCESS_TOKEN,
});
const legacyClient = new Client({
bearerAuthCredentials: {
accessToken: process.env.SQUARE_ACCESS_TOKEN!,
},
});
async function getLocation(): Promise {
return (
await client.locations.get({
locationId: "YOUR_LOCATION_ID",
})
).location!;
}
async function createOrder() {
const location = await getLocation();
await legacyClient.ordersApi.createOrder({
idempotencyKey: randomUUID(),
order: {
locationId: location.id!,
lineItems: [
{
name: "New Item",
quantity: "1",
basePriceMoney: {
amount: BigInt(100),
currency: "USD",
},
},
],
},
});
}
createOrder();
```
You should migrate to the new SDK using the following steps:
1. Upgrade the NPM module to `^40.0.0`.
2. Search and replace all requires and imports from `"square"` to `"square/legacy"`.
* For required, replace `require("square")` with `require("square/legacy")`.
* For imports, replace `from "square"` with `from "square/legacy"`.
* For dynamic imports, replace `import("square")` with `import("square/legacy")`.
3. Gradually introduce methods from the new SDK by importing them from `"square"`.
{% aside type="info" %}
If you're using TypeScript, make sure that the `moduleResolution` setting in your `tsconfig.json` is equal to `node16`, `nodenext`, or `bundler` to consume the legacy SDK.
{% /aside %}
## Named parameters
The previous version of the SDK relied on many positional parameters, which made it difficult for readers to understand the meaning of the parameter. For example:
```javascript
// LEGACY
await client.customersApi.listCustomers(undefined, 10, undefined, "DESC");
```
It's not immediately clear what `undefined`, `10`, `undefined`, and `DESC` mean. In the new version of the SDK, you specify the parameters by their name and you're not required to pass `undefined` parameters. The same `ListCustomers` request looks like the following:
```javascript
// NEW
await client.customers.list({
limit: 10,
sortOrder: "DESC",
});
```
## API classes and method name changes
Previously, API classes were named after the resource you're interacting with and suffixed with `Api`. To interact with customer resources, you used the `client.customersApi` class.
The method was named based on the action you want to perform and the same resource name specified earlier. To list customers, you call `client.customersApi.listCustomers`.
```javascript
// LEGACY
await client.customersApi.listCustomers();
```
The new API classes are named by the resource without the `Api` suffix, and the methods now name the action without mentioning the resource a second time.
```javascript
// NEW
await client.customers.list();
```
When interacting with a nested resource, you can chain the resources using dot-notation.
```javascript
// NEW
await client.customers.groups.list();
```
To find all classes and method names that might have changed, see [reference.md](https://github.com/square/square-nodejs-sdk/blob/master/reference.md).
## Auto-pagination
Paginated endpoints now support auto-pagination with an async iterator. Callers don’t need to manually fetch the next page at all. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.
The following example shows the same code, with the legacy and new SDK:
```javascript
// LEGACY
const limit = 10;
let listCustomersResponse = await customersApi.listCustomers(
undefined,
limit,
"DEFAULT",
"DESC"
);
while (!isEmpty(listCustomersResponse.result)) {
let customers = listCustomersResponse.result.customers;
customers.forEach(function (cust) {
console.log(
"customer: ID: " + cust.id,
"Version: " + cust.version + ",",
"Given name: " + cust.givenName + ",",
"Family name:" + cust.familyName
);
});
let cursor = listCustomersResponse.result.cursor;
if (cursor) {
listCustomersResponse = await customersApi.listCustomers(
cursor,
limit,
"DEFAULT",
"DESC"
);
} else {
break;
}
}
// NEW
let customerPager = await client.customers.list({
limit: 10,
sortField: "DEFAULT",
sortOrder: "DESC",
});
for await (const customer of customerPager) {
console.log(
"customer: ID: " + customer.id,
"Version: " + customer.version + ",",
"Given name: " + customer.givenName + ",",
"Family name: " + customer.familyName
);
}
```
If you need to paginate page by page, you can still do so with a lot less code:
- Use `customerPager.data` to get the customers of the current page.
- Use `customerPage.hasNextPage()` to check whether there's another page after the current one.
- Use `customerPage.getNextPage()` to retrieve the next page of customers.
```javascript
let customerPager = await client.customers.list({
limit: 10,
sortField: "DEFAULT",
sortOrder: "DESC",
});
const printCustomers = (customers: Square.Customer[]) => {
for (const customer of customers) {
console.log(
"customer: ID: " + customer.id,
"Version: " + customer.version + ",",
"Given name: " + customer.givenName + ",",
"Family name: " + customer.familyName
);
}
};
printCustomers(customerPager.data);
while (customerPager.hasNextPage()) {
customerPager = await customerPager.getNextPage();
printCustomers(customerPager.data);
}
```
## Big integers
The SDK requires you to pass in a `BigInt` to any field that is typed as a long or a big integer in Square's API. The SDK also guarantees that longs and big integers are returned as `BigInt` from the API.
Here's an example of passing in a `BigInt`:
```javascript
await client.orders.create({
idempotencyKey: idempotencyKey,
order: {
locationId: locationId,
lineItems: [
{
name: "New Item",
quantity: "1",
basePriceMoney: {
amount: BigInt(100),
currency: "USD",
},
},
],
},
});
```
Make sure to remove the `BigInt.prototype.toJSON` workaround from your code if you were previously using it. The prototyping workaround causes issues with the SDK, which already handles big integers correctly.
## Next steps
For more sample code and examples of using the new Node.js SDK, see [Common Square API Patterns](sdks/nodejs/common-square-api-patterns).
---
# Go SDK
> Source: https://developer.squareup.com/docs/sdks/go
> Status: PUBLIC
> Languages: All
> Platforms: All
Use the Square Go library to build with Square APIs in a language-idiomatic way that reduces complexity without sacrificing API functionality.
{% subheading %}The Square Go library supports Square APIs in a language-idiomatic way that reduces complexity without sacrificing API functionality.{% /subheading %}
{% toc hide=true /%}
{% card-layout%}
{% card iconPath="//images.ctfassets.net/1nw4q0oohfju/14OXUvUMscxqnOrElYjHi1/d29fb3702f93d44836c463d3657e51f6/go-bw.svg" href="https://pkg.go.dev/github.com/square/square-go-sdk" %}
{% card-link-out %}SDK package{% /card-link-out %}
{% /card %}
{% card iconPath="//images.ctfassets.net/1nw4q0oohfju/6foMeNHsmKw27jkpa7lPHk/6d5da15335dcf70d1fd1c28ca3bb540e/Github.svg" href="https://github.com/square/square-go-sdk/tree/master" %}
{% card-link-out %}Reference library docs{% /card-link-out %}
{% /card %}
{% /card-layout %}
{% line-break /%}
**Latest SDK Version:** v4.0.1
Each SDK version is tied to a specific [Square API version](build-basics/versioning-overview). As features are added, Square releases a new Square API version and a new SDK version. To use new features, you must update the SDK version in your application. Review the [release notes](changelog/connect) to learn about changes in each API version.
An increase in the SDK major version number indicates a breaking change. You should always test your application before deploying a change to production.
## Quickstart
* Follow along with the [Quickstart guide](sdks/go/quick-start) to set up and test the Square Go SDK in your own project.
* Download the [Square Go SDK sample app](https://github.com/Square-Developers/go-getting-started/tree/main) and follow the instructions in the README.
---
# Square Go SDK Quickstart
> Source: https://developer.squareup.com/docs/sdks/go/quick-start
> Status: BETA
> Languages: All
> Platforms: All
Learn how to quickly set up and test the Square Go SDK.
{% subheading %}Learn how to quickly set up and test the Square Go SDK.{% /subheading %}
{% toc hide=true /%}
## Prepare for the Quickstart
Before you begin, you need a Square account and account credentials. You use the Square Sandbox for the Quickstart exercise.
1. Create a Square account and an application. For more information, see [Create an Account and Application](get-started/create-account-and-application).
2. Get a Sandbox access token from the Developer Console. For more information, see [Get a personal access token](build-basics/access-tokens#get-a-personal-access-token).
3. Install the following:
* [Go](https://go.dev/) - Square supports Go version 1.18 or later.
{% aside type="info" %}
If you prefer to skip the following setup steps, download the [Square Go SDK Quickstart](https://github.com/Square-Developers/go-getting-started) sample and follow the instructions in the README.
{% /aside %}
## Create a project
1. Open a new terminal window.
2. Create a new directory for your project, navigate to that directory, and initialize a new Go module.
```
mkdir quickstart
cd quickstart
go mod init quickstart
```
3. Run the following command to use the Square Go library in your module:
```
go get github.com/square/square-go-sdk
```
## Write code
1. In your project directory, create a new file named quickstart.go with the following content:
```go
import (
"context"
"fmt"
"os"
square "github.com/square/square-go-sdk"
client "github.com/square/square-go-sdk/client"
option "github.com/square/square-go-sdk/option"
)
func main() {
client := client.NewClient(
option.WithToken(
os.Getenv("SQUARE_ACCESS_TOKEN"),
),
option.WithBaseURL(square.Environments.Sandbox),
)
// Get the list of locations
response, err := client.Locations.List(context.TODO())
if err != nil {
fmt.Println(err)
} else {
for l := range response.Locations {
fmt.Printf("ID: %s \n", *response.Locations[l].ID)
fmt.Printf("Name: %s \n", *response.Locations[l].Name)
fmt.Printf("Address: %s \n", *response.Locations[l].Address.AddressLine1)
fmt.Printf("%s \n", *response.Locations[l].Address.Locality)
}
fmt.Println(response)
}
}
```
This code does the following:
1. Creates a new `client` object with your Square access token. For more information, see [Set your Square credentials](#set-credentials).
2. Calls the `Locations.List` method.
3. If the request is successful, your Square location details are printed in the terminal window.
## Set your Square credentials
The Go code in this Quickstart reads your Square Sandbox access token from the `SQUARE_ACCESS_TOKEN` environment variable. This helps avoid the use of hardcoded credentials in the code.
For the following commands, replace `yourSandboxAccessToken` with your Square Sandbox access token:
### Linux or macOS
```bash
export SQUARE_ACCESS_TOKEN=yourSandboxAccessToken
```
### Windows: PowerShell
```bash
Set-item -Path Env:SQUARE_ACCESS_TOKEN -Value yourSandboxAccessToken
```
### Windows: Command shell
```bash
set SQUARE_ACCESS_TOKEN=yourSandboxAccessToken
```
## Run the application
1. In your quickstart directory, run the `go build` command to compile the code.
2. Run your program with `./quickstart`.
2. Verify the result. You should see at least one location, even if you just created your Square account.
---
# Take QR Code Payments for Digital Wallets
> Source: https://developer.squareup.com/docs/terminal-api/international-payment-methods/paypay-qr-code-payments
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to set up QR code payments for multiple digital wallet brands in Japan with the Terminal API.
**Applies to:** [Terminal API](terminal-api/overview)
{% subheading %}Use the Terminal API to take QR code payments for multiple digital wallets in Japan.{% /subheading %}
{% toc hide=true /%}
## Requirements and limitations
* The Terminal API supports multiple digital wallet brands for a QR code payment.
* Square Terminal must be running version 6.58 or later to accept a QR code payment.
* Square Terminal must be activated and located in Japan.
* The seller must be approved to accept QR code payments in Japan. For more information, see [Apply for QR code payment](https://squareup.com/help/jp/ja/article/8370-apply-for-qr-code-payments), which can be viewed in English or Japanese.
## Request a Terminal checkout for a QR code payment
The [Terminal API](https://developer.squareup.com/reference/square/terminal-api) supports multi-brand QR code payments by providing the [payment_type](https://developer.squareup.com/reference/square/objects/TerminalCheckout#definition__property-payment_type) field in the `TerminalCheckout` object and the [CheckoutOptionsPaymentType](https://developer.squareup.com/reference/square/enums/CheckoutOptionsPaymentType) enumeration. When a `payment_type` has the `QR_CODE` enumerator value specified in the checkout request, the Terminal displays a multi-brand QR code for the buyer to scan. For example, if the seller supports the PayPay digital wallet brand, the buyer can make a PayPay payment by scanning the QR code.
The QR code supports digital wallets that are connected to a specific seller location and each seller account can have multiple locations. The following example shows a Terminal checkout request with the QR code `payment_type`. This checkout request launches the QR code screen on the Square Terminal:
````
---
# Define Item Variations Using Options
> Source: https://developer.squareup.com/docs/catalog-api/item-options
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to use item options to simplify the process of creating standard variants for catalog items.
**Applies to:** [Catalog API](catalog-api/what-it-does)
{% subheading %}Learn how to use item options to simplify the process of creating standard variants for catalog items.{% /subheading %}
{% toc hide=true /%}
## Overview
Leveraging item options offers a more efficient strategy for application developers, especially when addressing inconsistencies in how sellers name product variations. By standardizing attributes like size and color, item options simplify the search process, allowing users to quickly find specific variations (such as a large red polo shirt) without navigating through poorly labeled or inconsistent entries (such as like Large red polo shirt, Red Polo shirt - LG, or Polo shirt: red large). This approach enhances usability and ensures a more seamless shopping experience.
## Item options and variations
The [Catalog API](https://developer.squareup.com/reference/square/catalog-api) includes several objects that enable efficient and standardized definitions of item variations in the seller's inventory. These objects include:
* [Items](https://developer.squareup.com/reference/square/objects/CatalogItem) - Generalized items, such as "Shirt".
* [Item variation](https://developer.squareup.com/reference/square/objects/CatalogItemVariation) - Specific items for sale, such as "Polo shirt: Lg, red".
* [Item options](https://developer.squareup.com/reference/square/objects/CatalogItemOption) - Standardized attributes such as color, size, and style.
When creating item variations in the Square Dashboard, sellers have two options: using item options or the variation name model. In both cases, the `item_variation_data.name` property is assigned a descriptive name. If item options are used, Square sets the variation name by combining the chosen option values into a comma-separated string and the `item_variation_data.item_option_values` property references the selected options and values.
{% aside type="important" %}
When using item options, the `CatalogItemVariation.name` includes only the option values, not the item's name (for example, "Large, Red" instead of "Polo shirt: Large, Red"). The item name should be set in the parent catalog item, such as "Polo shirt".
{% /aside %}
### Defining variations
There are two strategies for defining shirt variations:
* [Item variation name strategy](#variation-strategy) - Add variation attributes to its name (such as "small red polo shirt").
* [Item option strategy](#option-strategy) - Use item options to set variation attributes (such as "small", "red", and "polo").
When the variation name strategy is used, a seller might give variations inconsistent names, such as:
* "LG Red Camp Shirt".
* "Blue Polo shirt - small".
* "Yellow T-shirt: XL".
This can complicate searches within your application. For example, finding a blue polo shirt involves a text query like "blue polo shirt" to locate the relevant catalog objects. For more information, see [Search for item variations by searchable attribute](#text-query).
### Benefits of using item options
Item options streamline the creation of item variations by linking them to standardized attributes, such as these examples:
* **Color** - Options include "Red", "Green", and "Blue".
* **Size** - Options range from "Extra Large" to "Small".
* **Style** - Varieties such as "Polo", "Dress", and "Camp".
After your application creates a [CatalogItemOption](https://developer.squareup.com/reference/square/objects/CatalogItemOption)—such as "color" with predefined values—that option can be applied to define the color attribute for any new catalog items. Your application can also use catalog item options created by the seller in the Square Dashboard.
Using item options, a variation is automatically generated for every combination of option values. Each variation is linked to options and values (such as Red, Small, and Polo), eliminating the need for sellers to manually format individual descriptions. These examples (color, size, and style) are just that—examples. Your application can create any type of option with various values.
For information about querying by item option value, see [Search for item variations using item options](#option-query).
{% anchor id="variation-strategy" /%}
## Item variation name strategy
Item variations can be straightforward, defined by a single characteristic, or more complex, combining multiple characteristics to represent a composite variation.
In the following example, $35 polo shirts in three sizes and two colors are sold by a clothing retailer. To add these shirts to the catalog, six item variations are created. All the shirts have the same variation properties except for the variation name, which is unique to each variation.
* "Polo shirt, Red, Large"
* "Polo shirt, Red, Medium"
* "Polo shirt, Red, Small"
* "Polo shirt, Blue, Large"
* "Polo shirt, Blue, Medium"
* "Polo shirt, Blue, Small"
In the seller's item library and at the point of sale, items are organized alphabetically by name. If the naming of variations is inconsistent, the sorting order might appear illogical and confusing.
### Create item size and color variations using a variation name
To add item variations to a catalog, create a `CatalogItem` instance with a list of `CatalogItemVariation` instances nested within the item through the `variations` attribute on the `CatalogItem` object. A variation is created for each combination of color and size.
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The request results in a `CatalogItem` instance with nine `CatalogItemVariation` instances nested within.
```json
{
"catalog_object": {
"type": "ITEM",
"id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Shirt",
"description": "Shirt",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "F3P54C436KUEUGMRCUFYBEIZ",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Red, Large",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "IJBAQDICELYUAUTHM352X3AI",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Red, Medium",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "5JMHD2SBPVG3A7ZFN5HDXSY6",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Red, Small",
"ordinal": 2,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "FQZGFI5ZQZY4RYK3H5X3QG2X",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Blue, Large",
"ordinal": 3,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "6F4K33KPNUVDWKZ43KUIFH6K",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Blue, Medium",
"ordinal": 4,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "H6QGZ6Q3XBEIL672DZYQW5SH",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Blue, Small",
"ordinal": 5,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "FQZGFI5ZQZY4RYK3H5X3QG2X",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Green, Large",
"ordinal": 3,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "6F4K33KPNUVDWKZ43KUIFH6K",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Green, Medium",
"ordinal": 4,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "H6QGZ6Q3XBEIL672DZYQW5SH",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Polo shirt, Green, Small",
"ordinal": 5,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
}
}
}
],
"product_type": "REGULAR"
}
},
"id_mappings": [
{
"client_object_id": "#shirt",
"object_id": "3RJ4KVW64QXHXYDJ5CS6J4LE"
},
{
"client_object_id": "#shirt_small_red",
"object_id": "F3P54C436KUEUGMRCUFYBEIZ"
},
{
"client_object_id": "#shirt_medium_red",
"object_id": "IJBAQDICELYUAUTHM352X3AI"
},
{
"client_object_id": "#shirt_large_red",
"object_id": "5JMHD2SBPVG3A7ZFN5HDXSY6"
},
{
"client_object_id": "#shirt_small_blue",
"object_id": "FQZGFI5ZQZY4RYK3H5X3QG2X"
},
{
"client_object_id": "#shirt_medium_blue",
"object_id": "6F4K33KPNUVDWKZ43KUIFH6K"
},
{
"client_object_id": "#shirt_large_blue",
"object_id": "H6QGZ6Q3XBEIL672DZYQW5SH"
},
{
"client_object_id": "#shirt_small_greeen",
"object_id": "FQZGFI5ZQZY4RYK3H5X3QG2X"
},
{
"client_object_id": "#shirt_medium_green",
"object_id": "6F4K33KPNUVDWKZ43KUIFH6K"
},
{
"client_object_id": "#shirt_large_green",
"object_id": "H6QGZ6Q3XBEIL672DZYQW5SH"
}
]
}
```
{% /tab %}
{% /tabset %}
{% anchor id="option-strategy" /%}
## Item option strategy
Continuing with the polo shirt example, a "Polo shirt" variation must have a color and size because the parent "Shirt" item was defined with these options. The possible values for these variation options are taken from the "Shirt" item definition.
Keep in mind that because "Polo shirt" and "Club shirt" are variations of "Shirt", they're restricted to the same option values. If the seller later receives teal polo shirts, they must add "Teal" to the color option set. Prices can be set for each variation, allowing for different styles to have distinct prices. For example, a "Shirt" item with "Polo shirt" and "Club shirt" variations can have the "Polo shirt" priced at $35 and the "Club shirt" at $45.
### Get existing item options
A seller might have already created a set of standard item options in the Square Dashboard. Before creating new options, you should see whether the option you need is already available.
{% tabset %}
{% tab id="Request" %}
The following request looks for an existing color item option by querying for item options whose name includes "Color":
````
{% /tab %}
{% tab id="Response" %}
The following response shows that a seller has already created a standard set of colors:
```json
{
"objects": [
{
"type": "ITEM_OPTION",
"id": "6J4XYMEIZR5KKTE6SRF7KBLJ",
"updated_at": "2024-11-18T23:55:09.446Z",
"created_at": "2021-10-19T22:40:12.165Z",
"version": 1731974109446,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_data": {
"name": "Color",
"display_name": "Color",
"show_colors": false,
"values": [
{
"type": "ITEM_OPTION_VAL",
"id": "YXJJJB2AKABUSBTSXYJJ7ZYN",
"version": 1731623376831,
"item_option_value_data": {
"item_option_id": "6J4XYMEIZR5KKTE6SRF7KBLJ",
"name": "Red",
"ordinal": 6
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "6GGHS6YHE6VXPLNYWTLVLICD",
"version": 1731623376831,
"item_option_value_data": {
"item_option_id": "6J4XYMEIZR5KKTE6SRF7KBLJ",
"name": "Blue",
"ordinal": 7
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "KAHGO4JHH2UUVKZOE4BIPL4M",
"version": 1731623376831,
"item_option_value_data": {
"item_option_id": "6J4XYMEIZR5KKTE6SRF7KBLJ",
"name": "Yellow",
"ordinal": 8
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "CI3RA2SRJB2YEDSP7MOXHTLV",
"version": 1731974109446,
"item_option_value_data": {
"item_option_id": "6J4XYMEIZR5KKTE6SRF7KBLJ",
"name": "Purple",
"ordinal": 9
}
}
]
}
}
],
"latest_time": "2024-11-18T23:55:47.187Z"
}
```
Your application might need to modify item options to update the set of values within each option set. There are no restrictions to updating item options. To make an update, call [UpsertCatalogObject](https://developer.squareup.com/reference/square/catalog-api/upsert-catalog-object) and provide the complete set of new and updated values.
{% /tab %}
{% /tabset %}
### Generated item variations
Your application can create the `CatalogItem`, `CatalogItemOption` objects, and `CatalogVariations` objects with a single `BatchCatalogUpsert` call.
To simplify the following examples, the options are limited to "color" and "size", while the `CatalogItemOption` for "Style" is omitted. Additionally, the `CatalogItem` name is updated to "Polo Shirt" for clarity and specificity, replacing the more generic "Shirt".
### Create item size and color variations using item options
The following example shows how to create item options similar to the previous example.
The process starts by using `BatchUpsertCatalogObject` to create two `CatalogItemOption` objects. A `CatalogItem` is then created with nine `CatalogItemVariation` objects nested within it. Each `CatalogItemVariation` has two item option values attached, which specify the colors (red, blue, and yellow) and sizes (small, medium, and large).
{% tabset %}
{% tab id="Request" %}
````
Item option values are linked to an item variation by referencing the corresponding `item_option_ids` and `item_option_value_ids` in the `item_option_values` attribute of the item variation. This ensures that each variation is accurately associated with its specific options and values.
{% /tab %}
{% tab id="Response" %}
The request results in the creation of:
* Two item options (of `CatalogItemOption`): one for size and one for color.
* One item (of `CatalogItem`).
* Nine item variations (of `CatalogItemVariation`) nested within the item. Each item variation references the size and color options by the corresponding item option value IDs defined in the two item option objects, respectively.
```json
{
"objects": [
{
"type": "ITEM_OPTION",
"id": "GYWZZUMPQGBNMBANC32WWSWC",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_data": {
"name": "COLOR_OPTIONS",
"values": [
{
"type": "ITEM_OPTION_VAL",
"id": "O7XQMPXSMFSGUSATAGARGX3E",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"name": "RED",
"ordinal": 0
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "W55IT3LUEQI62LTLXOPLXYEL",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"name": "Blue",
"ordinal": 1
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "ZZ5IT3LUEQI62LTLXOPLXYEL",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "ZZWZZUMPQGBNMBANC32WWSWC",
"name": "Yellow",
"ordinal": 2
}
}
]
}
},
{
"type": "ITEM_OPTION",
"id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_data": {
"name": "SIZE_OPTIONS",
"values": [
{
"type": "ITEM_OPTION_VAL",
"id": "O55AQ6U4HFWDAIPHFHURPMEA",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"name": "Small",
"ordinal": 0
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "RJI7UGDMDVOHBEQJSASTWOOJ",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"name": "Medium",
"ordinal": 1
}
},
{
"type": "ITEM_OPTION_VAL",
"id": "56QF4FR2BC2D67K4QJ2U2KYC",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_option_value_data": {
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"name": "Large",
"ordinal": 2
}
}
]
}
},
{
"type": "ITEM",
"id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Polo Shirt",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "6PRFCYBKD7QNDERVZP5FBDL7",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, RED",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "SOQTNT7336QXGHI3YK7ZZQ6O",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, Blue",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "SOQTNT7336QXGHI3YK7ZZQ6O",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, Yellow",
"ordinal": 2,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "ZZWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "ZZ5IT3LUEQI62LTLXOPLXYEL"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "KI66FNZXAEGEPE42J2PPX6AJ",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Medium, RED",
"ordinal": 3,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "RHSUAWEXGNTQNQA55KNEYXOO",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Medium, Blue",
"ordinal": 4,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "RHSUAWEXGNTQNQA55KNEYXOO",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Medium, Yellow",
"ordinal": 5,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
},
{
"item_option_id": "ZZWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "ZZ5IT3LUEQI62LTLXOPLXYEL"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Large, RED",
"ordinal": 6,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "GBUW47ZH7I7PZI6E5XCWPLGD",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Large, Blue",
"ordinal": 7,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "GBUW47ZH7I7PZI6E5XCWPLGD",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Large, Yellow",
"ordinal": 8,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
},
{
"item_option_id": "ZZWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "ZZ5IT3LUEQI62LTLXOPLXYEL"
}
]
}
}
],
"product_type": "REGULAR",
"item_options": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC"
}
]
}
}
],
"id_mappings": [
{
"client_object_id": "#item_option_color",
"object_id": "GYWZZUMPQGBNMBANC32WWSWC"
},
{
"client_object_id": "#item_option_size",
"object_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
},
{
"client_object_id": "#item",
"object_id": "EQVBSUZZ65RO2WWPFU6PLYWU"
},
{
"client_object_id": "#item_option_value_color_red",
"object_id": "O7XQMPXSMFSGUSATAGARGX3E"
},
{
"client_object_id": "#item_option_value_color_blue",
"object_id": "W55IT3LUEQI62LTLXOPLXYEL"
},
{
"client_object_id": "#item_option_value_color_yellow",
"object_id": "ZZ5IT3LUEQI62LTLXOPLXYEL"
},
{
"client_object_id": "#item_option_value_size_small",
"object_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"client_object_id": "#item_option_value_size_medium",
"object_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
},
{
"client_object_id": "#item_option_value_size_large",
"object_id": "56QF4FR2BC2D67K4QJ2U2KYC"
},
{
"client_object_id": "#item_variation_small_red",
"object_id": "6PRFCYBKD7QNDERVZP5FBDL7"
},
{
"client_object_id": "#item_variation_medium_red",
"object_id": "KI66FNZXAEGEPE42J2PPX6AJ"
},
{
"client_object_id": "#item_variation_large_red",
"object_id": "AY6GSOG4ZZTYJ6RJPU2F4O6I"
},
{
"client_object_id": "#item_variation_small_blue",
"object_id": "SOQTNT7336QXGHI3YK7ZZQ6O"
},
{
"client_object_id": "#item_variation_medium_blue",
"object_id": "RHSUAWEXGNTQNQA55KNEYXOO"
},
{
"client_object_id": "#item_variation_large_blue",
"object_id": "GBUW47ZH7I7PZI6E5XCWPLGD"
},
{
"client_object_id": "#item_variation_small_yellow",
"object_id": "SOQTNT7336QXGHI3YK7ZZQ6O"
},
{
"client_object_id": "#item_variation_medium_yellow",
"object_id": "RHSUAWEXGNTQNQA55KNEYXOO"
},
{
"client_object_id": "#item_variation_large_yellow",
"object_id": "GBUW47ZH7I7PZI6E5XCWPLGD"
}
]
}
```
Notice that the `name` and `ordinal` attributes of an item variation are no longer set in the request. They're set on the item options. Don't set the `name` and `ordinal` attributes on the item variation when using an item option value. The `ordinal` number shown in the response is computed as the matrix element position.
{% /tab %}
{% /tabset %}
## Search for item variations with or without item options
When an item option is used in an item variation, the display order is determined by the sequence of the associated item option values. The display name for an item variation is created by combining the names of these option values. You must manage the name and order of an item variation through the item option.
If you're not using item options, you can still manage the name and order directly on the item variations. Other attributes, such inventory counts and SKU, are maintained at the item variation level, regardless of whether item options are used.
{% anchor id="option-query" /%}
### Search for item variations using item options
The following example searches for the small and red item variation with item options defining the size and color. Notice that the item option values (`Small` and `RED`) are referred to by the respective item option value IDs (`item_option_value_ids`).
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
The request returns a successful response similar to the following. Because the request used the `item_variations_for_item_option_values_query` filter, only the matched item variations are returned.
```json
{
"objects": [
{
"type": "ITEM_VARIATION",
"id": "6PRFCYBKD7QNDERVZP5FBDL7",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, RED",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
}
],
"latest_time": "2020-10-17T04:44:20.494Z"
}
```
{% /tab %}
{% /tabset %}
{% tabset %}
{% tab id="Request" %}
To specify the `RED` option value in the search query, set the `RED` item option value ID (`O7XQMPXSMFSGUSATAGARGX3E`) on the `item_variation_for_item_option_values_query` filter.
````
{% /tab %}
{% tab id="Response" %}
The successful response includes three item variations including the `RED` item options: `Small, RED`, `Medium, RED`, and `Large, RED` item variations.
```json
{
"objects": [
{
"type": "ITEM_VARIATION",
"id": "6PRFCYBKD7QNDERVZP5FBDL7",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, RED",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "KI66FNZXAEGEPE42J2PPX6AJ",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Medium, RED",
"ordinal": 2,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3000,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Large, RED",
"ordinal": 4,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 3500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
}
],
"latest_time": "2020-10-17T04:44:20.494Z"
}
```
{% /tab %}
{% /tabset %}
{% anchor id="text-query" /%}
### Search for item variations by attribute name
The Catalog API supports various query filters to search for catalog objects. The `name` attribute is one of the searchable attributes.
The following cURL example illustrates how to search for item variations with `"small red shirt"` or `"small red"` set on their names:
{% tabset %}
{% tab id="Request" %}
````
Instead of using the `"Small red shirt"` phrase as a single element of the `keywords` list, you can specify a three-element list in the `text_query` expression as shown. The result is the same.
````
{% /tab %}
{% tab id="Response" %}
In the example catalog, there's only one item variation with the `name` of `"Small red shirt"`. The successful response returns this object for the match.
```json
{
"objects": [
{
"type": "ITEM_VARIATION",
"id": "F3P54C436KUEUGMRCUFYBEIZ",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Small red shirt",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
}
}
}
],
"latest_time": "2020-10-17T04:44:20.494Z"
}
```
{% /tab %}
{% /tabset %}
#### Less specific text query
This query example uses only keywords that are common to multiple item variations, regardless of whether the variations were defined with item options.
In the example catalog, there's an item variation (named `Small red shirt`) without item options and another item variation (named `Small, RED`) with item option values defining the size and color. As a result, this request returns both for the match.
{% tabset %}
{% tab id="Request" %}
````
The order of the query expression list doesn't matter and punctuations are ignored.
{% /tab %}
{% tab id="Response" %}
```json
{
"objects": [
{
"type": "ITEM_VARIATION",
"id": "F3P54C436KUEUGMRCUFYBEIZ",
"updated_at": "2020-10-17T00:08:15.13Z",
"version": 1602893295130,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
"name": "Small red shirt",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "6PRFCYBKD7QNDERVZP5FBDL7",
"updated_at": "2020-10-17T04:44:20.494Z",
"version": 1602909860494,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
"name": "Small, RED",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 2500,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
"item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
},
{
"item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
"item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
}
]
}
}
],
"latest_time": "2020-10-17T04:44:20.494Z"
}
```
{% /tab %}
{% /tabset %}
---
# Synchronize a Catalog with an External Platform
> Source: https://developer.squareup.com/docs/catalog-api/sync-with-external-system
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn about using the Square API to synchronize an external platform with a Square catalog.
**Applies to:** [Catalog API](catalog-api/what-it-does) | [Subscriptions API](subscriptions/overview)
{% subheading %}Learn about using the Square API to synchronize an external platform with a Square catalog.{% /subheading %}
{% toc hide=true /%}
## Overview
When a seller's catalog exists in the Square Developer platform under their Square account and a duplicate catalog exists in an external platform, the two catalogs should be periodically synchronized to maintain parity. For example, a seller uses an enterprise resource planning (ERP) system to keep a catalog for functions such as cost accounting, inventory, or sales through another channel. The seller uses the catalog in Square Point of Sale to complete item purchases and process payments in a physical retail location.
{% aside type="tip" %}
A seller's catalog is the source of the Square Dashboard item library and for items shown in Square Point of Sale.
{% /aside %}
You need to know which platform hosts the master ("source of truth") catalog. Changes should be synchronized from the master catalog to the catalog in the other platform.
### Use reference IDs
Regardless of whether the Square platform hosts the seller's master catalog or the external system does, you should store the ID of the external item with the Square `CatalogObject` and the `ID` of the Square `CatalogObject` in its equivalent object in the external catalog. A good place to store the external ID is as a `custom_attribute_values` ([CatalogCustomAttributeValue](https://developer.squareup.com/reference/square/objects/CatalogCustomAttributeValue)) property value. For information about using catalog custom attributes, see [Add Custom Attributes](catalog-api/add-custom-attributes).
### Source of catalog updates
Catalog objects can be inserted, changed, or deleted by sellers in the Square Dashboard item library or from Square Point of Sale. These updates can also be made from any other catalog integration that a seller is using. Your sync logic needs to catch any updates made to the catalog, regardless of the source of the update.
## Sync from Square to an external platform
To sync to an external platform, your application periodically gets changes to the catalog in a Square account and writes them to the external platform. There are a couple of useful strategies to drive the periodic catalog reads:
* **On notification of a change** - Use [catalog.version.updated](https://developer.squareup.com/reference/square/catalog-api/webhooks/catalog.version.updated) to trigger a sync. The event provides the timestamp of a catalog update. Make a [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) request with the [begin_time](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects#request__property-begin_time) request property set to the previous event timestamp.
* **Regular interval polling** - On a set time interval, make a [SearchCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects) request with the [begin_time](https://developer.squareup.com/reference/square/catalog-api/search-catalog-objects#request__property-begin_time) request property set to the previous interval timestamp.
Both strategies use the `begin_time` property of `SearchCatalogObjects` to return only `Catalog` objects that have been updated after the time you set in the search request. The results of the search request include only the objects that you're interested in. For `Catalog` objects returned in the result, you need to push the new objects or updates to the external platform.
{% aside type="warning" %}
Whichever strategy you use, don't call [ListCatalog](https://developer.squareup.com/reference/square/catalog-api/list-catalog) on interval or event unless you're listing for the current catalog version number and limiting the scope of object types. Otherwise, your result set can be very large and subject your application to rate limiting.
{% /aside %}
## Sync on notification of a change
Synchronize when this webhook event is fired. It's fired once for every [UpsertCatalogObject](https://developer.squareup.com/reference/square/catalog-api/upsert-catalog-object), [DeleteCatalogObject](https://developer.squareup.com/reference/square/catalog-api/delete-catalog-object), [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/batch-upsert-catalog-objects), or [BatchDeleteCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/batch-delete-catalog-objects) API call.
{% aside type="info" %}
Deleted `Catalog` objects are returned in future `SearchCatalogObjects` responses. Such an object has an `is_deleted` property whose value is `true`. For more information about deleting `Catalog` objects, see [Delete Catalog Objects and Query Deleted Objects](catalog-api/delete-catalog-objects).
{% /aside %}
Insert, update, and delete operations trigger the generation of a new catalog version number, which is then assigned to every inserted, updated, or deleted object. In a given `catalog.version.updated` webhook event, `object.catalog_version.updated_at` gives the timestamp for the creation of that new version. If you call `SearchCatalogOjbects` with that timestamp, you get all updates completed after the version increment event. To get the object updates that triggered the webhook, you should use the `updated_at` timestamp for the previous webhook event.
### BatchUpsertCatalogObjects benefits
A positive side-effect of using `BatchUpsertCatalogObjects` instead of making a single object update with `UpsertCatalogObject` is that you receive a single webhook notification for all batches in the batch request. Because `BatchUpsertCatalogObjects` accepts up to 10,000 objects to be added or updated, it results in one webhook event rather than thousands. Batch delete operations have the same benefit.
### Webhook usage example
To get all `Catalog` object changes since the last time you synced, you need two things:
1. **The timestamp of your previous sync** - This timestamp should be the moment the previous catalog version was set. The timestamp is provided in the previous webhook event (`object.catalog_version.updated_at`).
2. **A new webhook notification** - This webhook tells you that the catalog has changed and that there's a new version.
The timestamp marks the start of a time range in which new catalog changes were made. The `SearchCatalogObjects` request takes that date (the date of your last sync) as the `begin_time` property of the request. When you make the search request, you're asking Square to return all catalog changes since the last sync. The response carries all changes from then to the moment you make the search request.
You can further scope the `SearchCatalogObjects` request to only those catalog types that you're syncing. For example, the external platform might only store items and variations. It might not store discounts, pricing rules, taxes, or other catalog types. In this case, add a search clause like the following example:
```json
"object_types": [
"ITEM",
"ITEM_VARIATION"
]
```
### Trigger sync with a webhook
Complete the following steps to start syncing a catalog from Square to an external system by using Square webhook notifications:
1. [Subscribe](webhooks/step2subscribe) to [catalog.version.updated](https://developer.squareup.com/reference/square/catalog-api/webhooks/catalog.version.updated) using the Developer Console or [subscribe](webhooks/webhook-subscriptions-api) programmatically with the Subscriptions API.
1. Make a full copy of the master catalog in the target platform.
3. Cache an arbitrary start date. Usually this is the date the target catalog is created.
4. Handle the next `catalog.version.updated` webhook event.
1. Call `SearchCatalogObjects` with the cached date.
1. Replace the cached date with the value of `object.catalog_version.updated_at`.
1. Parse the response to `SearchCatalogObjects`, which has all Square catalog changes since the last sync (or initial copy).
2. Sync updates to the external platform.
The following object is the body of a `catalog.version.updated` webhook event payload. Note the `object.catalog_version.updated_at` property.
```json
{
"merchant_id": "S1JEG5YR89KNM",
"type": "catalog.version.updated",
"event_id": "ce50c3de-7f60-36e6-af1f-21b9867f6f4d",
"created_at": "2024-10-02T21:36:39.343216712Z",
"data": {
"type": "catalog_version",
"id": "",
"object": {
"catalog_version": {
"updated_at": "2024-10-02T21:36:36.932Z"
}
}
}
}
```
The following example shows the use of a webhook timestamp to get all catalog updates after the catalog version was incremented:
{% tabset %}
{% tab id="Request" %}
To request all `Catalog` objects that have changed after the previous webhook event (`2024-10-02T21:31:36.932Z`) , make a `SearchCatalogOjbects` request like the following example:
````
{% /tab %}
{% tab id="Response" %}
The response shows that the only catalog update was a `CatalogItem` that was updated because its `CatalogItemVariation` with ID `UD3CZNICTRKB35IWY36ARVHT` was deleted after `2024-10-02T21:31:36.932Z`. You should also delete that object in the external platform.
```json
{
"objects": [
{
"type": "ITEM",
"id": "BD4FDFQQOMVOIIVW67F3AUYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-04-09T20:59:24.983Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Muffin",
"description": "Plump homemade muffins",
"abbreviation": "MUFF",
"is_taxable": true,
"variations": [
{
"type": "ITEM_VARIATION",
"id": "6U4CAIYCXVZO6NZYTBGKPXYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-10-02T21:36:37.081Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
}
],
"product_type": "REGULAR",
"description_html": "Plump homemade muffins
",
"description_plaintext": "Plump homemade muffins",
"is_archived": false
}
},
{
"type": "ITEM_VARIATION",
"id": "UD3CZNICTRKB35IWY36ARVHT",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-04-09T20:59:24.983Z",
"version": 1727904996932,
"is_deleted": true,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
},
{
"type": "ITEM_VARIATION",
"id": "6U4CAIYCXVZO6NZYTBGKPXYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-10-02T21:36:37.081Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
}
],
"latest_time": "2024-10-02T21:36:36.932Z"
}
```
{% /tab %}
{% /tabset %}
## Sync on regular interval polling
Polling replaces the non-deterministic webhook event trigger with a regular cadence that you establish in your application. For example, you can set a chron job to fire an event every 15 minutes to get all catalog updates made since the last time a chron event fired.
### Trigger sync from your chron job
Complete following steps to start syncing a catalog from Square to an external system by using a timer that you add to your application backend:
1. Make a full copy of the master catalog in the target platform.
3. Cache an arbitrary start date. Usually this is the date the target catalog is created.
4. Start your chron job.
5. When a chron event fires:
1. Call `SearchCatalogObjects` with the cached date,
1. Replace the cached date with the timestamp of the chron event.
1. Parse the response to `SearchCatalogObjects`, which has all Square catalog changes since the initial copy.
The following example shows the use of a chron event timestamp to get all catalog updates after the catalog version was incremented:
{% tabset %}
{% tab id="Request" %}
To request all `Catalog` objects that have changed after the previous chron event (`2024-10-02T21:31:36.932Z`) , make a `SearchCatalogOjbects` request like this request.
````
{% /tab %}
{% tab id="Response" %}
The response shows that the only catalog update was a `CatalogItem` that was updated because its `CatalogItemVariation` with ID `UD3CZNICTRKB35IWY36ARVHT` was deleted after `2024-10-02T21:31:36.932Z`.
```json
{
"objects": [
{
"type": "ITEM",
"id": "BD4FDFQQOMVOIIVW67F3AUYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-04-09T20:59:24.983Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Muffin",
"description": "Plump homemade muffins",
"abbreviation": "MUFF",
"is_taxable": true,
"variations": [
{
"type": "ITEM_VARIATION",
"id": "6U4CAIYCXVZO6NZYTBGKPXYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-10-02T21:36:37.081Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
}
],
"product_type": "REGULAR",
"description_html": "Plump homemade muffins
",
"description_plaintext": "Plump homemade muffins",
"is_archived": false
}
},
{
"type": "ITEM_VARIATION",
"id": "UD3CZNICTRKB35IWY36ARVHT",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-04-09T20:59:24.983Z",
"version": 1727904996932,
"is_deleted": true,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
},
{
"type": "ITEM_VARIATION",
"id": "6U4CAIYCXVZO6NZYTBGKPXYN",
"updated_at": "2024-10-02T21:36:36.932Z",
"created_at": "2024-10-02T21:36:37.081Z",
"version": 1727904996932,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BD4FDFQQOMVOIIVW67F3AUYN",
"name": "Regular",
"ordinal": 0,
"pricing_type": "VARIABLE_PRICING",
"sellable": true,
"stockable": true
}
}
],
"latest_time": "2024-10-02T21:36:36.932Z"
}
```
{% /tab %}
{% /tabset %}
## Sync from an external platform to Square
Syncing from an external platform to Square applies where the external platform hosts the master catalog.
Using whatever mechanism is appropriate for the external platform that your application supports, you parse any external updates and push them into the catalog in the seller's Square account by using [UpsertCatalogObject](https://developer.squareup.com/reference/square/catalog-api/upsert-catalog-object), [DeleteCatalogObject](https://developer.squareup.com/reference/square/catalog-api/delete-catalog-object), [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/batch-upsert-catalog-objects), or [BatchDeleteCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/batch-delete-catalog-objects) API calls.
It's a good idea to group like operations so you can call the Catalog API batch endpoints and reduce the number of API calls you make. For example, you can pull all the delete operations into a single [BatchDeleteCatalogObjects](https://developer.squareup.com/reference/square/catalog-api/batch-delete-catalog-objects) API call.
For each `Catalog` object that exists in both platforms, apply the external update by first retrieving the Square `Catalog` object by the `CatalogObject` ID that you stored in the external platform. For information about retrieving a `Catalog` object by ID, see [Retrieve a catalog object with a specified ID and catalog version](catalog-api/retrieve-catalog-objects#retrieve-a-catalog-object-with-a-specified-id-and-catalog-version).
To learn about updating existing Square `Catalog` objects with changes to the same object in an external platform, see [Update Catalog Objects](catalog-api/update-catalog-objects).
If an external catalog item is deleted, call [DeleteCatalogObject](https://developer.squareup.com/reference/square/catalog-api/delete-catalog-object).
### Verify updates
You can verify updates synchronously by catching the response to upsert or delete requests. If you get a `200` response, that means the catalog change succeeded. You can parse the call response to verify if necessary.
If you want to run verification in a webhook listener process, you can use the webhook events generated by the Catalog API operations. You need to provide a timestamp representing your first Catalog API call to that verify process.
To process verifications triggered by webhook events, first [subscribe](webhooks/step2subscribe) to [catalog.version.updated](https://developer.squareup.com/reference/square/catalog-api/webhooks/catalog.version.updated) using the Developer Console or [subscribe](webhooks/webhook-subscriptions-api) programmatically with the Subscriptions API. The webhook listener you use needs to be running before you make your first Catalog API call to push updates.
## Bi-directional syncing
Bi-directional catalog synchronization can be difficult to implement because of the large number of endpoints involved in both systems. `Catalog` object updates in either system result in risky operations such as:
* **CRUD operations** - Risks arise from concurrency, merging, duplication, and deletion issues if both systems have CRUD operations around the same time.
* **Price changes** - An accounting integrity risk can arise from a user on either system inadvertently updating the other system. For example, a Square user updates the POS price, which then updates the online price in the other system with that new price. A seller might intend for item prices to be different across sales channels.
If your application must address a bi-directional use case, you need to account for these side-effects, which are beyond the scope of this topic. However, you can use the preceding sections to understand the mechanisms you can use to build either direction of your use case.
---
# Process an Unlinked Refund
> Source: https://developer.squareup.com/docs/refunds-api/unlinked-refunds
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to process unlinked refunds with Refunds API.
**Applies to:** [Refunds API](refunds-api/overview) | [Web Payments SDK](web-payments/overview)
{% subheading %} Learn how to process unlinked refunds with the Refunds API.{% /subheading %}
{% toc hide=true /%}
## Overview
An unlinked refund isn't linked to a Square payment and has no associated payment ID. Use an unlinked refund when there's no Square payment to link to (such as when the original payment was processed by another payment processor).
## Requirements and limitations
The ability to process an unlinked refund has the following limitations:
* Unlinked refunds aren't supported in Japan.
* Refunds cannot be processed by a Square account that hasn't been enabled for payment processing.
* The unlinked refund feature is only available for sellers who've been authorized to use it. A seller using your application needs to contact their Square account manager for authorization. When authorized, all of the seller's locations can take unlinked refunds.
The following example is the `400` response that your application receives if used by a seller who isn't authorized to make unlinked refunds:
```json
{
"errors": [
{
"code": "BAD_REQUEST",
"detail": "Unlinked refund processing is not enabled for this merchant.",
"category": "INVALID_REQUEST_ERROR"
}
]
}
```
### Refund a non-Square payment
Non-Square payments exist when a seller is transitioning their payment processing from another service to Square. During the transition period, the seller might want to issue a refund through Square for a payment taken before they started with Square. The refund request is unlinked because there's no Square `Payment` object to represent the original payment.
This unlinked refund is processed the same way as a standard refund. The seller's Square account is the source of the funds for the refund. If there are insufficient funds in the seller's Square account, the seller's linked bank account is the refund's source.
## Create an unlinked refund
Use the `RefundPayment` endpoint to process an unlinked refund to a card. In the request, don't provide a payment ID. Instead, provide values for the following unlinked refund types before processing the refund.
### Create an unlinked refund to a card
Add the following values to the `RefundPayment` request for the card refund:
* `destination_id` - Identifies the refund destination by setting the value to a payment card (or Square gift card) token or card-on-file ID. Specify one of the following:
* A payment token.
* A Square gift card or card-on-file ID.
* `location_id` - Where the refund occurred.
* `customer_id` - Required for card-on-file destinations.
* `unlinked` - Must be `true`.
A payment token is generated by your application using the [Web Payments SDK](web-payments/overview). When testing, use a [Sandbox test](devtools/sandbox/payments#payment-tokens-for-testing-payments-api) token such as `cnon:card-nonce-ok`.
The following `RefundPayment` request specifies a test payment card on file that Square provides for [Sandbox testing](devtools/sandbox/payments#payment-tokens-for-testing-payments-api). You can test the same request with any of the card test values that Square provides.
````
After receiving the request, Square processes the refund and returns money to the buyer. In response, Square returns a `Refund` object, as shown in the following example:
```json
{
"refund": {
"id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
"status": "PENDING",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
"created_at": "2022-09-24T21:08:06.847Z",
"updated_at": "2022-09-24T21:08:06.856Z",
"location_id": "S8GWD5R9QB376",
"reason": "Buyer returned goods",
"unlinked": true,
"destination_type": "CARD",
"destination_details": {
"card_details": {
"card": {
"card_brand": "MASTERCARD",
"last_4": "6952",
"exp_month": 12,
"exp_year": 2028,
"fingerprint": "sq-1-HVUCWbGnS2LZ...E8Gkh_EtOTe0A",
"card_type": "CREDIT",
"bin": "512081"
},
"entry_method": "ON_FILE"
}
}
}
}
```
The `order_id` in this example is the unlinked return order ID. Square creates a refund order while processing the refund request and returns the new order ID in this response.
The `destination_details` field contains the details of the refund destination. Card refunds have a `card_details` field, which contains the refund destination's payment card details that you can use to confirm with the buyer that the funds were refunded to the intended card.
### Create a cash unlinked refund
Add the following values to the `RefundPayment` request for the cash refund:
* `destination_id` - Must be `CASH`.
* `location_id` - Where the refund occurred.
* `unlinked` - Must be `true`.
* `cash_details` - Must include the amount of cash the seller provided as `seller_supplied_money`.
The following is an example `RefundPayment` request:
````
After receiving the request, Square makes a record of the refund and returns a `Refund` object, as shown in the following example:
```json
{
"refund": {
"id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
"status": "PENDING",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
"created_at": "2024-10-17T21:08:06.847Z",
"updated_at": "2024-10-17T21:08:06.856Z",
"location_id": "{LOCATION_ID}",
"reason": "Buyer returned goods",
"unlinked": true,
"destination_type": "CASH",
"destination_details": {
"cash_details": {
"seller_supplied_money": {
"amount": 1000,
"currency": "USD"
},
"change_back_money": {
"amount": 0,
"currency": "USD"
}
}
}
}
}
```
### Create an unlinked refund to an external source
Add the following values to the `RefundPayment` request for the external refund:
* `destination_id` - Must be `EXTERNAL`.
* `location_id` - Where the refund occurred.
* `unlinked` - Must be `true`.
* `external_details` - Must include:
* source - A description of the external refund source.
* type - See [accepted options](https://developer.squareup.com/reference/square/refunds-api/refund-payment#request__property-external_details).
The following is an example `RefundPayment` request:
````
After receiving the request, Square makes a record of the refund and returns a `Refund` object, as shown in the following example:
```json
{
"refund": {
"id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
"status": "PENDING",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
"created_at": "2024-10-17T21:08:06.847Z",
"updated_at": "2024-10-17T21:08:06.856Z",
"location_id": "{LOCATION_ID}",
"reason": "Buyer returned goods",
"unlinked": true,
"destination_type": "EXTERNAL",
"destination_details": {
"external_details": {
"type": “OTHER”,
"source": "Food Delivery Service"
}
}
}
}
```
---
# Order Service Charges
> Source: https://developer.squareup.com/docs/orders-api/service-charges
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to add service charges to an order using the Orders API.
**Applies to:** [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to apply service charges to an order using the Orders API.{% /subheading %}
{% toc hide=true /%}
## Overview
Building on the example order created in [Order Price Adjustments](orders-api/price-adjustments), learn how the calculation phases you set on an order affect service charges applied to an order.
Square calculates and applies any discounts on the order before service charges are applied. After discounted prices are applied to the order, service charges are applied. Service charges are scoped as follows:
* **Based on the total amount of the order** - If the service charge will be taxed, it's applied before taxes are calculated.
* **Apportioned based on the individual items in the order** - The apportioned charge is based on a percentage or a fixed amount.
## Calculation phases
The time that the service charge calculation happens is a calculation phase. The Orders API supports any of four calculation phases for a service charge:
* **Subtotal phase** - The service charge is calculated before taxes.
* **Total phase** - The service charge is calculated after taxes.
* **Apportioned amount phase** - The service charge is calculated after any percentage-based apportioned service charges and before taxes.
* **Apportioned percentage phase** - The service charge is calculated before any amount-based apportioned service charges and taxes.
### Phase limitations
Each calculation phase is intended to work with only certain types of service charges. When a given phase is used in the wrong type of charge, your application receives a `400 BAD_REQUEST` response.
**Subtotal phase service charge** - Cannot be used on an order in the following condition:
* The service charge is applied at the order line-item level.
**Total phase service charge** - Cannot be used on an order in the following conditions:
* The service charge is taxable.
* The service charge is applied at the order line-item level.
**Apportioned amount phase service charge** - Cannot be used on an order in the following conditions:
* The [treatment_type](https://developer.squareup.com/reference/square/objects/OrderServiceCharge#definition__property-treatment_type) of the service charge is `LINE_ITEM_TREATMENT`.
* The service charge has a percentage amount instead of an amount.
**Apportioned percentage phase service charge** - Cannot be used on an order in the following conditions:
* The [treatment_type](https://developer.squareup.com/reference/square/objects/OrderServiceCharge#definition__property-treatment_type) of the service charge is `LINE_ITEM_TREATMENT`.
* The service charge has a dollar amount instead of a percentage.
{% aside type="important" %}
Apportioned service charges aren't accounted for in the `line_item.gross_sales_money` attribute. If your sales report includes service charges in line-item totals, report on the `total_money` attribute instead of `gross_sales_money`.
{% /aside %}
## Apportioned amount service charge
An apportioned amount service charge adds a portion of the total service charge to line items in the order. If the `service_charges[].scope` is set to `ORDER`, a portion of the service charge is applied to every line. If the scope is set to `LINE_ITEM`, only those line items where the service charge is applied get a portion of the service charge.
Suppose the total service charge on an order is $10 and the order subtotal is $116 for the three line items. $10 needs to be apportioned across all line items using the following calculation:
* `Dog Biscuits - Chicken Flavor`: ((2 @ $15 per box = $30) / $116) * 10 = $2.59
* `Handmade Sweater - Blue`: (($50) / $116) * 10 = $4.31
* `Chewy Rawhide - Beef Flavor`: ((3 @ $12 per box = $30) / $116) * 10 = $3.10
{% line-break /%}
{% tabset %}
{% tab id="Request" %}
The following example request specifies the $10 apportioned amount service charge and the three line items:
````
{% /tab %}
{% tab id="Response" %}
The following response shows that the three apportioned line-item service charges total the $10 total service charge:
```json
{
"order": {
"location_id": "VJN4XSBFTVPK9",
"line_items": [
{
"uid": "uFptr9GfXbBTuKMJRQJdGB",
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 3259,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 3000,
"currency": "USD"
},
"item_type": "ITEM",
"applied_service_charges": [
{
"uid": "PlbvFDyMySGH4FXicgOEyD",
"service_charge_uid": "SVS_CHARGE1",
"applied_money": {
"amount": 259,
"currency": "USD"
}
}
],
"total_service_charge_money": {
"amount": 259,
"currency": "USD"
}
},
{
"uid": "PCi6xxwOBo8Y1fzGEOBl8",
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5431,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 5000,
"currency": "USD"
},
"item_type": "ITEM",
"applied_service_charges": [
{
"uid": "tB2mgXVVhtIaINB9gFutuB",
"service_charge_uid": "SVS_CHARGE1",
"applied_money": {
"amount": 431,
"currency": "USD"
}
}
],
"total_service_charge_money": {
"amount": 431,
"currency": "USD"
}
},
{
"uid": "ozixhXglLJ9k6O4o5Pkfo",
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 3910,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 3600,
"currency": "USD"
},
"item_type": "ITEM",
"applied_service_charges": [
{
"uid": "z24JMoRuw1y8vmRFHK1UE",
"service_charge_uid": "SVS_CHARGE1",
"applied_money": {
"amount": 310,
"currency": "USD"
}
}
],
"total_service_charge_money": {
"amount": 310,
"currency": "USD"
}
}
],
"created_at": "2024-06-18T20:47:37.048Z",
"updated_at": "2024-06-18T20:47:37.048Z",
"state": "OPEN",
"version": 1,
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_tip_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 12600,
"currency": "USD"
},
"service_charges": [
{
"uid": "SVS_CHARGE1",
"name": "service charge",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"applied_money": {
"amount": 1000,
"currency": "USD"
},
"calculation_phase": "APPORTIONED_AMOUNT_PHASE",
"taxable": true,
"total_money": {
"amount": 1000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"type": "CUSTOM",
"treatment_type": "APPORTIONED_TREATMENT",
"scope": "ORDER"
}
],
"total_service_charge_money": {
"amount": 1000,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 12600,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 1000,
"currency": "USD"
}
},
"customer_id": "0V2VTQ2XQZJRNA8WXVSF81EWH0",
"net_amount_due_money": {
"amount": 12600,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
## Apportioned percentage service charge
Suppose the total service charge on the order is 10% of the order subtotal (before tax). The order subtotal is $116, which means that the service charge is $11.60. That amount needs to be apportioned across all line items using the following calculation:
* `Dog Biscuits - Chicken Flavor`: ((2 @ $15 per box = $30) / $116) * 11.60 = $3.00
* `Handmade Sweater - Blue`: (($50) / $116) * 11.60 = $5.00
* `Chewy Rawhide - Beef Flavor`: ((3 @ $12 per box = $30) / $116) * 11.60 = $3.60
The three apportioned line-item service charges ($3.00 + $5.00 + $3.60) equal the $11.60 total service charge.
## Apportioned service charge taxes
Apportioned service charges cannot have their own tax rate or amount. Instead, `applied_service_charges` inherit the tax of the line item it's applied to. If you add an applied tax to an apportioned service charge, it's ignored.
### Ignored service charge taxes
In the following example, an apportioned service charge is declared with a tax applied directly to the service charge:
{% tabset %}
{% tab id="Request" %}
```json
{
"service_charges": [
{
"calculation_phase": "APPORTIONED_AMOUNT_PHASE",
"name": "Fixed amount service charge",
"treatment_type": "APPORTIONED_TREATMENT",
"uid": "APPORTIONED_AMOUNT_SERVICE_CHARGE",
"scope": "LINE_ITEM",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"taxable": true,
"applied_taxes": [
{
"tax_uid": "SERVICE_CHARGE_TAX",
"uid": "2"
}
]
}
],
"taxes": [
{
"name": "Service charge tax",
"percentage": "8",
"scope": "LINE_ITEM",
"type": "ADDITIVE",
"uid": "SERVICE_CHARGE_TAX"
}
]
}
```
{% /tab %}
{% tab id="Response" %}
The following response shows that the service charge is applied to the line item but not the service charge tax:
```json
{
"line_items": [
{
"uid": "H5j9clSbv0cAQoUWGzv7QD",
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 3000,
"currency": "USD"
},
"item_type": "ITEM",
"applied_service_charges": [
{
"uid": "1",
"service_charge_uid": "APPORTIONED_AMOUNT_SERVICE_CHARGE",
"applied_money": {
"amount": 2000,
"currency": "USD"
}
}
],
"total_service_charge_money": {
"amount": 2000,
"currency": "USD"
}
},
}
```
{% /tab %}
{% /tabset %}
A non-apportioned line-item service charge must have its own tax information configured with its own rate, which can be different from the line-item tax rate. If a seller wants to ensure that a service charge is taxed at the same rate as its associated line item, an apportioned service charge should be used.
## Percentage service charges
When you specify a percentage service charge to an order, Square calculates the service charge as a percentage of the whole order. If you want to apply service charges to individual line items, you need to use apportioned service charges.
Raphael's Puppy-Care Emporium has established a fund to help encourage pet adoption and is adding a service charge for this. The service charge is applied after discounts, but before taxes (subtotal phase).
{% aside type="important" %}
When processing tips for external vendors (such as third-party delivery couriers), do not use the Payment object's tip fields. Adding tips through the Payment object would incorrectly include these amounts in the seller's internal team members' tip pool.
Instead, use the [Order.service_charge](https://developer.squareup.com/reference/square/objects/order#definition__property-service_charges) property on the Order object to record tips for external vendors who help fulfill orders. This ensures:
- External vendor tips are properly segregated from internal team member tips
- Tips are correctly attributed to the external vendor
- Tip amounts don't impact the seller's internal tip pool calculations
{% /aside %}
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines this service charge (`PET-ADOPT-1.5-PCT`) and applies it to the order:
````
{% /tab %}
{% tab id="Response" %}
In the following response, the 1.5% `service_charge_money` ($1.74) is added to the $116.00 total, so the `net_amount_due_money` is $117.74:
```json
{
"order": {
"line_items": [
{
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
"total_money": {
"amount": 3000,
"currency": "USD"
}
},
{
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
}
},
{
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
"total_money": {
"amount": 3600,
"currency": "USD"
}
}
],
"total_money": {
"amount": 11774,
"currency": "USD"
},
"service_charges": [
{
"name": "PET-ADOPT-1.5-PCT",
"percentage": "1.5",
"applied_money": {
"amount": 174,
"currency": "USD"
},
"calculation_phase": "SUBTOTAL_PHASE",
"total_money": {
"amount": 174,
"currency": "USD"
},
}
],
"total_service_charge_money": {
"amount": 174,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 11774,
"currency": "USD"
},
"service_charge_money": {
"amount": 174,
"currency": "USD"
}
},
"net_amount_due_money": {
"amount": 11774,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
## Service charge taxes
You can apply a tax to an order-level service charge in the same way you can apply a tax to a line item. In the following example, an order-level service charge of $10 is added to an order. The service charge applies a special service charge line-item tax of 8%. The order-scoped service charge is treated as a single line item, which is why the tax needs to be a `LINE_ITEM` tax.
{% tabset %}
{% tab id="Request" %}
````
{% aside type="info" %}
Setting `service_charges.taxable` has no bearing on whether a tax is charged on the service charge. As long as you set `service_charges.applied_taxes`, a tax will be applied.
{% /aside %}
{% /tab %}
{% tab id="Response" %}
The response shows that a service charge tax of $.80 is added to the order and applied to the service charge. In the order total amounts, `total_service_charge_money` doesn't reflect the tax. However, you can see the tax in `net_amounts.tax_money`.
```json
{
"order": {
"location_id": "VJN4XSBFTVPK9",
"line_items": [
{
"uid": "hc8R2Ky8qG4X7s7z95JYBC",
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 3000,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 3000,
"currency": "USD"
},
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
{
"uid": "KuoP2Nl0eZHiXqwn52OMwC",
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 5000,
"currency": "USD"
},
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
{
"uid": "gyqXxxDcDbSlSmEoiNFyzC",
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 3600,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 3600,
"currency": "USD"
},
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
}
],
"taxes": [
{
"uid": "SERVICE_CHARGE_TAX",
"name": "Service charge tax",
"percentage": "8",
"type": "ADDITIVE",
"applied_money": {
"amount": 80,
"currency": "USD"
},
"scope": "LINE_ITEM"
}
],
"created_at": "2024-06-28T20:47:28.825Z",
"updated_at": "2024-06-28T20:47:28.825Z",
"state": "OPEN",
"version": 1,
"total_tax_money": {
"amount": 80,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_tip_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 12680,
"currency": "USD"
},
"service_charges": [
{
"uid": "APPORTIONED_AMOUNT_SERVICE_CHARGE",
"name": "twelve percent service charge",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"applied_money": {
"amount": 1000,
"currency": "USD"
},
"calculation_phase": "SUBTOTAL_PHASE",
"taxable": true,
"total_money": {
"amount": 1080,
"currency": "USD"
},
"total_tax_money": {
"amount": 80,
"currency": "USD"
},
"applied_taxes": [
{
"uid": "2",
"tax_uid": "SERVICE_CHARGE_TAX",
"applied_money": {
"amount": 80,
"currency": "USD"
}
}
],
"type": "CUSTOM",
"treatment_type": "LINE_ITEM_TREATMENT",
"scope": "ORDER"
}
],
"total_service_charge_money": {
"amount": 1000,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 12680,
"currency": "USD"
},
"tax_money": {
"amount": 80,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 1000,
"currency": "USD"
}
},
"customer_id": "0V2VTQ2XQZJRNA8WXVSF81EWH0",
"net_amount_due_money": {
"amount": 12680,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
## 3rd-Party delivery tip with a service charge
Use an order-scoped, non-taxable service charge to represent a tip intended for a 3rd-party courier such as DoorDash rather than the seller’s staff. This keeps the amount out of payment‐level gratuity reporting and avoids affecting item-level taxes.
### Why a service charge?
`payment.tip_money` is designed for staff gratuities associated with the seller’s team that should be paid out through payroll. An `order.service_charge` is considered the best place to pass non-line-item order adjustments, including those that are pass-through to the merchants like courier tips and delivery platform fees.
### Recommended settings
* `scope`- `ORDER` (applies to the whole order).
* `amount_money` - Pass in an explicit tip amount, don't calculate the service charge using a percentage.
* `calculation_phase` - `TOTAL_PHASE` or `SUBTOTAL_PHASE`. While this field is required in API requests, it only affects percentage-based calculations. When providing an explicit amount, the phase value is accepted but not used in calculations. Avoid using apportioned phases (like `APPORTIONED_PERCENTAGE_PHASE`), as these follow different rules for distributing amounts across line items.
* `taxable` - `false`
* `name` - A clear label like "Courier Tip" for downstream reporting.
### Example
This example shows a $1.50 tip for the courier who delivered the order:
```json
"service_charges": [
{
"scope": "ORDER",
"calculation_phase": "TOTAL_PHASE",
"taxable": false,
"amount_money": { "amount": 150, "currency": "USD" },
"name": "Courier Tip"
}
]
```
## See also
* [Order Price Adjustments](orders-api/price-adjustments)
* [Order Taxes](orders-api/taxes)
* [Order Discounts](orders-api/discounts)
---
# Order Taxes
> Source: https://developer.squareup.com/docs/orders-api/taxes
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to apply taxes to an order using the Orders API.
**Applies to:** [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to apply taxes to an order using the Orders API.{% /subheading %}
{% toc hide=true /%}
## Overview
Building on the example order created in [Order Price Adjustments](orders-api/price-adjustments), learn how to apply taxes to the example order.
The final calculations for the order involve taxes. There are two types of taxes and they're processed by the Orders API in this order:
1. **Item-level taxes** - Calculated and applied to one or more individual items.
2. **Order-level taxes** - Calculated for the entire order and then distributed proportionally to each item as apportioned taxes.
## Example
In the following example, the state of California has approved the following taxes, which must now be collected:
* A 5% fair trade tax, applicable to any handmade goods.
* An 8.5% sales tax on every order.
{% line-break /%}
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines these two taxes (`FAIR-TRADE-5-PCT` and `STATE-SALES-8.5-PCT`) and applies each one appropriately:
````
{% /tab %}
{% tab id="Response" %}
In the response, the fair trade tax is applied only to the handmade sweater. The state sales tax is calculated for the order total and distributed proportionally across all the items.
```json
{
"order": {
"line_items": [
{
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
"total_tax_money": {
"amount": 255,
"currency": "USD"
},
"total_money": {
"amount": 3255,
"currency": "USD"
},
"applied_taxes": [
{
"tax_uid": "STATE-SALES-8.5-PCT",
"applied_money": {
"amount": 255,
"currency": "USD"
}
}
],
},
{
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
"total_tax_money": {
"amount": 675,
"currency": "USD"
},
"total_money": {
"amount": 5675,
"currency": "USD"
},
"applied_taxes": [
{
"tax_uid": "FAIR-TRADE-5-PCT",
"applied_money": {
"amount": 250,
"currency": "USD"
}
},
{
"tax_uid": "STATE-SALES-8.5-PCT",
"applied_money": {
"amount": 425,
"currency": "USD"
}
}
]
},
{
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
"total_tax_money": {
"amount": 306,
"currency": "USD"
},
"total_money": {
"amount": 3906,
"currency": "USD"
},
"applied_taxes": [
{
"tax_uid": "STATE-SALES-8.5-PCT",
"applied_money": {
"amount": 306,
"currency": "USD"
}
}
]
}
],
"taxes": [
{
"uid": "STATE-SALES-8.5-PCT",
"name": "State sales tax - 8.5%",
"percentage": "8.5",
"type": "ADDITIVE",
"applied_money": {
"amount": 986,
"currency": "USD"
},
"scope": "ORDER"
},
{
"uid": "FAIR-TRADE-5-PCT",
"name": "Fair Trade Tax - 5%",
"percentage": "5",
"type": "ADDITIVE",
"applied_money": {
"amount": 250,
"currency": "USD"
},
"scope": "LINE_ITEM"
}
],
"total_tax_money": {
"amount": 1236,
"currency": "USD"
},
"total_money": {
"amount": 12836,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 12836,
"currency": "USD"
},
"tax_money": {
"amount": 1236,
"currency": "USD"
}
},
"net_amount_due_money": {
"amount": 12836,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
If your application supports service charges, see [Order Service Charges](orders-api/service-charges) to learn how to apply service charges to this example order. To learn how discounts are applied to this example order, see [Order Discounts](orders-api/discounts).
## See also
* [Order Price Adjustments](orders-api/price-adjustments)
* [Order Service Charges](orders-api/service-charges)
* [Order Discounts](orders-api/discounts)
---
# Order Price Adjustments
> Source: https://developer.squareup.com/docs/orders-api/price-adjustments
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to adjust prices on an order with taxes, discounts, and service charges by using the Orders API.
**Applies to:** [Orders API](orders-api/what-it-does) | [Catalog API](catalog-api/what-it-does)
{% subheading %}Learn how to adjust prices on an order with taxes, discounts, and service charges using the Orders API.{% /subheading %}
{% toc hide=true /%}
## Overview
You can set parameters in a [CreateOrder](https://developer.squareup.com/reference/square/orders-api/create-order) request that tells Square to adjust the line item price for any item in an order. The API calculates these adjustments and applies them as [discounts](orders-api/discounts), [service charges](orders-api/service-charges), or [taxes](orders-api/taxes). Price adjustments are scoped as follows:
* **Item level** - The price adjustment is applied specifically to an applicable line item.
* **Order level** - The price adjustment is distributed across all the line item subtotals.
## Preview order price adjustments
If your application shows the buyer what they will pay for an order when placed, you need to calculate the order before you actually create it. The Orders API provides the [CalculateOrder](https://developer.squareup.com/reference/square/orders-api/CalculateOrder) endpoint that takes the same request body as `CreateOrder`. To preview Square's calculation before you actually create an order, provide the same request body that you will use for `CreateOrder`. In the `CalculateOrder` response, you can see that line item prices now show any discounts, taxes, or service charges that Square applied. You can set these adjustment parameters directly in an order request or, in some cases, you can refer to catalog [taxes](catalog-api/design-a-catalog#taxes) or [discounts](catalog-api/design-a-catalog#discounts) configured by a seller. When you call `CreateOrder` with the same request body, an order is actually created with those calculated values.
## Rounding rules
The Orders API performs its adjustment calculations using Bankers' Rounding, also known as Rounding Half to Even. Under Common Rounding rules (Round Half Up), half-values round up to the next closest integer. However, under Bankers' Rounding, half-values round to the closest even integer. This has the effect of rounding even numbers down, while leaving odd numbers unchanged.
The following table shows examples of values rounded to two decimal places using Common Rounding and Bankers' Rounding:
{% table %}
* Value {% width="80px" %}
* Common Rounding{% width="100px" %}
* Bankers' Rounding
---
* 0.505
* 0.51
* 0.50 (0 is the closest even and 1 is odd. Round down to .50)
---
* 0.715
* 0.72
* (2 is the closest even and 1 is odd. Round up two 2)
---
* 0.085
* 0.09
* 0.08 (8 is the closest even and 9 is odd. Round down to 8)
{% /table %}
### Bankers' Rounding
Bankers' Rounding is a rounding mode in which non-tie decimals (> 0 and ≠ 5) are rounded up or down to the nearest integer and ties (= 5) are rounded to the nearest even integer. For example, non-ties to two decimal places: 3.222 -> 3.22 and –3.228 -> –3.23. Ties to two decimal places: 3.225 -> 3.22 and –3.235 -> –3.24.
## Example use case
To illustrate how the Orders API calculates totals, consider an online order from Raphael's Puppy-Care Emporium. The order consists of the following items:
* Two boxes of chicken-flavored dog biscuits, at $15.00 per box.
* A handmade sweater for dogs (blue color), at $50.00.
* Three packages of beef-flavored chewy rawhide, at $12.00 per package.
The following examples use the [CalculateOrder](https://developer.squareup.com/reference/square/orders-api/CalculateOrder) endpoint to demonstrate each step in the process.
## Initial item totals
The first step is to calculate the initial total for each item, which is the base price of the item multiplied by the quantity.
{% table %}
* Quantity
* Description
* Base price
* Item total
---
* 2
* Dog Biscuits - Chicken Flavor
* $15.00
* $30.00
---
* 1
* Handmade Sweater - Blue
* $50.00
* $50.00
---
* 3
* Chewy Rawhide - Beef Flavor
* $12.00
* $36.00
{% /table %}
The subtotal for the order is the sum of all the item totals: $30.00 + $50.00 + $36.00 = $116.00.
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request shows the items in the order and the totals calculated by the Orders API:
````
{% /tab %}
{% tab id="Response" %}
In this partial response example, the `gross_sales_money` attributes reflect the item totals, while `net_amount_due_money` reflects the subtotal for the order ($116.00).
```json
{
"order": {
"line_items": [
{
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
},
{
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
},
{
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
}
],
"total_money": {
"amount": 11600,
"currency": "USD"
},
"net_amount_due_money": {
"amount": 11600,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
To learn about how discounts are applied to this example order, see [Order Discounts](orders-api/discounts). If your application will support service charges, see [Order Service Charges](orders-api/service-charges) to walk through applying service charges to this example order. To learn about applying taxes to the example order, see [Order Taxes](orders-api/taxes).
## See also
* [Order Discounts](orders-api/discounts)
* [Order Service Charges](orders-api/service-charges)
* [Order Taxes](orders-api/taxes)
---
# Order Discounts
> Source: https://developer.squareup.com/docs/orders-api/discounts
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to apply discounts to an order using the Orders API.
**Applies to:** [Orders API](orders-api/what-it-does) | [Catalog API](catalog-api/what-it-does)
{% subheading %}Learn how to apply discounts to an order using the Orders API.{% /subheading %}
{% toc hide=true /%}
## Overview
Building on the example order created in [Order Price Adjustments](orders-api/price-adjustments), learn how to apply discounts to the example order. If your application uses catalog pricing rules to calculate discount amounts, see [Automatically Apply Discounts](catalog-api/cookbook/auto-apply-discounts) for information about setting up discount pricing rules.
After the Orders API calculates item totals, it considers any available discounts of these types:
* **Discount on order total** - A discount can be defined in the order and based on a percentage (for example, 10% off) or based on a fixed amount and then applied to the order total.
* **Discount on line item** - A discount can be defined in the order and applied to an individual item or the entire order.
* **Pricing rule discount on line item** - A catalog pricing rule for [Square-applied order discounts](orders-api/apply-taxes-and-discounts/auto-apply-discounts) and applied to line items in the order.
If an order has multiple discounts of different scopes and types, they're calculated and applied in this sequence:
1. Item-level percentage
2. Order-level percentage
3. Order-level fixed amount
4. Item-level fixed amount
{% aside type="important" %}
Because order-level fixed-amount discounts are applied before item-level fixed-amount discounts, the order-level discount can reduce an item's price before the item-level discount is calculated. If the item-level discount is close to the item's base price, it might not fully apply. To avoid this, convert the item-level fixed-amount discount to an equivalent percentage discount.
{% /aside %}
{% accordion %}
{% slot "heading" %}
## Percentage discounts
{% /slot %}
### On items
Chicken-flavored dog biscuits have been discontinued, so this item receives a 7% discount. The `applied_discounts` attribute tells Square that this line item gets a specific discount and the `discounts` attribute defines what the discount is. `applied_discounts` can be set on any line item and reference any `discount` defined in the order.
Note that `applied_discounts` is a list, which means that multiple discounts can be applied to a single line item.
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines the discount (`DISCONTINUED-7-PCT`) and applies it to `Dog Biscuits - Chicken Flavor`:
````
{% /tab %}
{% tab id="Response" %}
In the response, `total_discount_money` for the item is $2.10, which is 7% of the `gross_sales_money` for the item. The item total is adjusted from $30.00 to $27.90, which lowers the order total from $116.00 to $113.90.
```
{
"order": {
...
"line_items": [
{
...
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 210,
"currency": "USD"
},
"total_money": {
"amount": 2790,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "DISCONTINUED-7-PCT",
"applied_money": {
"amount": 210,
"currency": "USD"
}
}
],
...
},
...
],
"discounts": [
{
"uid": "DISCONTINUED-7-PCT",
"name": "Discontinued - 7% off",
"percentage": "7",
"applied_money": {
"amount": 210,
"currency": "USD"
},
"type": "FIXED_PERCENTAGE",
"scope": "LINE_ITEM"
}
],
...
"total_discount_money": {
"amount": 210,
"currency": "USD"
},
...
"total_money": {
"amount": 11390,
"currency": "USD"
},
...
"net_amounts": {
"total_money": {
"amount": 11390,
"currency": "USD"
},
...
"discount_money": {
"amount": 210,
"currency": "USD"
},
...
},
"net_amount_due_money": {
"amount": 11390,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
### On orders
To celebrate National Puppy Day, the entire order receives a 12% discount. The Orders API calculates and applies order-level discounts as line-item price adjustments, so it apportions the discount across all the line-item subtotals. In this case, the `applied_discounts` attribute isn't used. The `discounts` attribute uses a `scope` parameter to tell Square to apply the discount to all line items.
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines the discount (`NATL-PUPPY-12-PCT`) to be applied to all the items:
````
{% /tab %}
{% tab id="Response" %}
In the response, the 12% order discount is shown as `total_discount_money`. The amount is deducted from `gross_sales_money`, resulting in `total_money` for the item.
The total `discount_money` for the order is $13.92. When subtracted from the $116.00 item total, the resulting `net_amount_due_money` is $102.08.
```
{
"order": {
...
"line_items": [
{
...
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 360,
"currency": "USD"
},
"total_money": {
"amount": 2640,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF",
"applied_money": {
"amount": 360,
"currency": "USD"
}
}
],
...
},
{
...
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 600,
"currency": "USD"
},
"total_money": {
"amount": 4400,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF",
"applied_money": {
"amount": 600,
"currency": "USD"
}
}
],
...
},
{
...
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 432,
"currency": "USD"
},
"total_money": {
"amount": 3168,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF",
"applied_money": {
"amount": 432,
"currency": "USD"
}
}
],
...
}
],
"discounts": [
{
"uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF",
"name": "National Puppy Day - 12% off",
"percentage": "12",
"applied_money": {
"amount": 1392,
"currency": "USD"
},
"type": "FIXED_PERCENTAGE",
"scope": "ORDER"
}
],
...
"total_discount_money": {
"amount": 1392,
"currency": "USD"
},
...
"total_money": {
"amount": 10208,
"currency": "USD"
},
...
"net_amounts": {
"total_money": {
"amount": 10208,
"currency": "USD"
},
...
"discount_money": {
"amount": 1392,
"currency": "USD"
},
...
},
"net_amount_due_money": {
"amount": 10208,
"currency": "USD"
}
}
}
```
In this example, you can see the discount of $13.92 shown in three places:
* **Individual discount total** - The total for the single discount defined. If there were multiple discounts on the order, each discount would be totaled in `discounts[].applied_money`.
* **Total order discounts** - The sum total of all discounts applied to the order in `total_discount_money`.
* **Amount subtracted from order total** - The amount discounted from the total amount of the order in `net_amounts.discount_money`.
The latter two attributes are always the same amount. When coding a report, such as a sales activity report, you can use the `net_amounts` attribute instead of `total_money` and `total_discount_money` to populate report line items.
{% /tab %}
{% /tabset %}
{% /accordion %}
{% accordion %}
{% slot "heading" %}
## Fixed amount discounts
{% /slot %}
### On items
To thank customers for their business, a Puppy Appreciation Discount is applied to dog treats. Customers save $3.00 on chicken-flavor dog biscuits and $11.00 on beef-flavor chewy rawhide.
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines two discounts (APPREC-3-USD and APPREC-11-USD) and applies them to the appropriate items:
````
{% /tab %}
{% tab id="Response" %}
In the response, $3.00 is deducted from the dog biscuits and $11.00 is deducted from the rawhide. The total `discount_money` for the order is $14.00. When subtracted from the $116.00 item total, the resulting `net_amount_due_money` is $102.00.
{% aside type="info" %}
An item-level fixed discount is applied to the extended price of the line item. In the example, two dog biscuits were ordered for a gross amount of $30. The fixed $3 discount is applied, leaving a net total of $27 for the line item.
{% /aside %}
```
{
"order": {
...
"line_items": [
{
...
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 300,
"currency": "USD"
},
"total_money": {
"amount": 2700,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "APPREC-3-USD",
"applied_money": {
"amount": 300,
"currency": "USD"
}
}
],
...
},
{
...
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
...
},
{
...
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 1100,
"currency": "USD"
},
"total_money": {
"amount": 2500,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "APPREC-11-USD",
"applied_money": {
"amount": 1100,
"currency": "USD"
}
}
],
...
}
],
"discounts": [
{
"uid": "APPREC-3-USD",
"name": "Customer Appreciation Discount - $3 off",
"amount_money": {
"amount": 300,
"currency": "USD"
},
"applied_money": {
"amount": 300,
"currency": "USD"
},
"type": "FIXED_AMOUNT",
"scope": "LINE_ITEM"
},
{
"uid": "APPREC-11-USD",
"name": "Customer Appreciation Discount - $11 off",
"amount_money": {
"amount": 1100,
"currency": "USD"
},
"applied_money": {
"amount": 1100,
"currency": "USD"
},
"type": "FIXED_AMOUNT",
"scope": "LINE_ITEM"
}
],
...
"total_discount_money": {
"amount": 1400,
"currency": "USD"
},
...
"total_money": {
"amount": 10200,
"currency": "USD"
},
...
"net_amounts": {
"total_money": {
"amount": 10200,
"currency": "USD"
},
...
"discount_money": {
"amount": 1400,
"currency": "USD"
},
...
},
"net_amount_due_money": {
"amount": 10200,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
### On orders
To celebrate the storewide Anniversary Sale, a discount of $5.00 is applied to the entire order. The Orders API calculates and applies order-level discounts as line-item price adjustments, so it evenly distributes the discount across all the line-item subtotals.
{% tabset %}
{% tab id="Request" %}
The following `CalculateOrder` request defines the discount `(ANNI-SALE-5-USD)` to be applied to all the items:
````
{% /tab %}
{% tab id="Response" %}
In the response, the $5.00 discount is distributed across the item totals, in proportion to the $116.00 subtotal for the order.
{% table %}
* Item
* Item total
* % of $116.00
* Contribution to discount
---
* Biscuits
* $30.00
* 25.86%
* $1.29
---
* Sweater
* $50.00
* 43.10%
* $2.16
---
* Rawhide
* $36.00
* 31.03%
* $1.55
{% /table %}
The total `discount_money` for the order is $5.00. When subtracted from the $116.00 item total, the resulting `net_amount_due_money` is $111.00.
```
{
"order": {
...
"line_items": [
{
...
"quantity": "2",
"name": "Dog Biscuits - Chicken Flavor",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 129,
"currency": "USD"
},
"total_money": {
"amount": 2871,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF",
"applied_money": {
"amount": 129,
"currency": "USD"
}
}
],
...
},
{
...
"quantity": "1",
"name": "Handmade Sweater - Blue",
"base_price_money": {
"amount": 5000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 5000,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 216,
"currency": "USD"
},
"total_money": {
"amount": 4784,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF",
"applied_money": {
"amount": 216,
"currency": "USD"
}
}
],
...
},
{
...
"quantity": "3",
"name": "Chewy Rawhide - Beef Flavor",
"base_price_money": {
"amount": 1200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 3600,
"currency": "USD"
},
...
"total_discount_money": {
"amount": 155,
"currency": "USD"
},
"total_money": {
"amount": 3445,
"currency": "USD"
},
...
"applied_discounts": [
{
...
"discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF",
"applied_money": {
"amount": 155,
"currency": "USD"
}
}
],
"item_type": "ITEM"
}
],
"discounts": [
{
"uid": "GLOBAL-SALES-5-DOLLARS-OFF",
"name": "Global Sales - $5 off",
"amount_money": {
"amount": 500,
"currency": "USD"
},
"applied_money": {
"amount": 500,
"currency": "USD"
},
"type": "FIXED_AMOUNT",
"scope": "ORDER"
}
],
...
"total_discount_money": {
"amount": 500,
"currency": "USD"
},
...
"total_money": {
"amount": 11100,
"currency": "USD"
},
...
"net_amounts": {
"total_money": {
"amount": 11100,
"currency": "USD"
},
...
"discount_money": {
"amount": 500,
"currency": "USD"
},
...
},
"net_amount_due_money": {
"amount": 11100,
"currency": "USD"
}
}
}
```
{% /tab %}
{% /tabset %}
{% /accordion %}
{% accordion %}
{% slot "heading" %}
## Item catalog pricing rule discount
{% /slot %}
The owners of Raphael's Puppy-Care Emporium have decided to offer a Buy One, Get One Free discount to motivate customers to buy combinations of dog biscuit items. To expedite the checkout process, they set up a pricing rule in their catalog to [automatically apply discounts](catalog-api/cookbook/auto-apply-discounts). On every order, they add the [pricing_options](https://developer.squareup.com/reference/square/objects/Order#definition__property-pricing_options) attribute and set `auto_apply_discounts`. That's all they need to do. When set, any order that contains a catalog item that matches a price rule is automatically discounted.
{% tabset %}
{% tab id="Request" %}
The following example shows an order for two cases of dog biscuits. The details of the line item are taken from the [CatalogItemVariation](https://developer.squareup.com/reference/square/objects/CatalogItemVariation) referenced by `catalog_object_id`.
````
{% /tab %}
{% tab id="Response" %}
Because Raphael's Puppy-Care Emporium is giving away a package of chewy rawhide for every two cases of biscuits purchased, the Order is automatically updated with the Buy One, Get One Free discount defined by the catalog as shown in this response:
```
{
"order":{
"id":"5FLV8dgGYHgRdrE4XOR9W8RMxh4F",
"location_id":"7WQ0KXC8ZSD90",
"line_items":[
{
"uid":"PpAcZ9GNazqgGpy99BHbUC",
"catalog_object_id":"K5NRPU4HXO6O5RFFHLEW3TI2",
"quantity":"1",
"name":""Chewy Rawhide",
"variation_name":"Chewy Rawhide - Beef Flavor",
"base_price_money":{
"amount":500,
"currency":"USD"
},
"total_discount_money":{
"amount":500,
"currency":"USD"
},
"applied_discounts":[
{
"uid":"ApDUTXKYyDukeiA98cG6mD",
"discount_uid":"a5nircWuDBWzPBh797O5SD",
"applied_money":{
"amount":500,
"currency":"USD"
}
}
],
"item_type":"ITEM"
},
{
"uid":"PpAcZ9GNazqgGpy99BHbUC",
"catalog_object_id":"RZNRPU4HXO6O5ROGHLEW3TI2",
"quantity":"2",
"name":""Dog Biscuits",
"variation_name":"Dog Biscuits - Beef Flavor",
"base_price_money":{
"amount":1500,
"currency":"USD"
},
"item_type":"ITEM"
}
],
"discounts":[
{
"uid":"a5nircWuDBWzPBh797O5SD",
"catalog_object_id":"FJYAGNWCJSX42774FCLQZ25Z",
"name":"BOGO",
"percentage":"100.0",
"applied_money":{
"amount":"500,
"currency":"USD"
},
"type":"FIXED_PERCENTAGE",
"scope":"LINE_ITEM",
"pricing_rule_id":"TL3AYTOI4DB4HYTL2WK3QJ6J"
}
],
"total_money":{
"amount":3000,
"currency":"USD"
},
"pricing_options":{
"auto_apply_discounts":true
}
}
}
```
In this example, the chewy rawhide line item has an `applied_discount` attribute to indicate that it's the free item, while the two cases of biscuits are sold at the regular price. The `discounts` attribute on the order details the discount given on the order and references the pricing rule applied from the catalog.
{% /tab %}
{% /tabset %}
{% /accordion %}
## See also
* [Order Price Adjustments](orders-api/price-adjustments)
* [Order Service Charges](orders-api/service-charges)
* [Order Taxes](orders-api/taxes)
* [Redeem Loyalty Points for a Discount](loyalty-api/walkthrough1/redeem-points)
---
# Configure the Mobile Payments SDK for Square Stand or Square Kiosk
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/square-stand
> Status: PUBLIC
> Languages: All
> Platforms: iOS
Configure the Mobile Payments SDK on iOS to use Square Stand or Square Kiosk to take card payments.
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios)
{% subheading %}Learn how to configure your Mobile Payments SDK iOS application to work with Square Stand and Square Kiosk.{% /subheading %}
{% toc hide=true /%}
## Requirements and limitations
You need to [install the Mobile Payments SDK](mobile-payments-sdk/ios#1-install-the-sdk-and-dependencies) and [authorize your application](mobile-payments-sdk/ios/configure-authorize) to take payments.
{% aside type="info" %}
Other than Square Readers, the Mobile Payments SDK cannot talk to any printers, cash drawers, barcode scanners, or other peripherals connected through Square Stand or Square Kiosk.
{% /aside %}
## Update your Info.plist file for Square Stand
To use [Square Stand](https://squareup.com/stand) or [Square Kiosk](https://squareup.com/us/en/hardware/kiosk) with your Mobile Payments SDK application, add the following key-value pairs to your `Info.plist` file. The SDK automatically detects whether a Square Stand or Square Kiosk is connected and uses it to accept card payments.
Key | Values
----| ------
[UISupportedExternalAccessoryProtocols](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html#//apple_ref/doc/uid/TP40009252-SW4) | `com.squareup.s020`{% line-break /%}`com.squareup.s025`{% line-break /%}`com.squareup.s089`{% line-break /%}`com.squareup.protocol.stand`
{% aside type="warning" %}
Before you can submit an application using Square Stand or Square Kiosk to the Apple App Store, Square must notify Apple that your application is authorized to work with Square Stand or Square Kiosk. This process might take several weeks to complete. [Contact us](https://docs.google.com/forms/d/e/1FAIpQLSe5X3KEGZcwH_79t7jcywK9Q_sI7cw9ZHTzpuURjZQKIwvr0g/viewform) for assistance.
{% /aside %}
## See also
* [Build on iOS](mobile-payments-sdk/ios)
---
# Migrate from the Reader SDK
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/migrate
> Status: PUBLIC
> Languages: All
> Platforms: iOS, Android
Learn how to migrate applications from the Reader SDK to use the Mobile Payments SDK.
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [Mobile Authorization API](mobile-authz/what-it-does) | [OAuth API](oauth-api/overview) | [Payments API](payments-refunds) | [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to migrate applications from the Reader SDK to use the Mobile Payments SDK.{% /subheading %}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK is the successor of the Reader SDK, providing a simple and PCI-compliant payment flow for iOS and Android applications. Developers should migrate their Reader SDK applications to the Mobile Payments SDK to benefit from new features and ensure continued support **before the retirement of the Reader SDK on December 31, 2025**. The following sections cover the major differences between the Reader SDK and the Mobile Payments SDK. When migrating your application, you can also reference the Mobile Payments SDK sample applications for [iOS](https://github.com/square/mobile-payments-sdk-ios) and [Android](https://github.com/square/mobile-payments-sdk-android).
{% aside type="info" %}
When migrating or upgrading to the Mobile Payments SDK **version 2.1 or above**, you are required to submit an application signature to Square prior to taking production payments. See the instructions for [iOS](mobile-payments-sdk/ios#application-signature) and [Android](mobile-payments-sdk/android#application-signature).
{% /aside %}
## OAuth authentication
The Reader SDK requires a mobile authorization code generated with the Mobile Authorization API to authorize the SDK, in addition to the standard OAuth flow. In contrast, the Mobile Payments SDK doesn't require a mobile authorization code, only the standard [PKCE OAuth flow](oauth-api/overview#pkce-flow). The Mobile Authorization API isn't required to use the Mobile Payments SDK.
When a seller signs in to Square using your [authorization URL](oauth-api/create-urls-for-square-authorization) and approves your authorization request, your redirect URL receives the authorization response containing an authorization code. This code is used to call the `ObtainToken` endpoint, which returns the Square seller's `access_token` in the response. Use this access token with the Mobile Payments SDK `AuthorizationManager.authorize` method and when calling other Square APIs. To learn more about the OAuth workflow, see [OAuth API](oauth-api/overview).
## Payments, not transactions
The Mobile Payments SDK is built on the [Payments API](payments-refunds), enabling a comprehensive integration with the rest of the Square Developer platform. In contrast, the Reader SDK is built on the now deprecated Transactions API, which shouldn't be used moving forward. Working with payments instead of transactions allows you to benefit from all the capabilities offered by this and other APIs, including:
* Collecting developer [application fees](payments-api/take-payments-and-collect-fees) (a portion of each payment your application processes using the Mobile Payments SDK).
* The [delayed capture of payments](payments-api/take-payments/card-payments/delayed-capture) and a configurable delay duration before completing or voiding a payment.
* Adding tips, discounts, and taxes using the [Orders API](orders-api/what-it-does).
* Associating a payment with a `reference_id` or `team_member_id`.
For more information about modifying your application to use payments instead of transactions, see [Migrate from the Transactions API](payments-api/migrate-from-transactions-api).
## Reader management and settings screen
Another change from the Reader SDK is the addition of programmatic reader management in the Mobile Payments SDK. You can use the `ReaderManager` to pair readers and get a list of readers connected to the mobile device running your application. The `ReaderInfo` class provides details about connected readers such as model, battery percentage, serial number, and card entry methods. You can use this class to create custom screens to display information about the status of readers to application users or use a Square-provided settings screen for quick integration.
## Store a card on file
The Reader SDK includes a built-in workflow for saving a card on file. The Mobile Payments SDK relies on the [Cards API](https://developer.squareup.com/reference/square/cards-api) to save a card to a customer's profile.
To store a card on file with the Mobile Payments SDK:
1. Authorize a payment with a credit card. This payment can be [delayed and canceled later](mobile-payments-sdk/ios/take-payments#delay-the-capture-of-payments) if you don’t want to charge the customer.
2. Note the `payment_id` value.
3. Use the `CreateCard` endpoint to save the card on file. For more information, see [Create a Card on File from a Payment ID](cards-api/walkthrough/card-from-payment-id#step-3-create-a-card-on-file-using-the-payment-id-as-the-source).
## Split tender payments
To take multiple payments or accept different forms of payment on a single order, your application must take each payment separately with the Mobile Payments SDK.
You should build your own checkout flow UI to give buyers the option of split tender payments, create separate `PaymentParameters` for each payment, and then make individual calls to `PaymentManager.startPayment()` (iOS) or `PaymentManager.startPaymentActivity()` (Android).
If you're using the [Orders API](https://developer.squareup.com/reference/square/orders-api) and want to split a payment for an order, each payment made with the Mobile Payments SDK must include the `orderID` in the `PaymentParameters` and `autocomplete` must be set to `false`. To complete the payments, call the [PayOrder](https://developer.squareup.com/reference/square/orders-api/pay-order) endpoint, specifying each of the payment IDs. For more information, see [Pay for Orders](orders-api/pay-for-orders).
## Tipping
Tips can be added to a payment before or after authorization by including an optional `tipMoney` value in the payment parameters or by calling the [UpdatePayment](https://developer.squareup.com/reference/square/payments-api/update-payment) endpoint and setting `tip_money` prior to completing a delayed payment. The Mobile Payments SDK doesn't include a built-in tipping UI, so you should build your own tipping UI for your application.
## Signature collection
Signatures aren't required for inserted, tapped, or swiped card payments. The Mobile Payments SDK doesn't include a signature collection workflow.
## Receipts
Your application must provide buyers the option to receive a digital or printed receipt. Receipts aren't sent directly by Square. [You can generate receipts for customers](mobile-payments-sdk/ios/take-payments#receipts) using `cardDetails` from the SDK's payment response or send customers a link to the Square-generated `receipt_url`, found in the Square `Payment` object. This URL is only present on `COMPLETED` payments.
---
# Mobile Payments SDK
> Source: https://developer.squareup.com/docs/mobile-payments-sdk
> Status: PUBLIC
> Languages: All
> Platforms: All
Use the Mobile Payments SDK to accept in-person payments using an embedded Square payment flow in iOS and Android applications.
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [Reader SDK](reader-sdk/what-it-does) | [Payments API](payments-refunds) | [Orders API](orders-api/what-it-does) | [OAuth API](oauth-api/overview)
{% subheading %}Use the Mobile Payments SDK to accept in-person payments in iOS and Android applications.{% /subheading %}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK lets developers accept in-person payments using an embedded Square payment flow in iOS and Android applications. Sellers can take mobile payments using a Square Reader or Square Stand. The Mobile Payments SDK is the successor of the Reader SDK and offers the following benefits:
* **Offline payments** - Take and store payments locally on a mobile device. Offline payments allows you to build reliability into your application experience so sellers can keep taking payments even if devices lose their network connection. For more information, see [Offline Payments for Android](mobile-payments-sdk/android/offline-payments) or [Offline Payments for iOS](mobile-payments-sdk/ios/offline-payments).
* **Mobile payment integration with the [Payments API](payments-refunds)** - Payments taken with the Mobile Payments SDK are linked to Square `Payment` objects to enable:
* The delayed capture of payments.
* Partial authorization, which is used to split payments across multiple credit cards.
* A configurable delay duration before voiding an authorization.
* Collecting application fees.
* Associating a payment with reference ID, team member ID, or location ID.
* Accepting cash payments.
* **Mobile payment integration with the [Orders API](orders-api/what-it-does)** - Payments taken with the Mobile Payments SDK can be linked to Square `Order` objects to enable:
* Itemization, where a payment is separated into different line items representing `Catalog` objects.
* Applying price modifications such as taxes, discounts, or service charges on items.
* Order-ahead functionality and sending SDK payments to Square Point of Sale for fulfillment.
* **Sandbox support** - Authorize the Mobile Payments SDK with a Square Sandbox account to test your mobile payment integration with fake payments. You can simulate a virtual reader device to take test payments in the Square Sandbox without a physical card reader.
* **Programmatic reader management** - Programmatically pair card readers and monitor their battery level, state, and available payment methods using the SDK `ReaderManager`.
* **Sample applications** – Square provides Mobile Payments SDK sample applications for [iOS](https://github.com/square/mobile-payments-sdk-ios) (written in Swift using SwiftUI) and [Android](https://github.com/square/mobile-payments-sdk-android) (written in Kotlin using Compose) to demonstrate a basic implementation of initialization, authorization, requesting permissions, and taking payments in the Sandbox and in production.
## Requirements and limitations
* The Mobile Payments SDK is currently available for accounts based in the United States, Canada, the United Kingdom, and Australia.
* Using the Mobile Payments SDK to implement payment solutions in unattended terminals or unattended kiosks is strictly prohibited. For example, an outdoor vending machine is unattended because it can be accessed by users outside of normal business hours and might not be in the line of sight of a seller or worker.
* The Mobile Payments SDK can only be used to implement payment solutions in attended terminals or attended kiosks. A terminal or kiosk is considered attended if all the following conditions are met:
* It cannot be physically accessed by buyers outside the seller's normal business hours.
* It's in the line of sight of the seller or one of the seller's workers.
* The onsite seller and workers are trained to use the payment solution and are available to assist and support customers with completing transactions.
* Card issuers impose transaction limits that might trigger a cardholder verification method (CVM) when a transaction or cumulative limit is reached. These limits vary by payment method and by country and region. Verification is handled in the Mobile Payments SDK by entering a personal identification number (PIN) during the payment flow when required by the card issuer.
* When using Mobile Payments SDK version 2.1 or later, you must provide an application signature to Square before taking payments in production. Learn how to do so for [Android](mobile-payments-sdk/android#application-signature) and [iOS](mobile-payments-sdk/ios#application-signature).
## Mobile Payments SDK components
The Mobile Payments SDK is divided into four managers that provide specific areas of functionality:
* **Authorization** - The `AuthorizationManager` handles authorizing and deauthorizing your application to process payments on behalf of a Square seller using an [OAuth access token](oauth-api/what-it-does) and a [location ID](locations-api). OAuth access tokens are used to get authenticated and scoped access to any Square account. These tokens should be used even if you only plan to use the Mobile Payments SDK with your own Square account. For more information, see [OAuth sample applications](sample-apps#oauth-samples).
* **Reader pairing and management** - The `ReaderManager` allows you to pair card readers, listen for reader status updates, and perform actions on reader devices.
* **Payments** - The `PaymentManager` handles the payment flow for your application, which includes determining the available payment methods, taking payments, and accessing payments taken offline.
* **Settings** – The `SettingsManager` provides an optional device management UI that you can use in your application and provides details about the current SDK version.
## OAuth permissions
At minimum, your application must have the following permissions to use the Mobile Payments SDK:
* `MERCHANT_PROFILE_READ`
* `PAYMENTS_WRITE`
* `PAYMENTS_WRITE_IN_PERSON`
* To collect application fees, you must also have `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` permission.
* To add credit card surcharges, you must also have `ITEMS_READ` permission.
Depending on its functionality and the other Square APIs used by your application, you might need to request other OAuth permissions for mobile payment integration from sellers. To learn which permissions are required for each API, see [Square OAuth Permissions Reference](oauth-api/square-permissions).
{% aside type="important" %}
Square OAuth access tokens expire after 30 days. Before expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted.
{% /aside %}
## Hardware devices and capabilities
The Mobile Payments SDK can be used to take payments with any version of Square Reader or Square Stand. Offline payment support is limited to the two most recent versions of Square Reader for contactless and chip, Square Reader for magstripe, and Square Stand second generation.
### Identify your Square Reader version
All Square Readers have a 16-digit serial number. Each Square Reader lists its version number in the 5th to 8th digits of the serial number like this XXXX**MMMM**XXXXXXXX. When you locate the serial number, refer to the **MMMM sequence** in the serial number.
{% table %}
* Product name
* Version
* MMMM sequence
* Charging port
* Offline payments support
---
* Square Reader for contactless and chip
(2nd generation)
* Version 1 (v1)
* S171, S172
* USB-C
* ✅
---
* Square Reader for contactless and chip
(1st generation)
* Version 3 (v3)
* S109, S130, S146, S148, S192, S193
* Micro USB
* ✅
---
* Square Reader for contactless and chip
(1st generation)
* Version 2 (v2)
* S084, S095, S098, S103, S127
* Micro USB
* ⛔️
---
* Square Reader for contactless and chip
(1st generation)
* Version 1 (v1)
* S070, S092
* Micro USB
* ⛔️
---
* Square Reader for magstripe
* Version 1 (v1)
* N/A
* N/A
* ✅
{% /table %}
### Identify your Square Stand version
Each Square Stand lists its model number in the 5th to 8th digits of the serial number like this XXXX**MMMM**XXXXXXXX. When you locate the serial number, refer to the **MMMM sequence** in the serial number.
{% table %}
* Product name
* Serial number
* MMMM sequence
* Color
* Hardware
* Offline payments support
---
* Square Stand
(2nd generation)
* 16-digit serial number
* S176, S155
* Black & White
* Built-in contactless and chip reader
* ✅
---
* Square Stand
(1st generation)
* 16-digit or 14-digit serial number
* S142, S015, S020, S021, S067, S025, S068, S089, S089
* White
* Built-in magstripe reader
* ✅
{% /table %}
The `ReaderManager` can be used to access the device serial number programmatically to determine the device version. A payment attempted with an offline flow on unsupported hardware results in an error.
### Update policy
Developers should make their best efforts to update their working version of the Mobile Payments SDK as soon as new versions are available. Square supports a given version of the Mobile Payments SDK for 2 years following its GA (General Availability) release, unless an update is required to address critical security updates or vulnerabilities or as otherwise deemed necessary by Square. If it becomes necessary to discontinue support for an SDK version before the 2-year life expectancy, Square contacts you in advance using the email address associated with your Square account.
## See also
* [Build on Android](mobile-payments-sdk/android)
* [Build on iOS](mobile-payments-sdk/ios)
---
# Build on iOS
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios
> Status: PUBLIC
> Languages: Swift, Objective C
> Platforms: iOS
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [Payments API](payments-refunds) | [OAuth API](oauth-api/overview)
{% subheading %}Learn how to build a secure in-person payment solution for iOS devices with the Mobile Payments SDK.{% /subheading %}
{% line-break /%}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK offers developers a secure way to integrate the Square checkout flow into their mobile applications, and accept in-person payments with a Square Reader or Square Stand.
There are four steps required to take your first payment using the Mobile Payments SDK:
1. [Install and configure the Mobile Payments SDK in your Xcode application](#install-sdk)
2. [Authorize the Mobile Payments SDK](mobile-payments-sdk/ios/configure-authorize#authorize)
3. [Pair a card reader](mobile-payments-sdk/ios/pair-manage-readers)
4. [Take a payment](mobile-payments-sdk/ios/take-payments)
For an example implementation, download the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-ios), written in Swift using SwiftUI.
## Requirements and limitations
To build with the Mobile Payments SDK for iOS, the following must be true:
* You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit [squareup.com/activation](https://squareup.com/activation).
* Your Square account is based in the United States, Canada, the United Kingdom, or Australia. If you're developing from outside these areas, you can take test payments in the Square Sandbox, but cannot take production payments.
* You're using Xcode 15.1+.
* You've set your Xcode iOS deployment target to iOS 16+.
* You have a Square application ID. You can find your application ID on the [Developer Console](https://developer.squareup.com/apps).
* Your application must [request an OAuth access token](build-basics/access-tokens#get-an-oauth-access-token) to authorize Square sellers using your application to take payments.
* Your version of the Mobile Payments SDK adheres to the Square update policy. To limit risk to developers and their users, Square enforces an [update policy](mobile-payments-sdk#update-policy) requiring developers keep their version of the Mobile Payments SDK current.
* When using the Mobile Payments SDK version 2.1 or later, you must provide an [application signature](#application-signature) to Square before taking payments in production.
* You're generally familiar with developing applications on iOS. If you're new to iOS development, you should visit the [Apple Training Center](https://training.apple.com/us/en) before continuing.
## Privacy permissions
The Mobile Payments SDK requires that each user grant access to their device's current location while using your application. This ensures that payments are taken in a Square-supported country and that each payment is associated with a specific seller location. At this time, the Mobile Payments SDK can only be used to take production payments in the United States, Canada, the United Kingdom, or Australia. Bluetooth must be enabled to take payments with a contactless and chip reader and microphone access must be granted to take payments with a magstripe reader.
Include the following privacy key/value pairs in your application's `Info.plist` file:
{% table %}
* Key {% width="300px" %}
* Description
---
* [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription)
* Square uses Bluetooth to connect and communicate with Square readers and compatible accessories.
---
* [NSLocationWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription)
* Square needs to know where transactions take place to reduce risk and minimize payment disputes.
---
* [NSMicrophoneUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsmicrophoneusagedescription)
* Some Square readers use the microphone to communicate payment card data to your device.
{% /table %}
{% aside type="info" %}
Some additional settings are required to [use the Mobile Payments SDK with Square Stand](mobile-payments-sdk/ios/square-stand).
{% /aside %}
## Device compatibility
The Mobile Payments SDK isn't compatible with custom devices from OEMs that violate Square's security rules or on devices that grant root access to the mobile device operating system code and kernel. These devices cannot connect to a contactless and chip reader.
The following additional considerations apply when trying to run the SDK on custom devices:
* The Mobile Payments SDK isn't supported for rooted or jailbroken devices.
* The Mobile Payments SDK cannot run on custom operating systems.
* Square prohibits using any software that provides the ability to record or capture screen data or that results in elevated privileges.
* [Verify that your device is supported](https://squareup.com/us/en/compatibility?platform=iOS&brand=Apple) for Square readers.
* Supported OS versions should be the latest or as close to the latest as possible.
* Review Square's support window for the OS version and confirm support for the compilation target version and the runtime version: The compilation target currently supports iOS versions 15 and later.
## Application signature
Developers using the Mobile Payments SDK version 2.1 or later are required to submit an application signature to Square prior to taking payments in production. This signature is an extra layer of security that ensures that your application hasn't been tampered with or otherwise modified by a user.
To submit an application signature, log in to the Developer Console and choose your application. In the left pane, choose **Mobile Payments SDK**, and then choose **Add Signature**.
You must provide your [bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle-ids) and [team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/) to Square.
If you publish a single mobile application used by multiple Square sellers using the same Square application id, you only need to submit one signature per platform for that application. Any debug builds you create that take payments in production also require their own application signature.
The **Mobile Payments SDK** page in the Developer Console lists each signature that you've submitted. If an application signature is deleted, the application is no longer able to take payments, but you can submit a new signature for your application at any time.
{% aside type="info" %}
If you're developing with the Mobile Payments SDK's [Flutter](mobile-payments-sdk/flutter) or [React Native](mobile-payments-sdk/react-native) plugins and publishing both an Android and iOS application, you must submit a signature for each application.
{% /aside %}
## Data privacy consent
To comply with data privacy laws, the Mobile Payments SDK requires merchants in Canada, the United Kingdom, and the European Union to grant or deny consent for performance and analytics tracking. Your application must handle consent appropriately for merchants in these regions using the `TrackingConsentManager` protocol.
Before processing payments, check the current state of consent for the authorized merchant.
{% tabset %}
{% tab id="Swift" %}
```swift
let consentState = trackingConsentManager.getTrackingConsentState()
```
{% /tab %}
{% tab id="ObjectiveC" %}
```objectivec
ConsentState consentState = [self.trackingConsentManager getTrackingConsentState];
```
{% /tab %}
{% /tabset %}
The possible states are:
* `pending` - Consent has not yet been provided
* `granted` - Merchant has granted consent for tracking
* `denied` - Merchant has denied consent for tracking
* `notRequired` - Merchant is in a region where consent is not required for tracking
When your application prompts merchants for consent, log their response using `setTrackingConsentStateIsGranted(_ isGranted: Bool)`.
{% tabset %}
{% tab id="Swift" %}
```swift
trackingConsentManager.setTrackingConsentStateIsGranted(true) // or false
```
{% /tab %}
{% tab id="ObjectiveC" %}
```objectivec
[self.trackingConsentManager setTrackingConsentStateIsGranted:YES]; // or NO
```
{% /tab %}
{% /tabset %}
If you don't implement consent handling via the API, the SDK automatically displays a consent dialog modal to users in regions where consent is required. This modal:
* appears on the first payment attempt or when the user first opens the [settings screen](mobile-payments-sdk/ios/pair-manage-readers#settings-manager).
* is shown only once per application per device.
* is not displayed to users outside required regions.
Listen for changes to `trackingConsentState` by conforming to the `TrackingConsentStateObserver` protocol.
{% aside type="important" %}
If you use a custom UI for your payment prompt screen and have not provided your user's consent status with the API, the SDK returns an error from `startPayment`. You must handle consent before initiating any payment when using a custom payment UI.
{% /aside %}
## Quickstart
Get started with the Mobile Payments SDK by configuring your iOS application and taking a test payment in the Square Sandbox.
Use the following steps to set up and test the Mobile Payments SDK in your own application. You can also download the [Mobile SDK sample application](https://github.com/square/mobile-payments-sdk-ios) (written in Swift) to see an example of initialization, authorization, requesting permissions, and taking payments in production or the Square Sandbox.
{% anchor id="install-sdk" /%}
## 1. Install the SDK and dependencies
### Option A: Install with Swift Package Manager
Install the Mobile Payments SDK with Swift Package Manager by following these steps in your Xcode project:
1. Choose **File**, and then choose **Add Package Dependencies**.
2. Enter the repository URL: **https://github.com/square/mobile-payments-sdk-ios**.
3. Choose the **Exact Version** dependency rule and specify the version as `2.4.0`.
4. Ensure the **SquareMobilePaymentsSDK** product is added to your target.
5. Optionally, you can add the **MockReaderUI** product to your target to simulate a physical reader when one isn't present in a Sandbox environment.
### Option B: Install with Cocoapods
Install the Mobile Payments SDK with [Cocoapods](https://guides.cocoapods.org/using/getting-started.html) by adding the following to your Podfile:
```
use_frameworks!
pod "SquareMobilePaymentsSDK", "~> 2.4.0"
# To use a simulated reader device to take sandbox payments, add the optional MockReaderUI:
pod "MockReaderUI", "~> 2.4.0", configurations: ['Debug']
```
## 2. Add a run script in the build phases for your target
1. On the **Build Phases** tab for your application target, choose the **+** button (at the top left of the pane).
2. Choose **New Run Script Phase**. The new run script phase should be the last build phase.
3. Paste the following into the editor panel of the new run script:
```shell
FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}"
"${FRAMEWORKS}/SquareMobilePaymentsSDK.framework/setup"
```
{% aside type="important" %}
Ensure that the new run script phase is the last build phase. Otherwise, the build fails.
{% /aside %}
For the run script to execute correctly, your application must disable user script sandboxing.
1. On the **Build Settings** tab for your application target, find the **Build Options** section.
2. Update the **User Script Sandboxing** setting to **No** for all build configurations.
[Context: Swift, iOS]
## 3. Initialize the Mobile Payments SDK
Before taking a payment or attempting any other operation with the Mobile Payments SDK, you must initialize it using the `initialize()` method and your Square application ID in your `AppDelegate`'s `didFinishLaunchingWithOptions` method.
To get your application ID, sign in to the [Developer Console](https://developer.squareup.com/apps) and choose your application. If you don't have an application yet, see [Get Started](square-get-started) for steps to create a Square application.
Your application opens to the **Credentials** page. This page contains the Square application ID used to initialize the Mobile Payments SDK.
{% aside type="info" %}
To test the Mobile Payments SDK in the Square Sandbox with mock readers and mock payments, switch the toggle at the top of the Developer Console to **Sandbox** to show your Sandbox credentials and initialize the SDK with your Sandbox application ID. To start taking production payments, you must initialize the Mobile Payments SDK again with your production application ID.
{% /aside %}
```swift
import UIKit
import SquareMobilePaymentsSDK
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
MobilePaymentsSDK.initialize(
applicationLaunchOptions: launchOptions,
squareApplicationID: "<#your_square_application_id#>"
)
return true
}
}
```
## 4. Authorize the Mobile Payments SDK
The `AuthorizationManager` handles authorization for the Mobile Payments SDK. Call the `authorize()` method with an [OAuth access token](oauth-api/overview) and location ID. If you're testing your application in the [Square Sandbox](devtools/sandbox/overview), you can use your personal access token and location ID from the **Sandbox** tab in the Developer Console.
{% aside type="important" %}
Don't deploy an application into production that contains your personal access token. For a secure authorization implementation in production, you should implement OAuth instead of using a personal access token.
{% /aside %}
When authorization completes, the `AuthorizeCompletionHandler` provides the result of the authorization, including any [errors](mobile-payments-sdk/ios/handling-errors).
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
func authorizeMobilePaymentsSDK(accessToken: String, locationID: String) {
guard MobilePaymentsSDK.shared.authorizationManager.state == .notAuthorized else {
return
}
MobilePaymentsSDK.shared.authorizationManager.authorize(
accessToken: accessToken,
locationID: locationID) { error in
if let authError = error {
// Handle auth error
print("error: \(authError.localizedDescription)")
return
}
print("Square Mobile Payments SDK successfully authorized.")
}
}
}
```
{% anchor id="request-location-bluetooth" /%}
## 5. Request location and Bluetooth permissions
The Mobile Payments SDK requires the user to grant access to the device's current location while using your application. This permission is required for payment, so you should only start a payment if you've determined that location access has been granted.
```swift
import CoreLocation
class <#YourViewController#>: UIViewController {
private lazy var locationManager = CLLocationManager()
// Call this in your app's lifecycle
func requestLocationPermission() {
switch CLLocationManager.authorizationStatus() {
case .notDetermined:
locationManager.requestWhenInUseAuthorization()
case .restricted, .denied:
print("Show UI directing the user to the iOS Settings app")
case .authorizedAlways, .authorizedWhenInUse:
print("Location services have already been authorized.")
@unknown default:
fatalError()
}
}
}
```
To use contactless readers (Square Reader for contactless and chip or Square Stand) with the SDK, you must request Bluetooth permission from users of your application. Use a method similar to the following `requestBluetoothPermissions()` method:
```swift
import CoreBluetooth
final class <#YourViewController#>: ViewController {
private var centralManager: CBCentralManager?
// Call this in your app's lifecycle
func requestBluetoothPermissions() {
guard CBManager.authorization == .notDetermined else {
return
}
centralManager = CBCentralManager(
delegate: self,
queue: .main,
options: nil
)
}
}
extension <#YourViewController#>: CBCentralManagerDelegate {
func centralManagerDidUpdateState(_ central: CBCentralManager) {
// Check state and prompt for permission if necessary
}
}
```
{% anchor id="mock-readers" /%}
## 6. Test with mock readers in the Square Sandbox
Physical card readers aren't supported in the Square Sandbox. To take test payments, you must simulate a virtual reader with the Mock Reader UI.
The Mock Reader UI consists of a floating button that can be dragged anywhere on the screen and persists as you navigate between screens in your application. Instantiate the Mock Reader UI and show the button with `try? self.mockReaderUI?.present()`.
```swift
import MockReaderUI
private lazy var mockReaderUI: MockReaderUI? = {
do {
return try MockReaderUI(for: MobilePaymentsSDK.shared)
} catch {
assertionFailure("Could not instantiate a mock reader UI: \(error.localizedDescription)")
}
return nil
}()
try? mockReaderUI?.present()
```
Click the following button to simulate connecting a magstripe reader or a contactless and chip reader to your device.
When mock readers have been connected and you [begin a payment](#begin-payment), click the button again to test your application's payment flow and simulate a swiped, inserted, or tapped card with the mock reader. Choose **Payment details** to select different card brands and payment behaviors (approved or declined) for testing purposes. To hide the mock reader UI in your application, call `self.mockReaderUI?.dismiss()`.
{% aside type="info" %}
When testing card payment flows, any inserted cards must be removed through the mock reader UI before beginning a new payment.
{% /aside %}
To pair physical readers for production payments, see [Pair and Manage Card Readers](mobile-payments-sdk/ios/pair-manage-readers).
## 7. Set up a payment
The `PaymentManager` handles payments in the Mobile Payments SDK. Prior to starting a payment, you create `PaymentParameters` to represent details of an individual payment and `PromptParameters` to indicate how the payment prompts are presented to the buyer.
When setting up a payment, you must conform to the `PaymentManagerDelegate` to [handle results and errors](mobile-payments-sdk/ios/handling-errors) from a payment. If the payment completes successfully, a `Payment` object is returned, which can be accessed on the [Sandbox Square Dashboard](testing/sandbox) or with the [Payments API](https://developer.squareup.com/reference/square/payments-api). If the payment fails, the response contains a `PaymentError`.
### Payment parameters
Before beginning a payment, create a `PaymentParameters` object. At a minimum, you must include the payment amount, a [payment attempt ID](mobile-payments-sdk/ios/take-payments#idempotency-and-payment-attempts), and the processing mode, which [determines whether payments can be taken offline](mobile-payments-sdk/ios/offline-payments). For the complete list of payment parameter values and details, see [iOS technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/ios).
### Prompt parameters
Each payment must also have `PromptParameters` configured, consisting of a `mode` and `additionalMethods` available to buyers.
Square provides a payment prompt screen that displays a UI to buyers prompting them to swipe, insert, or tap their card, depending on the payment options available. To use this screen for your quickstart application, set the `PromptParameters.mode` to `default`.
If you create your own custom payment prompt UI by passing `custom` in the `PromptParameters.mode`, use the `availableCardInputMethodsObserver` to update your UI if the available card entry methods change (for example, if a magstripe reader is inserted or removed from the mobile device).
{% anchor id="begin-payment" /%}
## 8. Take a payment
When you're ready to begin a payment, call `PaymentManager.startPayment()` with the `PaymentParameters` and `PromptParameters` you created for this payment.
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
private var paymentHandle: PaymentHandle?
func startPayment() {
paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(
makePaymentParameters(),
promptParameters: PromptParameters(
mode: .default,
additionalMethods: .all
),
from: self,
delegate: self
)
}
func makePaymentParameters() -> PaymentParameters {
PaymentParameters(
paymentAttemptID: UUID().uuidString,
amountMoney: Money(amount: 100, currency: .USD),
processingMode: processingMode.onlineOnly
)
}
}
extension <#YourViewController#>: PaymentManagerDelegate {
public func paymentManager(
_ paymentManager: PaymentManager,
didFinish payment: Payment
) {
print("Payment Did Finish: \(payment)")
}
public func paymentManager(
_ paymentManager: PaymentManager,
didFail payment: Payment,
withError error: Error
) {
// Handle Payment Failed
print("error: \(error.localizedDescription)")
}
public func paymentManager(
_ paymentManager: PaymentManager,
didCancel payment: Payment
) {
// Handle Payment Canceled
}
}
```
During each payment, Square takes control of the screen display to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer. While a payment is in progress, the `UIViewController` passed to `startPayment` must remain presented or pushed until your `PaymentManagerDelegate` receives a callback indicating the payment has completed, failed, or was canceled. After the payment starts, it cannot be canceled by the developer.
If the payment completes successfully, a `Payment` object is returned to your payment callback. This payment can be accessed on the Square Dashboard or with the [Payments API](https://developer.squareup.com/reference/square/payments-api). If the payment fails, the response contains an [error](mobile-payments-sdk/ios/handling-errors).
## Next steps
After installing the Mobile Payments SDK and testing your application with test payments in the Square Sandbox, learn more about configuring your application to take production payments:
* [Authorize the Mobile Payments SDK](mobile-payments-sdk/ios/configure-authorize#authorize)
* [Pair and Manage Card Readers](mobile-payments-sdk/ios/pair-manage-readers)
* [Take a Payment](mobile-payments-sdk/ios/take-payments)
[Context: Objective C, iOS]
## 3. Initialize the Mobile Payments SDK
Before taking a payment or attempting any other operation with the Mobile Payments SDK, you must initialize it using the `initialize()` method and your Square application ID in your `AppDelegate`'s `didFinishLaunchingWithOptions` method.
To get your application ID, sign in to the [Developer Console](https://developer.squareup.com/apps) and choose your application. If you don't have an application yet, see [Get Started](square-get-started) for steps to create a Square application.
Your application opens to the **Credentials** page. This page contains the Square application ID used to initialize the Mobile Payments SDK.
{% aside type="info" %}
To test the Mobile Payments SDK in the Square Sandbox with mock readers and mock payments, switch the toggle at the top of the Developer Console to **Sandbox** to show your Sandbox credentials and initialize the SDK with your Sandbox application ID. To start taking production payments, you must initialize the Mobile Payments SDK again with your production application ID.
{% /aside %}
```objectivec
#import "AppDelegate.h"
@import SquareMobilePaymentsSDK;
@interface AppDelegate ()
// …
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[SQMPMobilePaymentsSDK initializeWithApplicationLaunchOptions:launchOptions squareApplicationID:@"<#your_square_application_id#>"];
return YES;
}
}
```
## 4. Authorize the Mobile Payments SDK
The `SQMPAuthorizationManager` handles authorization for the Mobile Payments SDK. Call the `authorize()` method with an [OAuth access token](oauth-api/overview) and location ID. If you're testing your application in the [Square Sandbox](devtools/sandbox/overview), you can use your personal access token and location ID from the **Sandbox** tab in the Developer Console.
{% aside type="important" %}
Don't deploy an application into production that contains your personal access token. For a secure authorization implementation in production, you should implement OAuth instead of using a personal access token.
{% /aside %}
When authorization completes, the `AuthorizeCompletionHandler` provides the result of the authorization, including any [errors](mobile-payments-sdk/ios/handling-errors).
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
// …
@end
@implementation <#YourViewController#>
- (void)authorizeMobilePaymentsSDKWithAccessToken:(NSString *)accessToken locationID:(NSString *)locationID {
if (SQMPMobilePaymentsSDK.shared.authorizationManager.state != SQMPAuthorizationStateNotAuthorized) {
return;
}
[SQMPMobilePaymentsSDK.shared.authorizationManager authorizeWithAccessToken:accessToken locationID:locationID completion:^(NSError * _Nullable error) {
if (error == nil) {
NSLog(@"Square Mobile Payments SDK successfully authorized.");
} else {
// Handle auth error
NSLog(@"error: %@", error.localizedDescription);
}
}];
}
@end
```
{% anchor id="request-location-bluetooth" /%}
## 5. Request location and Bluetooth permissions
The Mobile Payments SDK requires the user to grant access to the device's current location while using your application. This permission is required for payment, so you should only start a payment if you've determined that location access has been granted.
```objectivec
#import
#import
@interface <#YourViewController#> : UIViewController
@property (nonatomic, strong) CLLocationManager *locationManager;
- (void)requestLocationPermission;
@end
@implementation <#YourViewController#>
- (instancetype)init {
self = [super init];
if (self) {
_locationManager = [[CLLocationManager alloc] init];
_locationManager.delegate = self;
}
return self;
}
// Call this in your app's lifecycle
- (void)requestLocationPermission {
CLAuthorizationStatus status = [CLLocationManager authorizationStatus];
switch (status) {
case kCLAuthorizationStatusNotDetermined:
[self.locationManager requestWhenInUseAuthorization];
break;
case kCLAuthorizationStatusRestricted:
case kCLAuthorizationStatusDenied:
NSLog(@"Show UI directing the user to the iOS Settings app");
break;
case kCLAuthorizationStatusAuthorizedAlways:
case kCLAuthorizationStatusAuthorizedWhenInUse:
NSLog(@"Location services have already been authorized.");
break;
default:
@throw [NSException exceptionWithName:NSInternalInconsistencyException
reason:@"Unknown authorization status"
userInfo:nil];
}
}
@end
```
To use contactless readers (Square Reader for contactless and chip or Square Stand) with the SDK, you must request Bluetooth permission from users of your application. Use a method similar to the following `requestBluetoothPermissions` method:
```objectivec
#import
#import
@interface <#YourViewController#> : UIViewController
@property (nonatomic, strong) CBCentralManager *centralManager;
- (void)requestBluetoothPermissions;
@end
@implementation <#YourViewController#>
// Call this in your app's lifecycle
- (void)requestBluetoothPermissions {
if (CBManager.authorization == CBManagerAuthorizationNotDetermined) {
self.centralManager = [[CBCentralManager alloc] initWithDelegate:self queue:dispatch_get_main_queue() options:nil];
}
}
- (void)centralManagerDidUpdateState:(CBCentralManager *)central {
// Check state and prompt for permission if necessary
}
@end
```
{% anchor id="mock-readers" /%}
## 6. Test with mock readers in the Square Sandbox
Physical card readers aren't supported in the Square Sandbox. To take test payments, you must simulate a virtual reader with the Mock Reader UI.
The Mock Reader UI consists of a floating button that can be dragged anywhere on the screen and persists as you navigate between screens in your application. See the following example for how to instantiate and present the Mock Reader UI:
```objectivec
@import MockReaderUI;
@interface ViewController ()
@property (strong, nonatomic) SQRDMockReaderUI *mockReaderUI;
@end
@implementation ViewController
- (void)testMockReaderUI
{
NSError *error = nil;
if (self.mockReaderUI == nil) {
self.mockReaderUI = [[SQRDMockReaderUI alloc] initFor:SQMPMobilePaymentsSDK.shared error:&error];
if (error != nil) {
NSLog(@"Mock Reader init Failed with error: %@", error);
}
}
if (self.mockReaderUI.isPresented == false) {
NSLog(@"Mock reader not presented. Calling present");
[self.mockReaderUI presentAndReturnError:&error];
if (error != nil) {
NSLog(@"Present Failed with error: %@", error);
}
} else {
NSLog(@"Mock reader already being presented");
}
}
@end
```
Click the following button to simulate connecting a magstripe reader or a contactless and chip reader to your device.
When mock readers have been connected and you [begin a payment](#begin-payment), click the button again to test your application's payment flow and simulate a swiped, inserted, or tapped card with the mock reader. Choose **Payment details** to select different card brands and payment behaviors (approved or declined) for testing purposes. To hide the mock reader UI in your application, call `[self.mockReaderUI dismiss]`.
{% aside type="info" %}
When testing card payment flows, any inserted cards must be removed through the mock reader UI before beginning a new payment.
{% /aside %}
To pair physical readers for production payments, see [Pair and Manage Card Readers](mobile-payments-sdk/ios/pair-manage-readers).
## 7. Set up a payment
The `SQMPPaymentManager` handles payments in the Mobile Payments SDK. Prior to starting a payment, you create `SQMPPaymentParameters` to represent details of an individual payment and `SQMPPromptParameters` to indicate how the payment prompts are presented to the buyer.
When setting up a payment, you must conform to the `SQMPPaymentManagerDelegate` to [handle results and errors](mobile-payments-sdk/ios/handling-errors) from a payment. If the payment completes successfully, a `Payment` object is returned, which can be accessed on the [Sandbox Square Dashboard](testing/sandbox) or with the [Payments API](https://developer.squareup.com/reference/square/payments-api). If the payment fails, the response contains a `PaymentError`.
### Payment parameters
Before beginning a payment, create a `SQMPPaymentParameters` object. At a minimum, you must include the payment amount, a [payment attempt ID](mobile-payments-sdk/ios/take-payments#idempotency-and-payment-attempts), and the processing mode, which [determines whether payments can be taken offline](mobile-payments-sdk/ios/offline-payments). For the complete list of payment parameter values and details, see [iOS technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/ios).
### Prompt parameters
Each payment must also have `SQMPPromptParameters` configured, consisting of a `mode` and `additionalMethods` available to buyers.
Square provides a payment prompt screen that displays a UI to buyers prompting them to swipe, insert, or tap their card, depending on the payment options available. To use this screen for your quickstart application, set the `SQMPPromptParameters.mode` to `default`.
If you create your own custom payment prompt UI by passing `custom` in the `PromptParameters.mode`, use the `availableCardInputMethodsObserver` to update your UI if the available card entry methods change (for example, if a magstripe reader is inserted or removed from the mobile device).
{% anchor id="begin-payment" /%}
## 8. Take a payment
When you're ready to begin a payment, call `PaymentManager.startPayment()` with the `SQMPPaymentParameters` and `SQMPPromptParameters` you created in the previous step.
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface ViewController ()
// ...
@end
@implementation <#YourViewController#>
- (void)startPayment {
id paymentHandle = [SQMPMobilePaymentsSDK.shared.paymentManager startPayment:[self makePaymentParameters]
promptParameters:[[SQMPPromptParameters alloc] initWithMode:SQMPPromptModeDefault
additionalMethods:SQMPAdditionalPaymentMethods.all]
from:self
delegate:self];
}
- (SQMPPaymentParameters *)makePaymentParameters
{
SQMPMoney *amountMoney = [[SQMPMoney alloc] initWithAmount:100
currency:SQMPCurrencyUSD];
NSString *paymentAttemptID = [[NSUUID UUID] UUIDString];
SQMPProcessingMode processingMode = SQMPProcessingModeOnlineOnly;
return [[SQMPPaymentParameters alloc] initWithPaymentAttemptID:paymentAttemptID
amountMoney:amountMoney
processingMode:processingMode];
}
- (void)paymentManager:(id)paymentManager didFinish:(id)payment
{
NSLog(@"Payment did finish: %@", payment);
}
- (void)paymentManager:(nonnull id)paymentManager didFail:(nonnull id)payment withError:(nonnull NSError *)error
{
NSLog(@"Payment did fail with error: %@", error.localizedDescription);
}
- (void)paymentManager:(id)paymentManager didCancel:(id)payment
{
NSLog(@"Payment did cancel");
}
@end
```
During each payment, Square takes control of the screen display to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer. While a payment is in progress, the `UIViewController` passed to `startPayment` must remain presented or pushed until your `PaymentManagerDelegate` receives a callback indicating the payment has completed, failed, or was canceled. After the payment starts, it cannot be canceled by the developer.
If the payment completes successfully, a `SQMPPayment` object is returned to your payment callback. This payment can be accessed on the Square Dashboard or with the [Payments API](https://developer.squareup.com/reference/square/payments-api). If the payment fails, the response contains an [error](mobile-payments-sdk/ios/handling-errors).
## Next steps
After installing the Mobile Payments SDK and testing your application with test payments in the Square Sandbox, learn more about configuring your application to take production payments:
* [Authorize the Mobile Payments SDK](mobile-payments-sdk/ios/configure-authorize#authorize)
* [Pair and Manage Card Readers](mobile-payments-sdk/ios/pair-manage-readers)
* [Take a Payment](mobile-payments-sdk/ios/take-payments)
---
# Build on Android
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android
> Status: PUBLIC
> Languages: All
> Platforms: Android
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Payments API](payments-refunds) | [OAuth API](oauth-api/overview)
{% subheading %}Learn how to build a secure in-person payment solution for Android devices with the Mobile Payments SDK.{% /subheading %}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK offers developers a secure way to integrate the Square checkout flow into their mobile applications and accept in-person payments with Square Readers.
There are four steps required to take your first payment using the Mobile Payments SDK:
1. [Install and configure the Mobile Payments SDK in your Android application](#install-sdk)
2. [Authorize the Mobile Payments SDK](mobile-payments-sdk/android/configure-authorize#authorize)
3. [Pair a card Reader](mobile-payments-sdk/android/pair-manage-readers)
4. [Take a payment](mobile-payments-sdk/android/take-payments)
For an example implementation, download the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-android), written in Kotlin using Compose.
## Requirements and limitations
* Your Square account is enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit [squareup.com/activation](https://squareup.com/activation).
* Your Square account is based in the United States, Canada, or Australia. If you're developing from outside these areas, you can take test payments in the Square Sandbox, but cannot take production payments.
* Your application's `minSdkVersion` is API 28 (Android 9) or later.
* Your application's `targetSdkVersion` is API 35 (Android 15) or a minimum of API 28 (Android 9).
* Your application's `compileSdkVersion` is 35.
* Your application uses AndroidX or enables [Jetifier](https://developer.android.com/jetpack/androidx#using_androidx) in `gradle.properties`.
* You're using the [Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) version 8.4.2 or later.
* Your version of the Mobile Payments SDK adheres to the Square update policy. To limit risk to developers and their users, Square enforces an [update policy](mobile-payments-sdk#update-policy) requiring developers keep their version of the Mobile Payments SDK current.
* When using Mobile Payments SDK version 2.1 or later, you must provide an [application signature](#application-signature) to Square before taking payments in production.
* You're generally familiar with developing applications on Android. If you're new to Android development, you should read the [Documentation on the Android Developers site](https://developer.android.com/guide) before continuing.
{% aside type="info" %}
The Mobile Payments SDK doesn't support Proguard for code optimization, as it might remove some critical bytecode from the library.
{% /aside %}
## Device permissions
The Mobile Payments SDK requires that the user grant access to their device’s current location while using your app. To use a Contactless and Chip reader to take card payments, Bluetooth must be enabled, and to use a magstripe reader, your application must be granted permission to access the device's microphone.
Ensure your application [requests](https://developer.android.com/training/permissions/requesting#request-permission) the following runtime permissions:
{% table %}
* Android device permission
* Purpose
---
* `ACCESS_FINE_LOCATION`
* To confirm that payments are occurring in a supported Square location.
---
* `RECORD_AUDIO`
* To receive data from magstripe readers.
---
* `BLUETOOTH_CONNECT`
* To receive data from contactless and chip readers.
---
* `BLUETOOTH_SCAN`
* To store information during checkout.
---
* `READ_PHONE_STATE`
* To identify the device sending information to Square servers.
{% /table %}
## Device compatibility
The Mobile Payments SDK isn't compatible with custom devices from original equipment manufacturers that violate Square's security rules or devices that grant root access to the mobile device operating system code and kernel. These devices cannot connect to a contactless and chip reader and don't comply with Square's security requirements.
The following additional considerations apply when trying to run the SDK on custom devices:
* The Mobile Payments SDK isn't supported for rooted devices or devices with custom ROMs.
* Square prohibits using any software that provides the ability to record or capture screen data or that results in elevated privileges.
* Square recommends running the Mobile Payments SDK on devices from large mobile device manufacturers such as Google or Samsung.
* If your mobile application runs on an uncommon device manufacturer, be sure to test the device with any expected software requirements, including Bluetooth connectivity, before investing in the device.
* Supported OS versions should be the latest or as close to the latest as possible.
* Review the Square support window for the OS version and confirm support for the compilation target version and the runtime version. The compilation target currently supports version 34. For runtime, the supported versions are 24 to 34.
## Application signature
Developers using the Mobile Payments SDK version 2.1 or later are required to submit an application signature to Square prior to taking payments in production. This signature is an extra layer of security that ensures that your application hasn't been tampered with or otherwise modified by a user.
To submit an application signature, log in to the Developer Console and choose your application. In the left pane, choose **Mobile Payments SDK**, and then choose **Add Signature**.
You must provide your **Package Name** and **Signing Key (SHA-256)** to Square. For more information, see [Android developer documentation on signing your app](https://developer.android.com/studio/publish/app-signing#api-providers).
If you publish a single mobile application used by multiple Square sellers using the same Square application id, you only need to submit one signature per platform for that application. Any debug builds you create that take payments in production also require their own application signature, since the signing key differs from your published application.
The **Mobile Payments SDK** page in the Developer Console lists each signature that you've submitted. If an application signature is deleted, the application is no longer able to take payments, but you can submit a new signature for your application at any time.
{% aside type="info" %}
If you're developing with the Mobile Payments SDK's [Flutter](mobile-payments-sdk/flutter) or [React Native](mobile-payments-sdk/react-native) plugins and publishing both an Android and iOS application, you must submit a signature for each application.
{% /aside %}
## Data privacy consent
To comply with data privacy laws, the Mobile Payments SDK requires merchants in Canada, the United Kingdom, and the European Union to grant or deny consent for performance and analytics tracking. Your application should prompt merchants in these regions for consent and log whether consent was granted or denied using `settingsManager.updateTrackingConsent(granted: Boolean)`.
Before processing payments, check the current state of consent for the authorized merchant.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val trackingConsentState = settingsManager.trackingConsentState
```
{% /tab %}
{% tab id="Java" %}
```java
ConsentState TrackingConsentState = settingsManager.getTrackingConsentState();
```
{% /tab %}
{% /tabset %}
The possible states are:
* `PENDING` - Consent has not yet been provided
* `GRANTED` - Merchant has granted consent for tracking
* `DENIED` - Merchant has denied consent for tracking
* `NOT_REQUIRED` - Merchant is in a region where consent is not required for tracking
If you don't implement consent handling via the API, the SDK automatically displays a consent dialog modal to users in regions where consent is required. This modal:
* appears on the first payment attempt or when the user first opens the [settings screen](mobile-payments-sdk/android/pair-manage-readers#settings-manager).
* is shown only once per application per device.
* is not displayed to users outside required regions.
{% aside type="important" %}
If you use a custom UI for your payment prompt screen and have not provided your user's consent status with the API, the SDK returns an error from `startPaymentActivity`. You must handle consent before initiating any payment when using a custom payment UI.
{% /aside %}
## Quickstart
Get started with the Mobile Payments SDK by configuring your Android application and taking a test payment in the Square Sandbox.
Use the following steps to set up and test the Mobile Payments SDK in your own application. You can also download the [Mobile SDK sample application](https://github.com/square/mobile-payments-sdk-android) (written in Kotlin) to see an example of initialization, authorization, and taking payments in production or the Square Sandbox.
{% anchor id="install-sdk" /%}
## 1. Install the SDK and dependencies
Add Square's Maven repo to your project's `settings.gradle` file and the following dependencies to your project's `build.gradle` file. The Mock Reader UI is used to [simulate virtual reader devices](#mockreader).
{% tabset %}
{% tab id="Kotlin" %}
`settings.gradle.kts`:
```gradle
...
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
...
maven ("https://sdk.squareup.com/public/android/")
}
}
...
```
`build.gradle.kts`:
```gradle
...
dependencies {
// Your dependencies
...
val squareSdkVersion = "2.4.0"
// Mobile Payments SDK dependency
implementation("com.squareup.sdk:mobile-payments-sdk:$squareSdkVersion")
// MockReader UI dependency
implementation("com.squareup.sdk:mockreader-ui:$squareSdkVersion")
}
```
{% /tab %}
{% tab id="Java" %}
`settings.gradle`:
```groovy
...
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
...
maven { url "https://sdk.squareup.com/public/android/" }
}
}
```
`build.gradle`:
```groovy
...
dependencies {
// Your dependencies
...
def squareSdkVersion = "2.4.0"
// Mobile Payments SDK dependency
implementation "com.squareup.sdk:mobile-payments-sdk:$squareSdkVersion"
// MockReader UI dependency
implementation "com.squareup.sdk:mockreader-ui:$squareSdkVersion"
}
```
{% /tab %}
{% /tabset %}
## 2. Initialize the Mobile Payments SDK
Before taking a payment or attempting any other operation with the Mobile Payments SDK, you must initialize it using the `initialize` method and your Square developer application ID. To get your application ID, sign in to the [Developer Console](https://developer.squareup.com/apps) and choose your application. If you don't have an application, see [Get Started](square-get-started) for steps to create a Square application.
Your application opens in the Developer Console to the **Credentials** page. This page contains your Square application ID used to initialize the Mobile Payments SDK.
{% aside type="info" %}
To test the Mobile Payments SDK in the Square Sandbox with mock readers and mock payments, switch the toggle at the top of the Developer Console to **Sandbox** to show your Sandbox credentials and initialize the SDK with your Sandbox application ID. To start taking production payments, you must initialize the Mobile Payments SDK again with your production application ID.
{% /aside %}
A good place to initialize the SDK is inside the `onCreate()` method of an [extended Application class](https://guides.codepath.com/android/Understanding-the-Android-Application-Class), because it's executed early in the application lifecycle.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
class DemoApplication : Application() {
override fun onCreate() {
super.onCreate()
MobilePaymentsSdk.initialize(getId(), this)
}
}
```
{% /tab %}
{% tab id="Java" %}
```java
public class DemoApplication extends Application {
@Override public void onCreate() {
super.onCreate();
MobilePaymentsSdk.initialize(getId(), this);
}
}
```
{% /tab %}
{% /tabset %}
If using the previous example, you should write your own implementation for `getId()` to return your application ID value from the Developer Console. Depending on your use case, this can be your production or Sandbox application ID, which might be stored as hardcoded strings, as Android resources, or fetched from your server.
## 3. Authorize the Mobile Payments SDK
The `AuthorizationManager` handles authorization for the Mobile Payments SDK. Call the `authorize()` method with an [OAuth access token](oauth-api/overview) and location ID. If you're testing your application in the [Square Sandbox](devtools/sandbox/overview), you can use your Sandbox personal access token and location ID.
{% aside type="important" %}
Don't deploy an application that contains your personal access token into production. For secure authorization in production, you should implement OAuth instead of using a personal access token.
{% /aside %}
In your call to `authorize()`, configure a callback to be notified of [authorization errors](mobile-payments-sdk/android/handling-errors) and display those to the user.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
override fun onResume() {
super.onResume()
val authorizationManager = MobilePaymentsSdk.authorizationManager()
// Authorize and handle authorization successes or failures
callbackReference = authorizationManager.authorize(accessToken, locationId) { result ->
when (result) {
is Success -> {
finishWithAuthorizedSuccess(result.value)
}
is Failure -> {
when (result.errorCode) {
NO_NETWORK -> showRetryDialog(result)
USAGE_ERROR -> showUsageErrorDialog(result)
}
}
}
}
}
override fun onPause() {
super.onPause()
// Remove the callback reference to prevent memory leaks
callbackReference?.clear()
}
```
{% /tab %}
{% tab id="Java" %}
```java
@Override protected void onResume() {
super.onResume();
AuthorizationManager authorizationManager = MobilePaymentsSdk.authorizationManager();
// Authorize and handle authorization successes or failures
callbackReference = authorizationManager.authorize(accessToken, locationId, result -> {
if (result.isSuccess()) {
finishWithAuthorizedSuccess(result.value());
} else {
AuthorizeErrorCode authorizeErrorCode = result.errorCode();
switch (authorizeErrorCode) {
case NO_NETWORK:
showRetryDialog(result);
break;
case USAGE_ERROR:
showUsageErrorDialog(result);
break;
}
}
});
}
@Override protected void onPause() {
super.onPause();
// Remove the callback reference to prevent memory leaks
callbackReference.clear();
}
```
{% /tab %}
{% /tabset %}
{% anchor id="mock-readers" /%}
## 4. Test with mock readers in the Square Sandbox
Physical card readers aren't supported in the Square Sandbox. To take test payments, you must simulate a virtual reader with the Mock Reader UI.
The Mock Reader UI automatically attaches a floating button to the currently displayed Activity as you navigate between screens in your application after you've called `MockReaderUI.show()`. The icon can be dragged anywhere on the screen and persists throughout your application lifecycle.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
override fun onCreate() {
super.onCreate()
// If in Sandbox - display Mock Reader floating icon
if (MobilePaymentsSdk.isSandboxEnvironment()) {
MockReaderUI.show()
}
}
// MockReader must hide once deauthorized as it should only be used within the Sandbox environment.
private fun deauthorize() {
MockReaderUI.hide()
}
```
{% /tab %}
{% tab id="Java" %}
```java
@Override protected void onCreate() {
super.onCreate();
// If in Sandbox - display Mock Reader floating icon
if (MobilePaymentsSdk.isSandboxEnvironment()) {
MockReaderUI.show();
}
}
// MockReader must hide once deauthorized as it should only be used within the Sandbox environment.
@Override private void deauthorize() {
MockReaderUI.hide();
}
```
{% /tab %}
{% /tabset %}
Click the following button to simulate connecting a magstripe reader or a contactless and chip reader to your device. You can use the `ReaderManager` to [programmatically access information](mobile-payments-sdk/android/pair-manage-readers#settings-manager) about these simulated readers, such as their model and available card entry methods.
When mock readers have been connected and you [begin a payment](#take-payment), click the button again to test your application's payment flow and simulate swiping, inserting, removing, or tapping a card with the mock reader. Choose **Payment details** to select different card brands and payment behaviors (approved or declined) for testing purposes. To hide the button in your application, call `MockReaderUI.hide()`.
{% aside type="info" %}
When testing card payment flows, any inserted cards must be removed through the mock reader UI before beginning a new payment.
{% /aside %}
To pair physical readers for production payments, see [Pair and Manage Card Readers](mobile-payments-sdk/android/pair-manage-readers).
## 5. Set up a payment
The `PaymentManager` handles payments in the Mobile Payments SDK. Prior to starting a payment, you create `PaymentParameters` to represent details of an individual payment and `PromptParameters` to indicate how the payment prompts are presented to the buyer.
### Payment parameters
Before beginning a payment, create a `PaymentParameters` object. At a minimum, you must include the payment amount, a [payment attempt ID](mobile-payments-sdk/android/take-payments#idempotency-and-payment-attempts), and the processing mode, which [determines whether payments can be taken offline](mobile-payments-sdk/android/offline-payments#take-a-payment-offline). For the complete list of payment parameter values and details, see [Android technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/android).
### Prompt parameters
Each payment also requires `PromptParameters`, consisting of a `mode` and `additionalPaymentMethods` available to buyers. The current options are `KEYED` (a manually entered credit card payment) or `CASH`.
Square provides a payment prompt screen that displays a UI prompting buyers to swipe, tap, or insert their card, depending on the payment options available. To use this screen, set `PromptParameters.mode` to `DEFAULT`. If you want to create your own custom payment prompt screen instead of using the default, set `PromptParameters.mode` to `CUSTOM`.
If you create your own custom payment prompt UI, use the `setAvailableCardEntryMethodChangedCallback` to update your UI if the available card entry methods change (for example, if a magstripe reader is inserted or removed from the mobile device). You should set this callback in either a `ViewModel` or an Activity’s `onCreate()` or `onResume()` method.
{% anchor id="take-payment" /%}
## 6. Take a payment
When you're ready to begin a payment, call `paymentManager.startPaymentActivity()` with the `PaymentParameters` and `PromptParameters` you created for this payment, along with a `callback` to notify you of the payment's success or failure.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun startPaymentActivity() {
val paymentManager = MobilePaymentsSdk.paymentManager()
// Configure the payment parameters
val paymentParams = PaymentParameters.Builder(
amount = Money(100, CurrencyCode.USD),
paymentAttemptId = UUID.randomUUID().toString(),
processingMode = processingMode(ProcessingMode.ONLINE_ONLY)
)
.referenceId("1234")
.note("Chocolate Cookies and Lemonade")
.autocomplete(true)
.build()
// Configure the prompt parameters
val promptParams = PromptParameters(
mode = PromptMode.DEFAULT,
additionalPaymentMethods = listOf(Type.KEYED)
)
// Start the payment activity
handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
// Callback to handle the payment result
when (result) {
is Success -> // show payment details
is Failure -> // show error message
}
}
}
override fun onDestroy() {
handle?.cancel()
...
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void startPaymentActivity() {
PaymentManager paymentManager = MobilePaymentsSdk.paymentManager();
// Configure the payment parameters
PaymentParameters paymentParams = new PaymentParameters.Builder(
new Money(100, CurrencyCode.USD),
UUID.randomUUID().toString(),
ProcessingMode.ONLINE_ONLY
)
.referenceId("1234")
.note("Chocolate Cookies and Lemonade")
.autocomplete(true)
.build();
// Configure the prompt parameters
PromptParameters promptParams = new PromptParameters(
PromptMode.DEFAULT,
Collections.singletonList(AdditionalPaymentMethod.Type.KEYED)
);
// Start the payment activity
paymentHandle = paymentManager.startPaymentActivity(paymentParams, promptParams, result -> {
// Handle the payment result
if (result.isSuccess()) {
// show payment details
...
} else {
// show error message
...
}
});
}
@Override public void onDestroy() {
if (paymentHandle != null) {
paymentHandle.cancel();
}
...
}
```
{% /tab %}
{% /tabset %}
During a payment, Square takes control of the screen display as another Android Activity to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer.
If the payment completes successfully, a `Payment` object is returned to your payment callback. This payment can be accessed on the Square Dashboard or with the [Payments API](https://developer.squareup.com/reference/square/payments-api). If the payment fails, the response contains a `PaymentError`.
## Next steps
After installing the Mobile Payments SDK and testing your application with test payments in the Square Sandbox, learn more about configuring your application to take production payments.
* [Authorize your Android Application](mobile-payments-sdk/android/configure-authorize)
* [Pair and Manage Card Readers](mobile-payments-sdk/android/pair-manage-readers)
* [Take a Payment](mobile-payments-sdk/android/take-payments)
---
# Authorize the Mobile Payments SDK
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/configure-authorize
> Status: PUBLIC
> Languages: Swift, Objective C
> Platforms: iOS
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [OAuth API](oauth-api/overview) | [Locations API](locations-api)
{% subheading %}Learn how to configure and authorize your Mobile Payments SDK iOS application.{% /subheading %}
{% line-break /%}
[Context: Swift, iOS]
{% toc hide=true /%}
## Overview
To enable your application to securely connect to a Square seller account, the Mobile Payments SDK must be authorized using an [OAuth access token](oauth-api/what-it-does) and a [location ID](locations-api). Each Square seller who uses your application must be authorized with an OAuth access token The same process should be used even if you only plan to use the Mobile Payments SDK with your own Square account. To get started, see [OAuth documentation](oauth-api/overview) and the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-ios) for an example of how to authorize the SDK.
When requesting an OAuth access token from a seller, your application must request the following permissions:
* `MERCHANT_PROFILE_READ` is required to get a list of all a seller's locations.
* `PAYMENTS_WRITE` and `PAYMENTS_WRITE_IN_PERSON` are required to take payments with the Mobile Payments SDK.
* `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` is required only if you want to collect [application fees](payments-api/take-payments-and-collect-fees).
* `EMPLOYEES_READ` is required if you want to associate a payment with a particular `teamMemberId`.
When displaying the Square authorization page, it’s recommended to use [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) instead of [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview). `WKWebView` can be used if it's required for the look and feel of your application, but using `SFSafariViewController` is a better supported and stable experience. For information about when to use `SFSafariViewController` rather than `WKWebView`, see [Apple's guidance](https://developer.apple.com/news/?id=trjs0tcd).
The Mobile Payments SDK is divided into [four managers](mobile-payments-sdk#mobile-payments-sdk-components) to provide specific areas of functionality. Authorization is handled by the `AuthorizationManager`. In your application's authorization or bootstrapping logic, use the `AuthorizationManager`'s `authorize()` function to authorize the Mobile Payments SDK with the OAuth access token and location ID for the Square seller connecting to your application. When authorization completes, the `AuthorizeCompletionHandler` provides the result of the authorization, including any errors.
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
func authorizeMobilePaymentsSDK(accessToken: String, locationID: String) {
guard MobilePaymentsSDK.shared.authorizationManager.state == .notAuthorized else {
return
}
MobilePaymentsSDK.shared.authorizationManager.authorize(
withAccessToken: accessToken,
locationID: locationID) { error in
guard let authError = error else {
print("Square Mobile Payments SDK successfully authorized.")
return
}
// Handle auth error
print("error: \(authError.localizedDescription)")
}
}
}
```
## Authorization state
You can check whether a user of your application is `authorized`, `notAuthorized`, or (in the process of) `authorizing` by checking `AuthorizationManager.state` prior to beginning authorization.
To track changes in the authorization state, add an `AuthorizationStateObserver` to your `viewController` to receive updates to the authorization `state` whenever the Mobile Payments SDK is authorized or deauthorized.
### Session expiration
Square OAuth access tokens expire after 30 days. After expiration, applications must generate a new OAuth access token using the refresh token received [when the authorization was first granted](oauth-api/how-oauth-works). The response looks like the following:
```json
{
"access_token": "EAAAEL_EXAMPLE_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n",
"token_type": "bearer",
"expires_at": "2024-05-15T19:36:00Z",
"merchant_id": "ML61OXvVbScCI",
"refresh_token": "EXAMPLEzRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9"
}
```
Square recommends tracking the `expires_at` value on your server and refreshing the authorization token before it expires. You can store expiration time on the device and check it during application initialization.
If the SDK detects an expired token, it deauthorizes the Square seller account (in the same manner as calling `AuthorizationManager.deauthorize()`) and your `AuthorizationStateObserver` is notified of the change in state.
### Deauthorize the Mobile Payments SDK
To deauthorize the Mobile Payments SDK and sign out of a seller's Square account, use the Authorization Manager's `deauthorize()` method. This method provides a `DeauthorizeCompletionHandler`, called when the SDK finishes deauthorizing.
It's a good idea to call this method when a user logs out of your application or hasn't had any activity within a period of time. This prevents your application from having to track a large number of dangling authorizations.
```swift
func deauthorizeMobilePaymentsSDK() {
MobilePaymentsSDK.shared.authorizationManager.deauthorize {
// Check authorization status
print(MobilePaymentsSDK.shared.authorizationManager.state)
}
}
```
## Next steps
After the Mobile Payments SDK is installed and initialized in your mobile application and authorized with a Square account, you're ready to [pair and manage card readers](mobile-payments-sdk/ios/pair-manage-readers).
[Context: Objective C, iOS]
{% toc hide=true /%}
## Overview
To enable your application to securely connect to a Square seller account, the Mobile Payments SDK must be authorized using an [OAuth access token](oauth-api/what-it-does) and a [location ID](locations-api). Each Square seller who uses your application must be authorized with an OAuth access token The same process should be used even if you only plan to use the Mobile Payments SDK with your own Square account. To get started, see [OAuth documentation](oauth-api/overview) and the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-ios) for an example of how to authorize the SDK.
When requesting an OAuth access token from a seller, your application must request the following permissions:
* `MERCHANT_PROFILE_READ` is required to get a list of all a seller's locations.
* `PAYMENTS_WRITE` and `PAYMENTS_WRITE_IN_PERSON` are required to take payments with the Mobile Payments SDK.
* `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` is required only if you want to collect [application fees](payments-api/take-payments-and-collect-fees).
* `EMPLOYEES_READ` is required if you want to associate a payment with a particular `teamMemberId`.
When displaying the Square authorization page, it’s recommended to use [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) instead of [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview). `WKWebView` can be used if it's required for the look and feel of your application, but using `SFSafariViewController` is a better supported and stable experience. For information about when to use `SFSafariViewController` rather than `WKWebView`, see [Apple's guidance](https://developer.apple.com/news/?id=trjs0tcd).
The Mobile Payments SDK is divided into [four managers](mobile-payments-sdk#mobile-payments-sdk-components) to provide specific areas of functionality. Authorization is handled by the `SQMPAuthorizationManager`. In your application's authorization or bootstrapping logic, use the `AuthorizationManager`'s `authorize()` function to authorize the Mobile Payments SDK with the OAuth access token and location ID for the Square seller connecting to your application. When authorization completes, the `AuthorizeCompletionHandler` provides the result of the authorization, including any errors.
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
// …
@end
@implementation <#YourViewController#>
- (void)authorizeMobilePaymentsSDKWithAccessToken:(NSString *)accessToken locationID:(NSString *)locationID {
if (SQMPMobilePaymentsSDK.shared.authorizationManager.state != SQMPAuthorizationStateNotAuthorized) {
return;
}
[SQMPMobilePaymentsSDK.shared.authorizationManager authorizeWithAccessToken:accessToken locationID:locationID completion:^(NSError * _Nullable error) {
if (error == nil) {
NSLog(@"Square Mobile Payments SDK successfully authorized.");
} else {
// Handle auth error
NSLog(@"error: %@", error.localizedDescription);
}
}];
}
@end
```
## Authorization state
You can check whether a user of your application is `authorized`, `notAuthorized`, or (in the process of) `authorizing` by checking `SQMPAuthorizationManager.state` prior to beginning authorization.
To track changes in the authorization state, add an `SQMPAuthorizationStatusObserver` to your `viewController` to receive updates to the authorization `state` whenever the Mobile Payments SDK is authorized or deauthorized.
### Session expiration
Square OAuth access tokens expire after 30 days. After expiration, applications must generate a new OAuth access token using the refresh token received [when the authorization was first granted](oauth-api/how-oauth-works). The response looks like the following:
```json
{
"access_token": "EAAAEL_EXAMPLE_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n",
"token_type": "bearer",
"expires_at": "2024-05-15T19:36:00Z",
"merchant_id": "ML61OXvVbScCI",
"refresh_token": "EXAMPLEzRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9"
}
```
Square recommends tracking the `expires_at` value on your server and refreshing the authorization token before it expires. You can store expiration time on the device and check it during application initialization.
If the SDK detects an expired token, it deauthorizes the Square seller account (in the same manner as calling `AuthorizationManager.deauthorize()`) and your `AuthorizationStateObserver` is notified of the change in state.
### Deauthorize the Mobile Payments SDK
To deauthorize the Mobile Payments SDK and sign out of a seller's Square account, use the Authorization Manager's `deauthorize()` method. This method provides a `DeauthorizeCompletionHandler`, called when the SDK finishes deauthorizing.
It's a good idea to call this method when a user logs out of your application or hasn't had any activity within a period of time. This prevents your application from having to track a large number of dangling authorizations.
```objectivec
- (void)deauthorizeMobilePaymentsSDK {
[SQMPMobilePaymentsSDK.shared.authorizationManager deauthorizeWithCompletion:^{
// Check authorization status
SQMPAuthorizationState state = SQMPMobilePaymentsSDK.shared.authorizationManager.state;
NSLog(@"%ld", (long)state);
}];
}
```
## Next steps
After the Mobile Payments SDK is installed and initialized in your mobile application and authorized with a Square account, you're ready to [pair and manage card readers](mobile-payments-sdk/ios/pair-manage-readers).
---
# Pair and Manage Card Readers
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/pair-manage-readers
> Status: PUBLIC
> Languages: All
> Platforms: iOS
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [OAuth API](oauth-api/overview) | [Locations API](locations-api)
{% subheading %}Learn how to pair and manage card readers with the Mobile Payments SDK for iOS.{% /subheading %}
{% line-break /%}
[Context: Swift, iOS]
{% toc hide=true /%}
## Overview
The Mobile Payments SDK's `ReaderManager` lets you pair and monitor changes in Square readers.
## Requirements and limitations
* To successfully pair a contactless reader and take payments, your application must [request location and Bluetooth permissions](mobile-payments-sdk/ios#request-location-bluetooth) from the user.
* Physical reader devices cannot be used in the Square Sandbox. For testing purposes, you can use the [Mock Reader UI](mobile-payments-sdk/ios#mock-readers) to pair simulated readers and process mock payments with your application in the Square Sandbox.
## Settings Manager
The Mobile Payments SDK offers a pre-made reader settings screen you can use in your application by calling `MobilePaymentsSDK.shared.settingsManager.presentSettings(viewController: self) { _ in }`. This screen includes two tabs. The **Devices** tab displays the model and connection status for readers paired to the seller's phone or tablet and includes a button for pairing a new reader. The **About** tab displays information about the Mobile Payments SDK, authorized location, and environment used to take payments. Users can also enable or disable consent for [performance and analytics tracking](mobile-payments-sdk/ios#data-privacy-consent) from this screen, if they are in a region where consent is required.
Use the `settingsManager.sdkSettings` to programmatically retrieve information about the current `environment` (either `production` or `sandbox`) and the current `version`.
You can check whether the settings screen is currently displayed with `settingsManager.isSettingsPresented` and programmatically dismiss it with `settingsManager.dismissSettings()`. This is useful for kiosks, or when your application needs to respond to external events while settings are open.
With the `SettingsManager`, you can also view `PaymentSettings` for the Square seller authenticated to your application, such as whether they have the ability to [take payments offline](/mobile-payments-sdk/ios/offline-payments).
## Reader Manager
If you want more control over your reader pairing and management screens, you can create your own using information from the Mobile Payments SDK's `ReaderManager`. This manager provides methods for pairing and forgetting readers, accessing information about a particular reader, and listening for reader status updates.
### Pairing a reader
Square Readers for magstripe are automatically detected by the Mobile Payments SDK as they are inserted or removed from a device's connection port and don't need to be paired. Likewise, the [Square Stand](mobile-payments-sdk/ios/square-stand) includes a built-in reader device and doesn't need an external reader paired to take payments. Square readers for contactless and chip must be paired with the Mobile Payments SDK using the `ReaderManager`.
To start searching for nearby Bluetooth readers, call `readerManager.startPairing(with:)`, passing in a `ReaderPairingDelegate`, which is notified when reader pairing begins and whether the pairing succeeded or failed.
During pairing, a `PairingHandle` is returned and can be used to stop the pairing in progress. You should call `PairingHandle.stop()` any time a user leaves the screen from which they're attempting to pair a reader.
When pairing is successful, the paired reader is added to the array of available readers accessed with `readerManager.readers`. If the pairing fails, the delegate's `readerPairingDidFail` method returns an [error](mobile-payments-sdk/ios/handling-errors) you can use to troubleshoot and attempt pairing again. Only one reader pairing can be in progress at one time, so before calling `startPairing`, check the Boolean value `readerManager.isPairingInProgress` and only begin pairing if it's `false`.
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
private var pairingHandle: PairingHandle?
func startPairing() {
// `self` must conform to ReaderPairingDelegate
pairingHandle = MobilePaymentsSDK.shared.readerManager.startPairing(with: self)
}
func stopPairing() {
// Manually stop searching for nearby readers.
pairingHandle?.stop()
}
}
extension <#YourViewController#>: ReaderPairingDelegate {
func readerPairingDidBegin() {
print("Reader pairing did begin!")
}
func readerPairingDidSucceed() {
print("Reader Paired!")
}
func readerPairingDidFail(with error: Error) {
// Handle pairing error
print("Error: \(error.localizedDescription)")
}
}
```
## Reader information
The `ReaderInfo` class provides information about Square readers and stands paired with your application. These properties include:
* The battery level and charging status.
* The model (`contactlessAndChip`, `magstripe`, or `stand`).
* The serial number.
* The firmware including version and update status (see [Firmware info](#firmware-info)).
* The card entry methods supported by the reader (`TAP`, `DIP`, or `SWIPE`).
* The [Reader status](#reader-status).
You can use this information to send notifications to users of your application when a reader is unpaired or its battery is low. In case of a [pairing error](mobile-payments-sdk/ios/handling-errors), you can use `connectionInfo.failureReason` to provide more details and suggestions to your application users about how to retry their pairing attempt.
### Getting reader updates
The Mobile Payments SDK reports changes to connected readers to any subscribed observers. An observer must conform to the `ReaderObserver` protocol and receives notifications when:
* A reader starts or stops charging.
* A reader's battery level changes.
* [Reader status](#reader-status) changes (for example, starts connecting or becomes ready to take payments).
* Firmware update status or firmware update time changes.
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
// Add this class as an observer to receive reader updates.
MobilePaymentsSDK.shared.readerManager.add(self)
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
MobilePaymentsSDK.shared.readerManager.remove(self)
}
}
extension <#YourViewController#>: ReaderObserver {
func readerWasAdded(_ readerInfo: ReaderInfo) {
print("Reader Added!")
}
func readerWasRemoved(_ readerInfo: ReaderInfo) {
print("Reader Removed!")
}
func readerDidChange(_ readerInfo: ReaderInfo, change: ReaderChange) {
switch change {
case .batteryDidBeginCharging:
print("Reader is charging.")
case .batteryDidEndCharging:
print("Reader not charging")
case .batteryLevelDidChange:
print("Reader battery changed to: \(readerInfo.batteryStatus!.level)")
case .statusDidChange:
print("Reader status changed to:\(readerInfo.statusInfo.status)")
@unknown default:
// Handle other `ReaderChange` events here.
print(change)
}
}
}
```
### Card input methods
Different reader devices offer different card entry methods. Square Reader for magstripe can only accept swiped cards, while Square Reader for contactless and chip can accept tapped or dipped cards. The card entry methods supported are available within the `ReaderInfo` `supportedInputMethods`. However, this list isn't updated if the available entry methods change (for example, if the NFC connection to a contactless reader times out). Your application should add an `AvailableCardInputMethodsObserver` to be notified when the available input methods change.
Before taking a payment, your application should display the available payment methods to customers as a prompt to swipe, insert, or tap their card to pay. The SDK provides a prebuilt [payment prompt screen](mobile-payments-sdk/ios/take-payments#create-prompt-parameters) you can use instead of creating a custom prompt. If you want to create your own payment prompt screen, your application should query the `PaymentManager` `availableCardInputMethods` method and display the available payment methods to buyers.
```swift
import SquareMobilePaymentsSDK
import UIKit
class <#YourViewController#>: AvailableCardInputMethodsObserver {
var availableCardInputMethods = MobilePaymentsSDK.shared.paymentManager.availableCardInputMethods
func viewDidLoad() {
// Add this class as an observer to receive updates to
// available card input methods.
MobilePaymentsSDK.shared.paymentManager.add(self)
}
public func availableCardInputMethodsDidChange(_ cardInputMethods: CardInputMethods) {
availableCardInputMethods = cardInputMethods
if availableCardInputMethods.isEmpty {
print("No card readers connected.")
} else {
print("Available card input methods: \(cardInputMethods)")
}
}
}
```
### Reader status
Your application can check the current status of connected readers with `ReaderInfo.statusInfo` to display updates and messages to users. The `statusInfo` property returns a `ReaderStatusInfo` object that contains the reader's current status and additional context. The `statusInfo.status` property indicates the reader's current state. The possible values are:
* `ready`: The reader is paired, connected, and able to accept card payments.
* Magstripe readers connect automatically and are always `ready` until physically disconnected from the mobile device.
* `connectingToSquare`: The reader is establishing a connection to Square's servers.
* `connectingToDevice`: The reader is establishing a connection to the mobile device.
* `faulty`: The reader has encountered a hardware or connection error and is in an unrecoverable state.
* `readerUnavailable`: The reader is connected but not able to take payments.
If a reader is unavailable, check `statusInfo.unavailableReasonInfo` for specific details, which may include bluetooth failure, a blocking firmware update, or issues with the merchant’s Square account. Depending on the reason, you can prompt the user to take action, or retry the connection with Square's servers with `readerManager.retryConnection()`.
{% aside type="info" %}
`readerInfo.status` is available in iOS Mobile Payments SDK version `2.3.0` and above. If your integration uses an earlier version of the SDK, monitor the status of connected readers with `readerInfo.state`. The available states are `connecting`, `updatingFirmware`, `disconnected`, or `failedToConnect`.
{% /aside %}
```swift
import SquareMobilePaymentsSDK
extension <#YourViewController#> {
func readyReaderCount() -> Int {
// You can access all connected readers via
// `MobilePaymentsSDK.shared.readerManager.readers`
MobilePaymentsSDK.shared.readerManager.readers.filter {
$0.statusInfo.status == .ready
}.count
}
func hasReadyReader() -> Bool {
MobilePaymentsSDK.shared.readerManager.readers.contains {
$0.statusInfo.status == .ready
}
}
}
```
### Firmware info
The `ReaderInfo.firmwareInfo` property provides structured firmware data through the `ReaderFirmwareInfo` class, which includes:
* `updateStatus: FirmwareUpdateStatus` — The current firmware update status, represented as an enum with the following cases:
- `.none` — No firmware update is available or in progress.
- `.pending` — A firmware update is scheduled.
- `.inProgress` — A firmware update is currently being installed.
- `.failed` — A firmware update failed.
* `updateTime: Date?` — The scheduled time for the next firmware update, if one is pending.
```swift
import SquareMobilePaymentsSDK
extension <#YourViewController#> {
func checkFirmwareStatus() {
for reader in MobilePaymentsSDK.shared.readerManager.readers {
let firmwareInfo = reader.firmwareInfo
print("Firmware version: \(firmwareInfo.version ?? "unknown")")
switch firmwareInfo.updateStatus {
case .none:
print("Firmware is up to date")
case .pending:
if let updateTime = firmwareInfo.updateTime {
print("Update scheduled for: \(updateTime)")
}
case .inProgress:
print("Firmware update in progress")
case .failed:
print("Firmware update failed")
@unknown default:
break
}
}
}
}
```
### Preferred firmware update time
You can schedule firmware updates to occur at a preferred time of day using `readerSettings.preferredFirmwareUpdateTime`. This property accepts a `TimeOfDay` value with `hour` (0–23) and `minute` (0–59) properties. Setting this value allows sellers to schedule reader firmware updates during off-hours to avoid interruptions during business operations.
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController, ReaderSettingsObserver {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
MobilePaymentsSDK.shared.readerManager.readerSettings.add(self)
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
MobilePaymentsSDK.shared.readerManager.readerSettings.remove(self)
}
func setFirmwareUpdateTime() {
// Schedule firmware updates for 2:00 AM
if let time = TimeOfDay(hour: 2, minute: 0) {
MobilePaymentsSDK.shared.readerManager.readerSettings.preferredFirmwareUpdateTime = time
}
}
// MARK: - ReaderSettingsObserver
func readerSettingsDidChange() {
print("Reader settings changed")
}
}
```
### Unpairing a reader
Paired contactless and chip readers are remembered by the Mobile Payments SDK. When a new card reader is paired to the application, it remains paired until forgotten with the `ReaderManager`'s `forget(reader)` method.
## Next steps
To test your application in the Square Sandbox without a physical Square Reader device, use the Mobile Payments SDK [Mock Reader UI](mobile-payments-sdk/ios#mock-readers) to simulate a reader and accept test payments. Otherwise, after you've paired a physical Square Reader device, you're ready to [take payments](mobile-payments-sdk/ios/take-payments) in a production environment.
[Context: Objective C, iOS]
{% toc hide=true /%}
## Overview
The Mobile Payments SDK's `ReaderManager` lets you pair and monitor changes in Square readers.
## Requirements and limitations
* To successfully pair a contactless reader and take payments, your application must [request location and Bluetooth permissions](mobile-payments-sdk/ios#request-location-bluetooth) from the user.
* Physical reader devices cannot be used in the Square Sandbox. For testing purposes, you can use the [Mock Reader UI](mobile-payments-sdk/ios#mock-readers) to pair simulated readers and process mock payments with your application in the Square Sandbox.
## Settings Manager
The Mobile Payments SDK offers a pre-made reader settings screen you can use in your application by calling `SQMPSettingsManager.presentSettings()`. This screen includes two tabs. The **Devices** tab displays the model and connection status for readers paired to the sellers's phone or tablet and includes a button for pairing a new reader. The **About** tab displays information about the Mobile Payments SDK, authorized location, and environment used to take payments. Users can also enable or disable consent for [performance and analytics tracking](mobile-payments-sdk/ios#data-privacy-consent) from this screen, if they are in a region where consent is required.
Use the `SQMPSettingsManager.sdkSettings` to programmatically retrieve information about the current `environment` (either `production` or `sandbox`) and the current `version`.
With the `SettingsManager`, you can also view `PaymentSettings` for the Square seller authenticated to your application, such as whether they have the ability to [take payments offline](/mobile-payments-sdk/ios/offline-payments).
You can check whether the settings screen is currently displayed with `settingsManager.isSettingsPresented` and programmatically dismiss it with `settingsManager.dismissSettings()`. This is useful for kiosk mode or when your application needs to respond to external events while settings are open.
## Reader Manager
If you want more control over your reader pairing and management screens, you can create your own using information from the Mobile Payments SDK `SQMPReaderManager`. This manager provides methods for pairing and forgetting readers, accessing information about a particular reader, and listening for reader status updates.
### Pairing a reader
Square Readers for magstripe are automatically detected by the Mobile Payments SDK as they are inserted or removed from a device's connection port and don't need to be paired. Likewise, the [Square Stand](mobile-payments-sdk/ios/square-stand) includes a built-in reader device and doesn't need an external reader paired to take payments. Square readers for contactless and chip must be paired with the Mobile Payments SDK using the `ReaderManager`.
To start searching for nearby Bluetooth readers, call `readerManager.startPairing(with:)`, passing in a `ReaderPairingDelegate`, which is notified when reader pairing begins and whether the pairing succeeded or failed.
During pairing, a `PairingHandle` is returned and can be used to stop the pairing in progress. You should call `PairingHandle.stop()` any time a user leaves the screen from which they're attempting to pair a reader.
When pairing is successful, the paired reader is added to the array of available readers accessed with `readerManager.readers`. If the pairing fails, the delegate's `readerPairingDidFail` method returns an [error](mobile-payments-sdk/ios/handling-errors) you can use to troubleshoot and attempt pairing again. Only one reader pairing can be in progress at one time, so before calling `startPairing`, check the Boolean value `readerManager.isPairingInProgress` and only begin pairing if it's `false`.
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
@property (nonatomic, strong) id pairingHandle;
- (void)startPairing;
- (void)stopPairing;
@end
@implementation <#YourViewController#>
- (void)startPairing {
// `self` must conform to SQMPReaderPairingDelegate
self.pairingHandle = [SQMPMobilePaymentsSDK.shared.readerManager startPairingWith:self];
}
- (void)stopPairing {
// Manually stop searching for nearby readers.
[self.pairingHandle stop];
}
#pragma mark - SQMPReaderPairingDelegate
- (void)readerPairingDidBegin {
NSLog(@"Reader pairing did begin!");
}
- (void)readerPairingDidSucceed {
NSLog(@"Reader Paired!");
}
- (void)readerPairingDidFailWith:(NSError * _Nonnull)error {
// Handle pairing error
NSLog(@"Error: %@", error.localizedDescription);
}
@end
```
## Reader information
The `SQMPReaderInfo` class provides information about Square readers and stands paired with your application. These properties include:
* The battery level and charging status.
* The model (`contactlessAndChip`, `magstripe`, or `stand`).
* The serial number.
* The firmware info, including version and update status.
* The connection type (`unknown`, `usb`, `bluetooth`, `embedded`, or `audio`).
* The card entry methods supported by the reader (`TAP`, `DIP`, or `SWIPE`).
You can use this information to send notifications to users of your application when a reader is unpaired or its battery is low. In case of a [pairing error](mobile-payments-sdk/ios/handling-errors), you can use `connectionInfo.failureReason` to provide more details and suggestions to your application users about how to retry their pairing attempt.
### Getting reader updates
The Mobile Payments SDK reports changes to connected readers to any subscribed observers. An observer must conform to the `SQMPReaderObserver` protocol and receives notifications when:
* A reader starts or stops charging.
* A reader's battery level changes.
* [Reader status](#reader-status) changes (for example, starts connecting or becomes ready to take payments).
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
@end
@implementation <#YourViewController#>
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
// Add this class as an observer to receive reader updates.
[SQMPMobilePaymentsSDK.shared.readerManager add:self];
}
- (void)viewDidDisappear:(BOOL)animated {
[super viewDidDisappear:animated];
[SQMPMobilePaymentsSDK.shared.readerManager remove:self];
}
#pragma mark - SQMPReaderObserver
- (void)readerWasAdded:(id _Nonnull)readerInfo {
NSLog(@"Reader Added!");
}
- (void)readerWasRemoved:(id _Nonnull)readerInfo {
NSLog(@"Reader Removed!");
}
- (void)readerDidChange:(id _Nonnull)readerInfo change:(enum SQMPReaderChange)change {
switch (change) {
case SQMPReaderChangeBatteryDidBeginCharging:
NSLog(@"Reader is charging.");
break;
case SQMPReaderChangeBatteryDidEndCharging:
NSLog(@"Reader not charging");
break;
case SQMPReaderChangeBatteryLevelDidChange:
NSLog(@"Reader battery changed to: %ld", (long)readerInfo.batteryStatus.level);
break;
case SQMPReaderChangeStatusDidChange:
NSLog(@"Reader status changed to: %ld", (long)readerInfo.status);
break;
default:
// Handle other `SQMPReaderChange` events here.
NSLog(@"Unknown change: %ld", (long)change);
break;
}
}
@end
```
### Card input methods
Different reader devices offer different card entry methods. Square Reader for magstripe can only accept swiped cards, while Square Reader for contactless and chip can accept tapped or dipped cards. The card entry methods supported are available within the `ReaderInfo` `supportedInputMethods`. However, this list isn't updated if the available entry methods change (for example, if the NFC connection to a contactless reader times out). Your application should add an `SQMPAvailableCardInputMethodsObserver` to be notified when the available input methods change.
Before taking a payment, your application should display the available payment methods to customers as a prompt to swipe, insert, or tap their card to pay. The SDK provides a prebuilt [payment prompt screen](mobile-payments-sdk/ios/take-payments#create-prompt-parameters) you can use instead of creating a custom prompt. If you want to create your own payment prompt screen, your application should query the `PaymentManager` `availableCardInputMethods` method and display the available payment methods to buyers.
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
@property (nonatomic, strong) SQMPCardInputMethods *availableCardInputMethods;
@end
@implementation <#YourViewController#>
- (void)viewDidLoad {
[super viewDidLoad];
// Initialize availableCardInputMethods
self.availableCardInputMethods = SQMPMobilePaymentsSDK.shared.paymentManager.availableCardInputMethods;
// Add this class as an observer to receive updates to available card input methods.
[SQMPMobilePaymentsSDK.shared.paymentManager add:self];
}
#pragma mark - SQMPAvailableCardInputMethodsObserver
- (void)availableCardInputMethodsDidChange:(SQMPCardInputMethods *)cardInputMethods {
self.availableCardInputMethods = cardInputMethods;
if (self.availableCardInputMethods.isEmpty) {
NSLog(@"No card readers connected.");
} else {
NSLog(@"Available card input methods: %@", cardInputMethods);
}
}
@end
```
### Reader status
Your application can check the current status of connected readers with `SQMPReaderInfo.statusInfo` to display updates and messages to users. The `statusInfo` property returns a `SQMPReaderStatusInfo` object that contains the reader's current status and additional context. The statusInfo.status property indicates the reader's current status. The possible values are:
* `ready`: The reader is paired, connected, and able to accept card payments.
* Magstripe readers connect automatically and are always `ready` until physically disconnected from the mobile device.
* `connectingToSquare`: The reader is establishing a connection to Square's servers.
* `connectingToDevice`: The reader is establishing a connection to the mobile device.
* `faulty`: The reader has encountered a hardware or connection error and is in an unrecoverable state.
* `readerUnavailable`: The reader is connected but not able to take payments.
If a reader is unavailable, check `statusInfo.unavailableReasonInfo.reason` for specific details, which may include bluetooth failure, a blocking firmware update, or issues with the merchant’s Square account. Depending on the reason, you can prompt the user to take action, or retry the connection with Square's servers with `SQMPreaderManager.retryConnection()`.
{% aside type="info" %}
`SQMPreaderInfo.status` is available in iOS Mobile Payments SDK version `2.3.0` and above. If your integration uses an earlier version of the SDK, monitor the status of connected readers with `readerInfo.state`. The available states are `connecting`, `updatingFirmware`, `disconnected`, or `failedToConnect`.
{% /aside %}
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
// …
@end
@implementation <#YourViewController#>
- (NSInteger)readyReaderCount {
// You can access all connected readers via
// `SQMPMobilePaymentsSDK.shared.readerManager.readers`
NSArray> *readers = SQMPMobilePaymentsSDK.shared.readerManager.readers;
NSInteger readyReaderCount = 0;
for (id reader in readers) {
if (reader.status == SQMPReaderStatusReady) {
readyReaderCount++;
}
}
return readyReaderCount;
}
@end
```
### Unpairing a reader
Paired contactless and chip readers are remembered by the Mobile Payments SDK. When a new card reader is paired to the application, it remains paired until forgotten with the `ReaderManager`'s `forget(reader)` method.
## Next steps
To test your application in the Square Sandbox without a physical Square Reader device, use the Mobile Payments SDK [Mock Reader UI](mobile-payments-sdk/ios#mock-readers) to simulate a reader and accept test payments. Otherwise, after you've paired a physical Square Reader device, you're ready to [take payments](mobile-payments-sdk/ios/take-payments) in a production environment.
---
# Take a Payment
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/take-payments
> Status: PUBLIC
> Languages: All
> Platforms: iOS
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [Payments API](payments-refunds) | [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to use the Mobile Payments SDK for iOS to take a payment with a Square Reader or Square Stand.{% /subheading %}
{% line-break /%}
[Context: Swift, iOS]
{% toc hide=true /%}
## Overview
Payments in the Mobile Payments SDK are handled by the `PaymentManager` and must conform to the `PaymentManagerDelegate` protocol. The `PaymentManagerDelegate` is called when a payment starts and finishes successfully, fails, or is canceled. Your application should include logic to handle each of these scenarios. To learn about error messages produced by the Mobile Payments SDK and ways to resolve them, see [Handling Errors](mobile-payments-sdk/ios/handling-errors). If the payment completes successfully, a `Payment` object is returned, describing details of the payment. This can be either an `OnlinePayment` or an `OfflinePayment`.
```swift
extension <#YourViewController#>: PaymentManagerDelegate {
func paymentManager(_ paymentManager: PaymentManager, didFinish payment: Payment) {
// You can further inspect each payment once cast
if let onlinePayment = payment as? OnlinePayment {
print("Online Payment - ID: \(onlinePayment.id!), status: \(onlinePayment.status.description)")
} else if let offlinePayment = payment as? OfflinePayment {
print("Offline Payment - ID: \(offlinePayment.localID), status: \(offlinePayment.status.description)")
}
}
func paymentManager(_ paymentManager: PaymentManager, didFail payment: Payment, withError error: Error) {
// Handle this the same way as `didFinish`
}
func paymentManager(_ paymentManager: PaymentManager, didCancel payment: Payment) {
// Handle this the same way as `didFinish`
}
}
```
## Requirements and limitations
Before taking a payment with the SDK in a production environment, ensure that you've done the following:
* [Requested the permissions](mobile-payments-sdk/ios#privacy-permissions) necessary for the type of reader you're using.
* [Installed and initialized](mobile-payments-sdk/ios#quickstart) the Mobile Payments SDK in your iOS application.
* [Authorized the Mobile Payments SDK](mobile-payments-sdk/ios/configure-authorize) with a Square account.
Additionally, before taking a payment in production, you can test your application using [mock readers](mobile-payments-sdk/ios#mock-readers) and the Square Sandbox or download the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-ios) to see an example payment implementation.
## Create payment parameters
To begin a payment with the Mobile Payments SDK, you create a `PaymentParameters` object, which includes attributes describing the payment you want to take. For example, there are parameters for the payment amount, payment attempt ID, optional tip, application fee (if applicable), and the processing mode, which [determines whether payments can be taken offline](mobile-payments-sdk/ios/offline-payments). `autoDetect` is the recommended `processingMode`, as this directs the payment online or offline based on the highest chance of success. For this reason, the resulting Payment object might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both if you're using the `autoDetect` processing mode. Merchants can optionally add [card surcharges](#card-surcharging) to payments, and your application can allow or override that setting with the `allowCardSurcharge` parameter. For the complete list of payment parameter values and details, see the [iOS technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/ios).
### Idempotency and payment attempts
{% aside type="important" %}
In the Mobile Payments SDK version `2.2.2` and earlier, you generated and added your own idempotency key in your `paymentParameters`. In version `2.3.0` and later, the `idempotencyKey` parameter is deprecated and you instead provide a `paymentAttemptID`.
This is the recommended way to handle idempotent payment requests in the Mobile Payments SDK, and offers both idempotency protection and support for Strong Customer Authentication (SCA) requirements.
{% /aside %}
[Square payment requests](https://developer.squareup.com/reference/square/payments-api/create-payment) contain an idempotency key, a unique string identifier that accompanies an API operation, allowing Square to recognize potential duplicate calls. Using an idempotency key for each payment request ensures that a payment can only occur once, protecting against unintended outcomes like charging a customer twice for the same transaction.
When you provide a `paymentAttemptID` in your `paymentParameters` for each call to `startPayment`, the Mobile Payments SDK generates a unique idempotency key for the payment request, and stores it along with your payment attempt ID. If multiple requests are made for the same payment attempt (for example, during SCA flows), the SDK generates a new idempotency key for each request and updates the stored idempotency key for the given payment attempt ID. You can't include both an `idempotencyKey` and a `paymentAttemptID` in your `paymentParameters`, only one.
Along with a `paymentAttemptID`, you should include a unique `referenceID` value in your `paymentParameters` for each payment. This persists with the payment and can be used to identify the payment within your own system if you need to reference it later. Your attempt ID and reference ID are not interchangeable. You shouldn't use the same value for both parameters because sometimes a payment requires multiple attempts (for example, if the first payment attempt is declined for expiration or insufficient funds, you can retry the payment with the same `referenceID` and a new `paymentAttemptID`). Typically, the `referenceID` is used to match Square payments to an external system, but it can also be used to identify payments within Square.
If you don't receive a server response from a payment made with the Mobile Payments SDK, you should check its status to determine whether to attempt the payment again. Use the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and query by location ID, total payment amount, or other fields to filter the list. You can use your unique `referenceID` to identify the correct payment and check its status. You might need to make a new payment attempt if the prior payment exists, but can't be completed. In this situation, retrieve the final idempotency key used for the payment attempt with `PaymentManager.getIdempotencyKey`, and cancel the incomplete payment by using [CancelPaymentByIdempotencyKey](https://developer.squareup.com/reference/square/payments-api/cancel-payment-by-idempotency-key).
The following is an example of payment parameters created for a payment of $1 USD. The parameters include a `paymentAttemptID`, unique `referenceID`, and an optional `orderID` that allows you to associate a payment with an itemized [Square order](orders-api/what-it-does).
```swift
import UIKit
import SquareMobilePaymentsSDK
extension <#YourViewController#> {
func makePaymentParameters() -> PaymentParameters {
let amount = Money(amount: 100, currency: .USD)
// This is the ID used to reference the payment in your own system.
let referenceID = "MY_REFERENCE_ID_1234"
// This is the ID of the payment attempt for idempotent payment requests.
let paymentAttemptID = "paymentAttemptID"
// allow the payment to be taken online or offline
let processingMode = processingMode.autoDetect
// allow credit card surcharging for online payments if configured by the merchant
let allowCardSurcharge = true
// Create the payment parameters
let paymentParams = PaymentParameters(
paymentAttemptID: paymentAttemptID,
amountMoney: amount,
processingMode: processingMode,
allowCardSurcharge: allowCardSurcharge
)
// An optional note to add to the payment.
paymentParams.note = "My Note"
// Optional parameter to associate this payment with a previously created Square order.
paymentParams.orderID = "CAISENgvlJ6jLWAzERDzjyHVybY"
// A user-defined ID to associate with the payment. You can use this field
// to associate the payment to an entity in an external system.
paymentParams.referenceID = referenceID
return paymentParams
}
}
```
## Create prompt parameters
Each payment must also have `PromptParameters` configured. The `PromptParameters` contain a `PromptMode` and `AdditionalPaymentMethods`. `PromptParameters.mode` determines whether your application uses the `default` Square-provided payment prompt UI or a custom payment prompt where you build your own UI. The default UI provided by Square is presented on top of the `viewController` passed to `PaymentManager.startPayment` and presents buyers with the payment options available from `PaymentManager.availableCardInputMethods`.
{% line-break /%}
`PromptParameters.additionalPaymentMethods` specifies a list of additional payment methods available to use for this payment. The current options are `keyed` (a manually entered credit card payment) or `cash`. If you're using the default `PromptMode`, you can make `AdditionalPaymentMethods` an empty list to remove the manual card entry button from the payment prompt.
If you create your own `custom` `PromptMode`, you should use the `additionalPaymentMethods` available from the `PaymentHandle` to render these options for buyers in your own payment prompt UI.
## Start the payment
To begin processing a payment, call `PaymentManager.startPayment()` with the `PaymentParameters` and `PromptParameters` you previously created. During the payment, Square takes control of the screen display to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer. You must conform to the `PaymentManagerDelegate` to handle results and [errors](mobile-payments-sdk/ios/handling-errors) from the payment flow.
When the payment begins, the Payment Manager provides a `PaymentHandle` as a way for you to interact with the ongoing payment (for example, if you need to [cancel the payment](#canceling-payments)). When the payment completes, regardless of whether it completed successfully, control is returned to the user interface and your application is notified of the result using `PaymentManagerDelegate`. Your application can display [receipt](#receipts) or [error](mobile-payments-sdk/ios/handling-errors) information to the user and continue other processing.
{% aside type="info" %}
Only one payment can be in process at a given moment. If you make a second call to `startPayment` before the first has completed, triggering the `PaymentManagerDelegate`, the second call fails immediately with a `paymentAlreadyInProgress` error. The first payment call continues.
{% /aside %}
```swift
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
private var paymentHandle: PaymentHandle?
func startPayment() {
paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(
makePaymentParameters(),
promptParameters: PromptParameters(
mode: .default,
additionalMethods: .all
),
from: self,
delegate: self
)
}
func makePaymentParameters() -> PaymentParameters {
PaymentParameters(
paymentAttemptID: UUID().uuidString,
amountMoney: Money(amount: 100, currency: .USD)
)
}
}
```
## Delay the capture of payments
As part of your application's workflow, you might want to authorize a customer's transaction but delay the capture of the payment (the transfer of funds from customer to seller) for a period of time. For example, in a restaurant with a kiosk ordering system, you might want to authorize a customer's credit card when they order, but not complete the payment until they receive their food.
While creating `PaymentParameters`, set the `autocomplete` value to `false` if you want to delay the capture of the payment. While the payment is delayed, use the Payments API to [complete](https://developer.squareup.com/reference/square/payments-api/complete-payment) or [cancel the payment](https://developer.squareup.com/reference/square/payments-api/cancel-payment). You can also [update the payment](https://developer.squareup.com/reference/square/payments-api/update-payment) to add a tip using the `tip_money` parameter.
When `autocomplete` is `false`, there are two more `PaymentParameter` values which handle the delayed payment:
* `delayDuration`: The number of seconds to wait before canceling the payment or taking another `delayAction`, specified as a `TimeInterval`, with a minimum value of 60 seconds. Use a value of “0” to fallback to the default 36 hours for card present payments, or 7 days for manually entered payments.
* `delayAction`: The action to take once the `delayDuration` has passed with no other action on the payment. The possible options are `cancel` (default) or `complete`.
{% aside %}
Only one of `autocomplete` and `acceptPartialAuthorization` can be `true`. If you are accepting multiple payment methods for a single purchase (such as a gift card and credit card), you must set `autocomplete` to `false` and manage the delayed capture of the payment.
{% /aside %}
For more information about delayed payment capture using the Payments API, see [Delayed Capture of a Card Payment](payments-api/take-payments/card-payments/delayed-capture).
## Card Surcharging
A surcharge is an additional amount or percentage that sellers can set to pass on credit card processing fees to buyers. Sellers optionally set a surcharge percentage in their Square Dashboard. As a Mobile Payments SDK developer, you can include this surcharge or choose to override the dashboard settings and disallow surcharges on card payments in your application.
{% aside type="important" %}
* Surcharges with the Mobile Payments SDK are only available for credit card payments made in the US.
* Surcharges are not available for offline payments, debit card payments, or pre-existing orders.
{% /aside %}
To add surcharges to credit card payments, your application must have `ITEMS_READ` permission in addition to the [standard payment permissions](mobile-payments-sdk#oauth-permissions).
Use the `allowCardSurcharge` parameter in your `PaymentParameters` to control whether surcharges can be applied to individual payments:
```swift
// Enable surcharging for this payment
paymentParams.allowCardSurcharge = true
// Or disable surcharging for this specific payment
paymentParams.allowCardSurcharge = false
```
If you're using a custom payment prompt, use the use the `PaymentHandle.totalMoneyWithProposedCardSurcharge` to display surcharge amounts to customers before payment completion. This ensures transparency and compliance with surcharging regulations.
After an Online payment completes, access surcharge information from its `CardPaymentDetails` for receipt generation and record keeping:
```swift
extension YourViewController: PaymentManagerDelegate {
func paymentManager(_ paymentManager: PaymentManager, didFinish payment: Payment) {
// Cast to OnlinePayment to access cardDetails
if let onlinePayment = payment as? OnlinePayment,
let cardDetails = onlinePayment.cardDetails,
let surchargeDetails = cardDetails.appliedCardSurchargeDetails {
print("Base surcharge amount: \(surchargeDetails.cardSurchargeMoney)")
if let taxOnSurcharge = surchargeDetails.taxOnCardSurchargeMoney {
print("Tax on surcharge: \(taxOnSurcharge)")
}
```
## Canceling payments
The `PaymentHandle` provided by the Mobile Payments SDK during a payment can be used to cancel that payment. Note that only a payment where `autocomplete` is set to `false` can be canceled during processing. You can first check the value of `PaymentHandle.isPaymentCancelable`. If it's set to `true`, the payment can be canceled by calling `paymentHandle.cancelPayment()`. For example, if your code dismisses the view controller passed to `PaymentManager.startPayment` and the payment was not successful, you must call `cancelPayment`.
During any payment flow, if the application is backgrounded or the application activity is interrupted, the payment in progress is canceled.
## Receipts
Your application must provide buyers with the option to receive a digital or printed receipt. These receipts aren't sent directly by Square. Therefore, to remain compliant with EMV-certification requirements, you must generate receipts including the following fields from the payment response `cardDetails` object, when available:
* `cardholderName` (example: James Smith)
* `cardBrand` and `last4` (example: Visa 0094)
* `applicationName` (example: AMERICAN EXPRESS)
* `applicationIdentifier` (example: AID: A0 00 00 00 25 01 09 01)
* `entryMethod` (example: Contactless)
[Context: Objective C, iOS]
{% toc hide=true /%}
## Overview
Payments in the Mobile Payments SDK are handled by the `SQMPPaymentManager` and must conform to the `SQMPPaymentManagerDelegate` protocol. The `SQMPPaymentManagerDelegate` is called when a payment starts and finishes successfully, fails, or is canceled. Your application should include logic to handle each of these scenarios. To learn about error messages produced by the Mobile Payments SDK and ways to resolve them, see [Handling Errors](mobile-payments-sdk/ios/handling-errors). If the payment completes successfully, a `Payment` object is returned, describing details of the payment. This can be either an `OnlinePayment` or an `OfflinePayment`.
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> ()
// …
@end
@implementation <#YourViewController#>
- (void)paymentManager:(id)paymentManager didFinish:(id)payment {
// You can further inspect each payment once cast
if ([payment conformsToProtocol:@protocol(SQMPOnlinePayment)]) {
id onlinePayment = (id)payment;
NSLog(@"Online Payment - ID: %@, status: %lu", onlinePayment.id, onlinePayment.status);
} else if ([payment conformsToProtocol:@protocol(SQMPOfflinePayment)]) {
id offlinePayment = (id)payment;
NSLog(@"Offline Payment - ID: %@, status: %lu", offlinePayment.localID, offlinePayment.status);
}
}
@end
```
## Requirements and limitations
Before taking a payment with the SDK in a production environment, ensure that you've done the following:
* [Requested the permissions](mobile-payments-sdk/ios#privacy-permissions) necessary for the type of reader you're using.
* [Installed and initialized](mobile-payments-sdk/ios#quickstart) the Mobile Payments SDK in your iOS application.
* [Authorized the Mobile Payments SDK](mobile-payments-sdk/ios/configure-authorize) with a Square account.
Additionally, before taking a payment in production, you can test your application using [mock readers](mobile-payments-sdk/ios#mock-readers) and the Square Sandbox or download the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-ios) (written in Swift) to see an example payment implementation.
## Create payment parameters
To begin a payment with the Mobile Payments SDK, you create a `SQMPPaymentParameters` object, which includes attributes describing the payment you want to take. For example, there are parameters for the payment amount, payment attempt ID, optional tip, application fee (if applicable), and the processing mode, which determines whether [payments can be taken offline](mobile-payments-sdk/ios/offline-payments). `autoDetect` is the recommended `processingMode`, as this directs the payment online or offline based on the highest chance of success. For this reason, the resulting Payment object might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both if you're using the `autoDetect` processing mode. Merchants can optionally add [card surcharges](#card-surcharging) to payments, and your application can allow or override that setting with the `allowCardSurcharge` parameter. For the complete list of payment parameter values and details, see the [iOS technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/ios).
### Idempotency and payment attempts
{% aside type="important" %}
In the Mobile Payments SDK version `2.2.2` and earlier, you generated and added your own idempotency key in your `SQMPpaymentParameters`. In version `2.3.0` and later, the `idempotencyKey` parameter is deprecated and you instead provide a `paymentAttemptID`.
This is the recommended way to handle idempotent payment requests in the Mobile Payments SDK, and offers both idempotency protection and support for Strong Customer Authentication (SCA) requirements.
{% /aside %}
[Square payment requests](https://developer.squareup.com/reference/square/payments-api/create-payment) contain an idempotency key, a unique string identifier that accompanies an API operation, allowing Square to recognize potential duplicate calls. Using an idempotency key for each payment request ensures that a payment can only occur once, protecting against unintended outcomes like charging a customer twice for the same transaction.
When you provide a `paymentAttemptID` in your `SQMPPaymentParameters` for each call to `startPayment`, the Mobile Payments SDK generates a unique idempotency key for the payment request, and stores it along with your payment attempt ID. If multiple requests are made for the same payment attempt (for example, during SCA flows), the SDK generates a new idempotency key for each request and updates the stored idempotency key for the given payment attempt ID. You can't include both an `idempotencyKey` and a `paymentAttemptID` in your `SQMPPaymentParameters`, only one.
Along with a `paymentAttemptID`, you should include a unique `referenceID` value in your `SQMPPaymentParameters` for each payment. This persists with the payment and can be used to identify the payment within your own system if you need to reference it later. Your attempt ID and reference ID are not interchangeable. You shouldn't use the same value for both parameters because sometimes a payment requires multiple attempts (for example, if the first payment attempt is declined for expiration or insufficient funds, you can retry the payment with the same `referenceID` and a new `paymentAttemptID`). Typically, the `referenceID` is used to match Square payments to an external system, but it can also be used to identify payments within Square.
If you don't receive a server response from a payment made with the Mobile Payments SDK, you should check its status to determine whether to attempt the payment again. Use the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and query by location ID, total payment amount, or other fields to filter the list. You can use your unique `referenceID` to identify the correct payment and check its status. You might need to make a new payment attempt if the prior payment exists, but can't be completed. In this situation, retrieve the final idempotency key used for the payment attempt with `PaymentManager.getIdempotencyKey`, and cancel the incomplete payment by using [CancelPaymentByIdempotencyKey](https://developer.squareup.com/reference/square/payments-api/cancel-payment-by-idempotency-key).
The following is an example of payment parameters created for a payment of $1 USD. The parameters include a `paymentAttemptID`, unique `referenceID`, and an optional `orderID` that allows you to associate a payment with an itemized [Square order](orders-api/what-it-does).
```objectivec
#import
@import SquareMobilePaymentsSDK;
@implementation <#YourViewController#>
- (SQMPPaymentParameters *)makePaymentParameters {
SQMPMoney *amount = [[SQMPMoney alloc] initWithAmount:100 currency:SQMPCurrencyUSD];
// allow the payment to be taken online or offline
SQMPProcessingMode processingMode = SQMPProcessingModeAutoDetect;
// This is the ID used to reference the payment in your own system.
NSString *referenceID = @"MY_REFERENCE_ID_1234";
// This is the ID of the payment attempt for idempotent payment requests.
NSString *paymentAttemptID = [NSUUID UUID].UUIDString;
// Create the payment parameters
SQMPPaymentParameters *paymentParams = [[SQMPPaymentParameters alloc] initWithPaymentAttemptID:paymentAttemptID amountMoney:amount processingMode:processingMode];
// An optional note to add to the payment.
paymentParams.note = @"My Note";
// Optional parameter to associate this payment with a previously created Square order.
paymentParams.orderID = @"CAISENgvlJ6jLWAzERDzjyHVybY";
// A user-defined ID to associate with the payment. You can use this field
// to associate the payment to an entity in an external system.
paymentParams.referenceID = referenceID;
return paymentParams;
}
@end
```
## Create prompt parameters
Each payment must also have `SQMPPromptParameters` configured. The `SQMPPromptParameters` contain a `PromptMode` and `AdditionalPaymentMethods`. `PromptParameters.mode` determines whether your application uses the `default` Square-provided payment prompt UI or a custom payment prompt where you build your own UI. The default UI provided by Square is presented on top of the `viewController` passed to `PaymentManager.startPayment` and presents buyers with the payment options available from `PaymentManager.availableCardInputMethods`.
{% line-break /%}
`PromptParameters.additionalPaymentMethods` specifies a list of additional payment methods available to use for this payment. The current options are `keyed` (a manually entered credit card payment) and `cash`. If you're using the default `PromptMode`, you can make `AdditionalPaymentMethods` an empty list to remove the manual card entry button from the payment prompt.
If you create your own `custom` `PromptMode`, you should use the `additionalPaymentMethods` available from the `SQMPPaymentHandle` to render these options for buyers in your own payment prompt UI.
## Start the payment
To begin processing a payment, call `PaymentManager.startPayment()` with the `SQMPPaymentParameters` and `SQMPPromptParameters` you previously created. During the payment, Square takes control of the screen display to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer. You must conform to the `SQMPPaymentManagerDelegate` to handle results and [errors](mobile-payments-sdk/ios/handling-errors) from the payment flow.
When the payment begins, the Payment Manager provides a `SQMPPaymentHandle` as a way for you to interact with the ongoing payment (for example, if you need to [cancel the payment](#canceling-payments)). When the payment completes, regardless of whether it completed successfully, control is returned to the user interface and your application is notified of the result using `SQMPPaymentManagerDelegate`. Your application can display [receipt](#receipts) or [error](mobile-payments-sdk/ios/handling-errors) information to the user and continue other processing.
{% aside type="info" %}
Only one payment can be in process at a given moment. If you make a second call to `startPayment` before the first has completed, triggering the `SQMPPaymentManagerDelegate`, the second call fails immediately with a `paymentAlreadyInProgress` error. The first payment call continues.
{% /aside %}
```objectivec
#import
@import SquareMobilePaymentsSDK;
@interface <#YourViewController#> : UIViewController
// …
@end
@implementation <#YourViewController#>
- (void)startPayment {
id paymentHandle = [SQMPMobilePaymentsSDK.shared.paymentManager
startPayment:[self makePaymentParameters]
promptParameters:[[SQMPPromptParameters alloc] initWithMode:SQMPPromptModeDefault
additionalMethods:SQMPAdditionalPaymentMethods.all]
from:self
delegate:self];
}
- (SQMPPaymentParameters *)makePaymentParameters {
SQMPMoney *amountMoney = [[SQMPMoney alloc] initWithAmount:100 currency:SQMPCurrencyUSD];
NSString *paymentAttemptID = [[NSUUID UUID] UUIDString];
return [[SQMPPaymentParameters alloc] initWithpaymentAttemptID:paymentAttemptID amountMoney:amountMoney];
}
@end
```
## Delay the capture of payments
As part of your application's workflow, you might want to authorize a customer's transaction but delay the capture of the payment (the transfer of funds from customer to seller) for a period of time. For example, in a restaurant with a kiosk ordering system, you might want to authorize a customer's credit card when they order, but not complete the payment until they receive their food.
While creating `SQMPPaymentParameters`, set the `autocomplete` value to `false` if you want to delay the capture of a payment. While the payment is delayed, use the Payments API to [complete](https://developer.squareup.com/reference/square/payments-api/complete-payment) or [cancel the payment](https://developer.squareup.com/reference/square/payments-api/cancel-payment). You can also [update the payment](https://developer.squareup.com/reference/square/payments-api/update-payment) to add a tip using the `tip_money` parameter.
When `autocomplete` is `false`, there are two more `SQMPPaymentParameter` values which handle the delayed payment:
* `delayDuration`: The number of seconds to wait before canceling the payment or taking another `delayAction`, specified as a `TimeInterval`, with a minimum value of 60 seconds. Use a value of “0” to fallback to the default 36 hours for card present payments, or 7 days for manually entered payments.
* `delayAction`: The action to take once the `delayDuration` has passed with no other action on the payment. The possible options are `cancel` (default) or `complete`.
{% aside %}
Only one of `autocomplete` and `acceptPartialAuthorization` can be `true`. If you are accepting multiple payment methods for a single purchase (such as a gift card and credit card), you must set `autocomplete` to `false` and manage the delayed capture of the payment.
{% /aside %}
For more information about delayed payment capture using the Payments API, see [Delayed Capture of a Card Payment](payments-api/take-payments/card-payments/delayed-capture).
## Card Surcharging
A surcharge is an additional amount or percentage that sellers can set to pass on credit card processing fees to buyers. Sellers optionally set a surcharge percentage in their Square Dashboard. As a Mobile Payments SDK developer, you can include this surcharge or choose to override the dashboard settings and disallow surcharges on card payments in your application.
{% aside type="important" %}
* Surcharges with the Mobile Payments SDK are only available for credit card payments made in the US.
* Surcharges are not available for offline payments, debit card payments, or pre-existing orders.
{% /aside %}
To add surcharges to credit card payments, your application must have `ITEMS_READ` permission in addition to the [standard payment permissions](mobile-payments-sdk#oauth-permissions).
Use the `allowCardSurcharge` parameter in your `SQMPPaymentParameters` to control whether surcharges can be applied to individual payments:
```objectivec
// Enable surcharging for this payment
paymentParams.allowCardSurcharge = YES
// Or disable surcharging for this specific payment
paymentParams.allowCardSurcharge = NO
```
If you're using a custom payment prompt, use the use the `SQMPPaymentHandle.totalMoneyWithProposedCardSurcharge` to display surcharge amounts to customers before payment completion. This ensures transparency and compliance with surcharging regulations.
After an Online payment completes, access surcharge information from its `CardPaymentDetails` for receipt generation and record keeping:
```objectivec
#import
@import SquareMobilePaymentsSDK;
- (void)paymentManager:(id)paymentManager
didFinish:(id)payment {
// Cast to SQMPOnlinePayment to access cardDetails
if ([payment conformsToProtocol:@protocol(SQMPOnlinePayment)]) {
id onlinePayment = (id)payment;
id cardDetails = onlinePayment.cardDetails;
if (cardDetails && cardDetails.appliedCardSurchargeDetails) {
id surchargeDetails = cardDetails.appliedCardSurchargeDetails;
NSLog(@"Base surcharge amount: %@", surchargeDetails.cardSurchargeMoney);
if (surchargeDetails.taxOnCardSurchargeMoney) {
NSLog(@"Tax on surcharge: %@", surchargeDetails.taxOnCardSurchargeMoney);
}
```
## Canceling payments
The `SQMPPaymentHandle` provided by the Mobile Payments SDK during a payment can be used to cancel that payment. Note that only a payment where `autocomplete` is set to `false` can be canceled during processing. You can first check the value of `PaymentHandle.isPaymentCancelable`. If it's set to `true`, the payment can be canceled by calling `paymentHandle.cancelPayment()`. For example, if your code dismisses the view controller passed to `PaymentManager.startPayment` and the payment was not successful, you must call `cancelPayment`.
During any payment flow, if the application is backgrounded or the application activity is interrupted, the payment in progress is canceled.
## Receipts
Your application must provide buyers with the option to receive a digital or printed receipt. These receipts aren't sent directly by Square. Therefore, to remain compliant with EMV-certification requirements, you must generate receipts including the following fields from the payment response `cardDetails` object, when available:
* `cardholderName` (example: James Smith)
* `cardBrand` and `last4` (example: Visa 0094)
* `authorizationCode` (example: Authorization 262921)
* `applicationName` (example: AMERICAN EXPRESS)
* `applicationId` (example: AID: A0 00 00 00 25 01 09 01)
* `entryMethod` (example: Contactless)
---
# Offline Payments
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/offline-payments
> Status: BETA
> Languages: All
> Platforms: iOS
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios) | [Payments API](payments-refunds)
{% subheading %}Learn how to take payments offline with the Mobile Payments SDK for iOS.{% /subheading %}
{% line-break /%}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK supports taking payments in offline mode, for example when a reader is used in a location with weak network connection or the application momentarily loses connection to Square servers. Offline payments are stored (queued) locally on the mobile device running the Mobile Payments SDK application and processed by Square the next time the device successfully connects to the Internet and Square servers.
## Requirements and limitations
{% aside type="warning" %}
Before upgrading to a new version of the Mobile Payments SDK or a new version of your application, you should ensure all offline payments have been uploaded by verifying that the offline payment queue is empty.
{% /aside %}
* Offline payments aren't supported in the Square Sandbox.
* Interac debit cards don't work in Offline mode. Any offline transaction attempted with an Interac debit card results in a payment failure.
* Your application must be connected to the Internet to connect a new Square reader. If you intend to take offline payments, Square recommends pairing any reader devices while online.
* Offline Payments support is limited to the two most recent versions of Square Reader for contactless and chip, Square Reader for magstripe, and Square Stand second generation. To learn whether your reader device is supported, see [Hardware devices and capabilities](mobile-payments-sdk#hardware-devices-and-capabilities).
* If you're using the Mobile Payments SDK with a [Square Reader for contactless and chip](https://squareup.com/us/en/hardware/contactless-chip-reader), both a bluetooth connection and a secure connection are required to take offline payments.
* Bluetooth connection relies on device settings and physical distance. A reader must maintain a Bluetooth connection with a mobile device's POS application to take payments.
* A secure connection is established when a reader is connected to a mobile device that has its POS application open and online.
To take offline payments with the Mobile Payments SDK and a bluetooth Square reader:
* The reader must be connected to a device that was online and had its POS application opened within the last 24 hours.
* The POS device must have a bluetooth connection to the reader and have offline processing enabled before going offline.
* The reader must maintain a bluetooth connection to your device throughout the offline payment.
{% aside type="important" %}
Sellers must contact Square and [opt-in to accept offline payments with the Mobile Payments SDK](#seller-onboarding). The seller is responsible for any expired, declined, or disputed payments accepted while offline. By opting in, providing their merchant ID, and using Offline Payments, the seller is aware of and accepting this risk.
{% /aside %}
[Context: Swift, iOS]
## Seller onboarding
At this time, the Offline Payments feature for the Mobile Payments SDK is in Beta and requires Square sellers to opt in to this feature. If a seller using your application is interested in taking payments offline with the Mobile Payments SDK, send an email to developerbetas@squareup.com. In your message, include:
* The seller's business name.
* The seller's email address (this should be the owner or administrator for the seller's Square account).
* Your application ID.
Square contacts the seller directly and provides them with a seller onboarding form for this feature. After the seller is successfully onboarded, Square sends you (the developer) a confirmation email letting you know that you can accept offline payments for the seller.
At any time, you can check the `isOfflineProcessingAllowed` value within the `PaymentSettings` to determine whether the seller that is authorized with your application can take payments offline. If your application tries to take an offline payment for a seller who doesn't have access to this feature, you receive a `merchantNotOptedIntoOfflineProcessing` [error](mobile-payments-sdk/ios/handling-errors).
## Transaction limits
Each seller taking payments offline with the Mobile Payments SDK has a limit on each offline payment and a limit to the total amount they can store offline on their mobile device. These limits vary by seller. If your application attempts to take an offline payment that exceeds the limit for a single transaction, the Mobile Payments SDK returns an `offlineTransactionAmountExceeded` [error](mobile-payments-sdk/ios/handling-errors). If your application attempts to take an offline payment that exceeds the allowed offline payment total, the SDK returns an `offlineStoredAmountExceeded` error.
Each device running the Mobile Payments SDK can take up to 1000 payments for up to 24 hours before reconnecting to the network. If this limit is reached, the reader fails to connect and your mobile device must connect to a network to process and upload these payments before accepting more.
```swift
let paymentSettings = MobilePaymentsSDK.shared.settingsManager.paymentSettings
let isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed
let offlineTransactionAmountLimit = paymentSettings.offlineTransactionAmountLimit
let offlineTotalStoredAmountLimit = paymentSettings.offlineTotalStoredAmountLimit
```
### Payment methods
The payment methods available to customers are limited while offline and not all devices support every type of offline payment. Before taking any payment, your application should query the Payment Manager's `availableCardInputMethods()` and display the possible payment methods to customers.
If you're using the `DEFAULT` [payment prompt](mobile-payments-sdk/ios/take-payments#create-prompt-parameters), the SDK automatically displays the card input methods available while offline.
## Take a payment offline
When you're ready to [take a payment](mobile-payments-sdk/ios/take-payments) with the Mobile Payments SDK, you create `PaymentParameters` with details about the payment. The `processingMode` field is required, and determines whether the payment should be taken offline. You can choose from `onlineOnly`, `offlineOnly`, or `autoDetect`.
It's recommended to set the `processingMode` to `autoDetect` to improve your application reliability. In this mode, the SDK checks the status of the local network connection and the performance of Square's servers to route the payment online or offline for the highest chance of success. For example, with the `processingMode` set to `autoDetect`, a seller who has not opted into offline processing always has their payment attempted online, since offline payments would fail when checking opt-in status. If you're using the `autoDetect` processing mode, the Payment object returned by `startPayment()` might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both possibilities.
In some situations, such as when a location has a sporadic or weak Internet connection, sellers might want to take all payments offline during a period of time. To do so, set the `processingMode` for payments to `offlineOnly`. All payments made with this mode are initially queued on the mobile device, even if there is a network connection.
```swift
let paymentParams = PaymentParameters(
paymentAttemptID: UUID().uuidString,
amountMoney: Money(amount: 100, currency: .USD),
processingMode: .autoDetect
)
let paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(
paymentParams,
promptParameters: PromptParameters(
mode: .default,
additionalMethods: .all
),
from: self,
delegate: self
)
```
{% aside type="important" %}
When an offline payment is queued, it hasn't yet been processed by Square. The transaction isn't returned from the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and doesn't have a Square payment ID value. If your application's workflow involves delayed payment capture or syncing Square payments with an outside transaction database, you must write logic to query Square for the completed payment and its details and then perform that sync. For more information, see [Payment IDs](#payment-ids).
{% /aside %}
## Access offline payments
The Mobile Payments SDK provides the `getOfflinePaymentQueue()` method in the Payment Manager to access all payments taken offline by the application on the current mobile device. This includes queued payments waiting to be processed and completed processed payments. Only payments that have a `locationId` matching the current application user's location ID are returned. This prevents two Square sellers logging in to your application on the same mobile device from viewing each other's payments.
The `status` of an `OfflinePayment` indicates its current point in the payment workflow and whether it failed to upload or process. The `status` can be one of the following:
* `QUEUED` - The payment is stored locally on the device running the Mobile Payments SDK application. The SDK attempts to upload the payment to Square after the network connection is restored.
* `UPLOADED` - The payment has been uploaded to the Square server, but hasn't yet been processed.
* `FAILED_TO_UPLOAD` - The payment couldn't be uploaded due to an unrecoverable error.
* `FAILED_TO_PROCESS` - The connection was restored, but Square couldn't process this specific offline payment. This might be because of a declined card or another error with the card-issuing bank. An offline payment with this status cannot be recovered, and the seller doesn't receive funds from the transaction.
* `PROCESSED` - Square processed your offline payment successfully. It can now be seen in the Square Dashboard.
```swift
let offlinePaymentQueue = MobilePaymentsSDK.shared.paymentManager.offlinePaymentQueue
// Grab total amount stored
offlinePaymentQueue.getTotalStoredPaymentsAmount { [weak self] money, error in
guard let self else { return }
if let error {
print("Error getting total stored payments amount: \(error)")
return
}
print("Total stored amount: \(money.amount)")
}
// Grab offline payments
offlinePaymentQueue.getPayments { [weak self] offlinePayments, error in
guard let self else { return }
if let error {
print("Error getting offline payments: \(error)")
return
}
// Get the total number of payments currently stored
let totalNumberOfPayments = offlinePayments.count
// Iterate over the offline payments
offlinePayments.forEach { offlinePayment in
switch offlinePayment.status {
case .queued:
// Payment is retained on the local device; awaiting upload by Mobile Payments SDK.
break
case .uploaded:
// Payment has been successfully uploaded to the Square Server.
break
case .failedToUpload:
// Upload of payment failed due to an unrecoverable error.
break
case .failedToProcess:
// Processing of offline payment by Square Server failed, possibly due to card decline or other transaction issue.
break
case .processed:
// Offline payment has been successfully processed by Square Server and is now visible in the merchant dashboard.
break
case .unknown:
fallthrough
@unknown default:
// The status is unknown; verification could not be completed.
break
}
}
}
```
### Payment IDs
A payment taken offline with the Mobile Payments SDK has two identification values: `localID`, used to identify the payment on your mobile device before it's processed, and `id`, which represents the Square payment `id` value. The second value is always `null` until the SDK uploads the payment to Square and the payment is processed.
When a payment's status changes to `PROCESSED`, you can access its `id` value from the mobile device and match it to the `id` value of payments returned by the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint. You can now continue your application's payment workflow and use other Square APIs to access and manage the payment. `PROCESSED` payments are deleted from the mobile device to conserve storage space.
## Process offline payments
The Mobile Payments SDK regularly checks for network connectivity and a connection to Square servers so that queued payments can be processed. This is done automatically while the application is open in the foreground of the device. Assuming that there are no errors in the `PaymentParameters` or issues like cards being declined, the funds are available to the seller in the Square Dashboard and the payment can be accessed and managed by the [Payments API](https://developer.squareup.com/reference/square/payments-api) after this processing is complete.
{% aside type="important" %}
The following actions result in queued payments being removed from the device. If this happens before the payment is uploaded and processed, it cannot be processed and the seller doesn't receive funds from the transaction:
* Wiping the device cache
* Authenticating the Mobile Payments SDK with a different application ID on the same device
* Uninstalling the application from the device using the Mobile Payments SDK
{% /aside %}
Queued payments remain on the device when a user force-quits your application, switches to another application, or a seller logs out of your application. As a best practice, your application should query for any `QUEUED` payments on the device before calling `authorizationManager.deauthorize()`, so that you can alert the seller about any unprocessed payments.
[Context: Objective C, iOS]
## Seller onboarding
At this time, the Offline Payments feature for the Mobile Payments SDK is in Beta and requires Square sellers to opt in to this feature. If a seller using your application is interested in taking payments offline with the Mobile Payments SDK, send an email to developerbetas@squareup.com. In your message, include:
* The seller's business name.
* The seller's email address (this should be the owner or administrator for the seller's Square account).
* Your application ID.
Square contacts the seller directly and provides them with a seller onboarding form for this feature. After the seller is successfully onboarded, Square sends you (the developer) a confirmation email letting you know that you can accept offline payments for the seller.
At any time, you can check the `isOfflineProcessingAllowed` value within the `SQMPPaymentSettings` to determine whether the seller that is authorized with your application can take payments offline. If your application tries to take an offline payment for a seller who doesn't have access to this feature, you receive an `merchantNotOptedIntoOfflineProcessing` [error](mobile-payments-sdk/ios/handling-errors).
## Transaction limits
Each seller taking payments offline with the Mobile Payments SDK has a limit on each offline payment and a limit to the total amount they can store offline on their mobile device. These limits vary by seller. If your application attempts to take an offline payment that exceeds the limit for a single transaction, the Mobile Payments SDK returns an `offlineTransactionAmountExceeded` [error](mobile-payments-sdk/ios/handling-errors). If your application attempts to take an offline payment that exceeds the allowed offline payment total, the SDK returns an `offlineStoredAmountExceeded` error.
Each device running the Mobile Payments SDK can take up to 1000 payments for up to 24 hours before reconnecting to the network. If this limit is reached, the reader fails to connect and your mobile device must connect to a network to process and upload these payments before accepting more.
```objectivec
id paymentSettings = SQMPMobilePaymentsSDK.shared.settingsManager.paymentSettings;
BOOL isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed;
SQMPMoney *offlineTransactionAmountLimit = paymentSettings.offlineTransactionAmountLimit;
SQMPMoney *offlineTotalStoredAmountLimit = paymentSettings.offlineTotalStoredAmountLimit;
```
### Payment methods
The payment methods available to customers are limited while offline and not all devices support every type of offline payment. Before taking any payment, your application should query the Payment Manager's `availableCardInputMethods()` and display the possible payment methods to customers.
If you're using the `DEFAULT` [payment prompt](mobile-payments-sdk/ios/take-payments#create-prompt-parameters), the SDK automatically displays the card input methods available while offline.
## Take a payment offline
When you're ready to [take a payment](mobile-payments-sdk/ios/take-payments) with the Mobile Payments SDK, you create `SQMPPaymentParameters` with details about the payment. The `processingMode` field is required, and determines whether the payment should be taken offline. You can choose from `onlineOnly`, `offlineOnly`, or `autoDetect`.
It's recommended to set the `processingMode` to `autoDetect` to improve your application reliability. In this mode, the SDK checks the status of the local network connection and the performance of Square's servers to route the payment online or offline for the highest chance of success. For example, with the `processingMode` set to `autoDetect`, a seller who has not opted into offline processing always has their payment attempted online, since offline payments would fail when checking opt-in status. If you're using the `autoDetect` processing mode, the Payment object returned by `startPayment()` might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both possibilities.
In some situations, such as when a location has a sporadic or weak Internet connection, sellers might want to take all payments offline during a period of time. To do so, set the `processingMode` for payments to `offlineOnly`. All payments made with this mode are initially queued on the mobile device, even if there is a network connection.
```objectivec
SQMPPaymentParameters *paymentParams =
[[SQMPPaymentParameters alloc]
initWithpaymentAttemptID:[[NSUUID UUID] UUIDString]
amountMoney:[[SQMPMoney alloc] initWithAmount:100
currency:SQMPCurrencyUSD]
processingMode:SQMPProcessingModeAutoDetect];
id paymentHandle = [SQMPMobilePaymentsSDK.shared.paymentManager startPayment:
[self makePaymentParameters]
promptParameters: [[SQMPPromptParameters alloc] initWithMode:SQMPPromptModeDefault
additionalMethods:SQMPAdditionalPaymentMethods.all]
from:self
delegate:self
];
```
{% aside type="important" %}
When an offline payment is queued, it hasn't yet been processed by Square. The transaction isn't returned from the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and doesn't have a Square payment ID value. If your application's workflow involves delayed payment capture or syncing Square payments with an outside transaction database, you must write logic to query Square for the completed payment and its details and then perform that sync. For more information, see [Payment IDs](#payment-ids).
{% /aside %}
## Access offline payments
The Mobile Payments SDK provides the `getOfflinePaymentQueue()` method in the Payment Manager to access all payments taken offline by the application on the current mobile device. This includes queued payments waiting to be processed and completed processed payments. Only payments that have a `locationId` matching the current application user's location ID are returned. This prevents two Square sellers logging in to your application on the same mobile device from viewing each other's payments.
The `status` of an `SQMPOfflinePayment` indicates its current point in the payment workflow and whether it failed to upload or process. The `status` can be one of the following:
* `QUEUED` - The payment is stored locally on the device running the Mobile Payments SDK application. The SDK attempts to upload the payment to Square after the network connection is restored.
* `UPLOADED` - The payment has been uploaded to the Square server, but hasn't yet been processed.
* `FAILED_TO_UPLOAD` - The payment couldn't be uploaded due to an unrecoverable error.
* `FAILED_TO_PROCESS` - The connection was restored, but Square couldn't process this specific offline payment. This might be because of a declined card or another error with the card-issuing bank. An offline payment with this status cannot be recovered, and the seller doesn't receive funds from the transaction.
* `PROCESSED` - Square processed your offline payment successfully. It can now be seen in the Square Dashboard.
```objectivec
id offlinePaymentQueue = SQMPMobilePaymentsSDK.shared.paymentManager.offlinePaymentQueue;
// Grab total amount stored
[offlinePaymentQueue getTotalStoredPaymentsAmountWithCompletion:^(SQMPMoney *money, NSError *error) {
if (error) {
NSLog(@"Error getting total stored payments amount: %@", error.userInfo);
return;
}
NSLog(@"Total stored amount: %lu", money.amount);
}];
// Grab offline payments
[offlinePaymentQueue getPaymentsWithCompletion:^(NSArray> *offlinePayments, NSError *error) {
if (error) {
NSLog(@"Error getting offline payments: %@", error.userInfo);
return;
}
// Get the total number of payments currently stored
NSLog(@"Number of offline payments: %lu", offlinePayments.count);
// Iterate over the offline payments
for (id offlinePayment in offlinePayments) {
switch (offlinePayment.status) {
case SQMPOfflineStatusQueued:
// Payment is retained on the local device; awaiting upload by Mobile Payments SDK.
break;
case SQMPOfflineStatusUploaded:
// Payment has been successfully uploaded to the Square Server.
break;
case SQMPOfflineStatusFailedToUpload:
// Upload of payment failed due to an unrecoverable error.
break;
case SQMPOfflineStatusFailedToProcess:
// Processing of offline payment by Square Server failed, possibly due to card decline or other transaction issue.
break;
case SQMPOfflineStatusProcessed:
// Offline payment has been successfully processed by Square Server and is now visible in the merchant dashboard.
break;
case SQMPOfflineStatusUnknown:
// The status is unknown; verification could not be completed.
break;
default:
// The status is unknown; verification could not be completed.
break;
}
}
}];
```
### Payment IDs
A payment taken offline with the Mobile Payments SDK has two identification values: `localID`, used to identify the payment on your mobile device before it's processed, and `id`, which represents the Square payment `id` value. The second value is always `null` until the SDK uploads the payment to Square and the payment is processed.
When a payment's status changes to `PROCESSED`, you can access its `id` value from the mobile device and match it to the `id` value of payments returned by the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint. You can now continue your application's payment workflow and use other Square APIs to access and manage the payment. `PROCESSED` payments are deleted from the mobile device to conserve storage space.
```objectivec
@interface MyViewController ()
@end
@implementation MyViewController
- (void)paymentManager:(id)paymentManager didFinish:(id)payment {
if ([payment conformsToProtocol:@protocol(SQMPOnlinePayment)]) {
id onlinePayment = (id)payment;
NSLog(@"Online Payment - ID: %@, status: %lu", onlinePayment.id, onlinePayment.status);
} else if ([payment conformsToProtocol:@protocol(SQMPOfflinePayment)]) {
id offlinePayment = (id)payment;
NSLog(@"Offline Payment - ID: %@, status: %lu", offlinePayment.localID, offlinePayment.status);
}
}
@end
```
## Process offline payments
The Mobile Payments SDK regularly checks for network connectivity and a connection to Square servers so that queued payments can be processed. This is done automatically while the application is open in the foreground of the device. Assuming that there are no errors in the `SQMPPaymentParameters` or issues like cards being declined, the funds are available to the seller in the Square Dashboard and the payment can be accessed and managed by the [Payments API](https://developer.squareup.com/reference/square/payments-api) after this processing is complete.
{% aside type="important" %}
The following actions result in queued payments being removed from the device. If this happens before the payment is uploaded and processed, it cannot be processed and the seller doesn't receive funds from the transaction:
* Wiping the device cache
* Authenticating the Mobile Payments SDK with a different application ID on the same device
* Uninstalling the application from the device using the Mobile Payments SDK
{% /aside %}
Queued payments remain on the device when a user force-quits your application, switches to another application, or a seller logs out of your application. As a best practice, your application should query for any `QUEUED` payments on the device before calling `authorizationManager.deauthorize()`, so that you can alert the seller about any unprocessed payments.
---
# Handling Errors
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/ios/handling-errors
> Status: PUBLIC
> Languages: All
> Platforms: iOS
Learn how to resolve errors in the Mobile Payments SDK for iOS.
**Applies to:** [Mobile Payments SDK - iOS](https://developer.squareup.com/docs/sdk/mobile-payments/ios)
{% subheading %}Learn how to resolve errors in the Mobile Payments SDK for iOS.{% /subheading %}
{% toc hide=true /%}
## Authorization errors
Errors might be returned when using the `AuthorizationManager`. These errors are surfaced by the `AuthorizeCompletionHandler` as part of `AuthorizationManager.authorize()`. To unwrap the returned authorization error message, include the following inside your error handling code:
```swift
if let authError = AuthorizationError(rawValue: (error as NSError).code) {
print(authError.debugInfo)
}
```
{% table %}
* Error {% width="275px" %}
* Description
---
* `alreadyAuthorized`
* This device is already authorized with a Square account.
---
* `alreadyInProgress`
* An authorization is already in progress. Wait for this action to complete and try again.
---
* `authorizationCodeAlreadyRedeemed`
* The authorization code for this session was already used. Have the seller reauthorize their Square account with your application.
---
* `deauthorizationInProgress`
* A deauthorization is already in progress. Wait for this action to complete and try again.
---
* `deviceTimeDoesNotMatchServerTime`
* The local device time is out of sync with the server time. Check your device's time and attempt authorization again.
---
* `emptyAccessToken`
* No access token was provided to the `AuthorizationManager`.
---
* `emptyLocationID`
* No location ID was provided to the `AuthorizationManager`.
---
* `expiredAuthorizationCode`
* The authorization code for this session has expired. Have the seller reauthorize their Square account with your application.
---
* `invalidAccessToken`
* The access token provided to the `AuthorizationManager` is invalid.
---
* `invalidAuthorizationCode`
* The authorization code provided to the `AuthorizationManager` is invalid.
---
* `invalidLocationID`
* The location ID provided to the `AuthorizationManager` is invalid.
---
* `locationNotActivatedForCardProcessing`
* The seller's location isn't activated for credit card processing. Request the seller to reauthorize with another location ID.
---
* `notAuthorized`
* The Mobile Payments SDK isn't currently authorized with a Square seller account. Use the `AuthorizationManager` to authorize a Square account.
---
* `noNetwork`
* The Mobile Payments SDK couldn't connect to the network.
---
* `unexpected`
* An unexpected error occurred. Check your application's local logs for further information and contact Square developer support if the issue persists.
---
* `unsupportedCountry`
* The seller using your application is in a country unsupported by the Mobile Payments SDK.
{% /table %}
## Bluetooth and pairing errors
Errors might be returned when pairing readers using the `ReaderManager`. These errors are surfaced by the `ReaderPairingDelegate` as part of `ReaderPairingDidFail(withError error: Error)`. To unwrap the returned bluetooth or pairing error message, include the following inside your error handling code:
```swift
if let pairingError = ReaderPairingError(rawValue: (error as NSError).code) {
print(pairingError.debugInfo)
}
```
{% table %}
* Error {% width="275px" %}
* Description
---
* `bluetoothDisabled`
* Bluetooth was disabled by the user. Prompt them to enable Bluetooth and try again.
---
* `bluetoothNotReady`
* The Bluetooth connection isn't ready. Wait and try again.
---
* `bluetoothNotSupported`
* The device doesn't support Bluetooth.
---
* `bluetoothPermissionDenied`
* Bluetooth access has been denied by the user. You should check for Bluetooth permission before trying to pair a reader.
---
* `bluetoothPermissionNotDetermined`
* The Mobile Payments SDK couldn't determine your application's Bluetooth permission. You should check for Bluetooth permission before trying to pair a reader.
---
* `bluetoothPermissionRestricted`
* Your application's Bluetooth access has been restricted in settings. You should check for Bluetooth permission before trying to pair a reader.
---
* `bluetoothPermissionUnknownCase`
* The Mobile Payments SDK couldn't determine your application's Bluetooth permission. You should check for Bluetooth permission before trying to pair a reader.
---
* `bluetoothResetting`
* Bluetooth is resetting. Try pairing again.
---
* `bluetoothUnknownError`
* An unknown Bluetooth error occurred.
---
* `bondingRemoved`
* An unknown Bluetooth error occurred. Prompt the user to go to the Bluetooth settings on their device and "forget" the reader they're attempting to pair. Then reopen your application and try pairing again.
---
* `failedToConnect`
* The Mobile Payments SDK failed to connect to the reader. Try pairing the reader again.
---
* `notSupported`
* Your application is currently authorized in a Square Sandbox account, where reader pairing isn't supported. Reauthorize with a production account.
---
* `readerAlreadyPairing`
* There is already a reader pairing in progress. Wait for the pairing to complete and try again.
---
* `sandboxNotSupported`
* Bluetooth reader pairing isn't supported in the Square Sandbox. Use a production account to authorize and test reader pairing.
---
* `simulatorNotSupported`
* Bluetooth reader pairing isn't supported on iOS simulators. Test on a physical device with Square hardware or use a mock reader with a Square Sandbox account in the simulator.
---
* `timedOut`
* The Mobile Payments SDK timed out while trying to pair with nearby readers. Try the pairing again.
---
* `updateRequired`
* This version of the Mobile Payments SDK isn't compatible with the reader. Update the SDK or use a compatible reader.
{% /table %}
## Reader connection errors
Errors might be returned if readers are unable to connect to Square servers. These errors are surfaced within `ReaderInfo.connectionInfo` and the `ReaderConnectionFailureInfo.failureReason`. If you receive one of these errors, you can check the [Square status page](https://issquareup.com/) or contact Square developer support if the issue persists.
{% table %}
* Error {% width="200px" %}
* Description
---
* `deniedByServer`
* The connection was denied by the Square server.
---
* `genericError`
* A generic error occurred.
---
* `maxReadersConnected`
* The maximum number of readers are connected to your application. Unpair some readers and try again.
---
* `networkTimeout`
* The network timed out before the reader could connect. Try your action again.
---
* `networkTransportError`
* There was a network error while connecting to Square.
---
* `notConnectedToInternet`
* There is no Internet connection and the reader couldn't establish a connection to Square.
---
* `readerTimeout`
* The connection timed out while updating the reader firmware.
---
* `revokedByDevice`
* A device error occurred while attempting to establish a connection to Square.
---
* `serverError`
* There was a server error while connecting to Square.
---
* `unknown`
* An unknown error occurred.
{% /table %}
## Reader update errors
Errors related to reader firmware updates occurred. These errors are surfaced within `ReaderInfo.firmwareInfo.failureReason`. To unwrap the returned reader update error message, include the following inside your error handling code:
```swift
if let updateError = ReaderFirmwareUpdateError(rawValue: (error as NSError).code) {
print(updateError.debugInfo)
}
```
{% table %}
* Error {% width="200px" %}
* Description
---
* `connectionTimeout`
* The connection timed out while updating the reader firmware.
---
* `firmwareFailure`
* The reader firmware failed during an update.
---
* `serverCallFailure`
* The Mobile Payments SDK failed to connect to the server while updating the reader firmware.
---
* `unknownError`
* An unknown error occurred while updating the reader firmware.
{% /table %}
## Payment errors
Errors might be returned when taking a payment with the `PaymentManager`. These errors are surfaced by the `PaymentManagerDelegate` as part of `paymentManager(_ paymentManager: PaymentManager, didFail payment: Payment, withError error: Error)`. To unwrap the returned payment error message, include the following inside your payment error handling code:
```swift
if let paymentError = PaymentError(rawValue: (error as NSError).code) {
print(paymentError.debugInfo)
}
```
For errors that occur during the [payment flow](mobile-payments-sdk/ios/take-payments#start-the-payment), the Mobile Payments SDK provides an error screen as part of the payment UI. This is shown to the user for `invalidPaymentParameters`, `idempotencyKeyReused`, `notAuthorized`, and `unexpected` errors. `timedOut` and `unsupportedMode` errors present a similar screen with error details.
{% table %}
* Error {% width="300px" %}
* Description
---
* `deviceTimeDoesNotMatchServerTime`
* The local device time is out of sync with the server time, which could lead to inaccurate payment reporting. Check your device's time and attempt your action again.
---
* `invalidPaymentParameters`
* The `PaymentParameters` provided were invalid. Check the request details and try the payment again.
---
* `invalidPaymentSource`
* The payment source provided didn't match the `AlternatePaymentMethod` given. Check the request details and try the payment again.
---
* `locationPermissionNeeded`
* Location permission hasn't been granted to your application. Prompt the user for location access and try the payment again.
---
* `idempotencyKeyReused`
* The idempotency key used for this payment has already been used. Review previous payments to ensure you're not processing a duplicate payment and then try again with a new idempotency key.
---
* `merchantNotOptedIntoOfflineProcessing`
* The seller using your application isn't part of the [Offline Payments feature](mobile-payments-sdk/ios/offline-payments) and cannot take offline payments with the Mobile Payments SDK.
---
* `noNetwork`
* The Mobile Payments SDK couldn't connect to the network and the payment couldn't be completed.
---
* `notAuthorized`
* The Mobile Payments SDK isn't currently authorized with a Square seller account. Use the `AuthorizationManager` to authorize a Square account.
---
* `offlineStoredAmountExceeded`
* Your application has exceeded the total amount available to be stored on the device. Wait until connection is restored and stored payments have processed before taking more offline payments.
---
* `offlineTransactionAmountExceeded`
* Your application is attempting an offline payment that exceeds the limit for a single transaction. Try again with a lower payment amount.
---
* `sandboxUnsupportedForOfflineProcessing`
* Your application is attempting to take an offline payment while authorized with a Square Sandbox account. Offline payments aren't supported in the Square Sandbox. Reauthorize with a production account to take offline payments.
---
* `paymentAlreadyInProgress`
* A payment is already in progress. Cancel the current payment or wait for it to complete. Then try the new payment again.
---
* `timedOut`
* The Mobile Payments SDK timed out while awaiting a payment. Try the payment again.
---
* `unsupportedMode`
* The user entered an unsupported mode while a payment was in process (for example, split screen mode isn't supported in the Mobile Payments SDK). Try the payment again.
---
* `unexpected`
* `PaymentManager.startPayment` was used in an unexpected or unsupported way. Check your local logs and try the payment again.
{% /table %}
## Offline payment queue errors
Errors might be returned when working with [offline payments](mobile-payments-sdk/ios/offline-payments). These errors are surfaced as part of the `OfflinePaymentQueue`'s `getTotalStoredPaymentsAmount(completion: TotalStoredPaymentsAmountCompletionHandler)` and
`getPayments(completion: GetOfflinePaymentsCompletionHandler)`.
{% table %}
* Error {% width="200px" %}
* Description
---
* `notAuthorized`
* The Mobile Payments SDK isn't currently authorized with a Square seller account. Use the `AuthorizationManager` to authorize a Square account.
---
* `unsupportedSandboxEnvironment`
* Your application is attempting to take an offline payment while authorized with a Square Sandbox account. Offline payments aren't supported in the Square Sandbox. Reauthorize with a production account to take offline payments.
---
* `unexpected`
* An unexpected error occurred. Check your application's local logs for further information and contact Square developer support if the issue persists.
{% /table %}
---
# Authorize your Android Application
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/configure-authorize
> Status: PUBLIC
> Languages: All
> Platforms: Android
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [OAuth API](oauth-api/overview) | [Locations API](locations-api) | [Payments API](payments-refunds)
{% subheading %}Learn how to configure and authorize your Mobile Payments SDK Android application.{% /subheading %}
{% toc hide=true /%}
## Overview
To enable your application to securely connect to a Square seller account, the Mobile Payments SDK must be authorized using an [OAuth access token](oauth-api/what-it-does) and a [location ID](locations-api). Each Square seller who uses your application must be authorized with an OAuth access token. The same process should be used even if you only plan to use the Mobile Payments SDK with your own Square account. To get started, see [OAuth documentation](oauth-api/what-it-does) and the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-android) for an example of how to authorize the SDK.
When requesting an OAuth access token from a seller, your application must request the following permissions:
* `MERCHANT_PROFILE_READ` is required to get a list of all of a seller's locations.
* `PAYMENTS_WRITE` and `PAYMENTS_WRITE_IN_PERSON` are required to take payments with the Mobile Payments SDK.
* `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` is required if you want to collect [application fees](payments-api/take-payments-and-collect-fees).
The Mobile Payments SDK is divided into [four managers](mobile-payments-sdk#mobile-payments-sdk-components) to provide specific areas of functionality. Authorization is handled by the `AuthorizationManager`. Use `authorizationManager.authorize()` to authorize your Mobile Payments SDK application with a Square seller's `accessToken` and `locationId`. You also pass in a `callback` to be notified of authorization errors and successes and display those to the user.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
override fun onResume() {
super.onResume()
val authorizationManager = MobilePaymentsSdk.authorizationManager()
// Authorize and handle authorization successes or failures
callbackReference = authorizationManager.authorize(accessToken, locationId) { result ->
when (result) {
is Success -> {
finishWithAuthorizedSuccess(result.value)
}
is Failure -> {
when (result.errorCode) {
NO_NETWORK -> // show error message and retry suggestion
...
USAGE_ERROR -> // show error message
...
}
}
}
}
}
override fun onPause() {
super.onPause()
// Remove the callback reference to prevent memory leaks
callbackReference?.clear()
}
```
{% /tab %}
{% tab id="Java" %}
```java
@Override protected void onResume() {
super.onResume();
AuthorizationManager authorizationManager = MobilePaymentsSdk.authorizationManager();
// Authorize and handle authorization successes or failures
callbackReference = authorizationManager.authorize(accessToken, locationId, result -> {
if (result.isSuccess()) {
finishWithAuthorizedSuccess(result.value());
} else {
AuthorizeErrorCode authorizeErrorCode = result.errorCode();
switch (authorizeErrorCode) {
case NO_NETWORK:
// show error message and retry suggestion
...
break;
case USAGE_ERROR:
// show error message
...
break;
}
}
});
}
@Override protected void onPause() {
super.onPause();
// Remove the callback reference to prevent memory leaks
callbackReference.clear();
}
```
{% /tab %}
{% /tabset %}
## Authorization state
You can check whether a user of your application is currently authorized by checking `AuthorizationState.isAuthorized()` prior to beginning authorization.
To track changes in the authorization state, register a callback by using `authorizationManager.setAuthorizationStateChangedCallback()`. This callback can give you live updates to the `authorizationManager.authorizationState` whenever the Mobile Payments SDK is authorized or deauthorized.
## Session expiration
Square OAuth access tokens expire after 30 days. After expiration, applications must generate a new OAuth access token using the refresh token received [when the authorization was first granted](oauth-api/receive-and-manage-tokens). The response looks like the following:
```json
{
"access_token": "EAAAEL_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n",
"token_type": "bearer",
"expires_at": "2024-05-15T19:36:00Z",
"merchant_id": "TVSNN09QQY609",
"refresh_token": "EQAAEInZRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9"
}
```
Square recommends tracking the `expires_at` value on your server and refreshing the authorization token before it expires. If the SDK detects an expired token, it deauthorizes the Square seller account and invokes the callback registered with `setAuthorizationStateChangedCallback` with `AuthorizationState(isAuthorized = false, isAuthorizationInProgress = false)`.
## Deauthorize the Mobile Payments SDK
To deauthorize the Mobile Payments SDK and log out of a seller's Square account, use `authorizationManager.deauthorize()`. This method provides a completion handler, called when the SDK finishes deauthorizing.
The seller remains authorized as long as their access token is valid. Therefore, it is a good idea to call this method when a user logs out of your application or has not had any activity within a period of time. This prevents your application from tracking a large number of dangling authorizations. Calling `authorizationManager.deauthorize()` doesn't expire a user's OAuth access token, it only deauthorizes the user from the mobile device running the Mobile Payments SDK.
## Next steps
After authorizing your application, you're ready to [pair a card reader](mobile-payments-sdk/android/pair-manage-readers) and prepare to start [taking payments](mobile-payments-sdk/android/take-payments).
---
# Pair and Manage Card Readers
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/pair-manage-readers
> Status: PUBLIC
> Languages: All
> Platforms: Android
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android)
{% subheading %}Learn how to pair and manage card readers with the Mobile Payments SDK for Android.{% /subheading %}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK's `ReaderManager` lets you pair and monitor changes in [Square Readers](https://squareup.com/shop/hardware/us/en/products/chip-credit-card-reader-with-nfc).
{% aside type="tip" %}
Physical reader devices cannot be used in the Square Sandbox. For testing purposes, you can use the [Mock Reader UI](mobile-payments-sdk/android#mock-readers) to pair simulated readers and process mock payments with your application in the Square Sandbox.
{% /aside %}
## Settings Manager
The Mobile Payments SDK offers a preconfigured reader settings screen, built from the SDK's public API, that you can use in your application by calling `settingsManager.showSettings()`. This screen includes two tabs. The **Devices** tab displays the model and connection status for readers paired to the merchant's phone or tablet and includes a button for pairing a new reader. The **About** tab displays information about the Mobile Payments SDK, authorized location, and environment used to take payments. Users can also enable or disable consent for [performance and analytics tracking](mobile-payments-sdk/android#data-privacy-consent) from this screen, if they are in a region where consent is required.
Use the `SettingsManager` to programmatically retrieve information about the current `sdkEnvironment` (`PRODUCTION` or `SANDBOX`) and the current `sdkVersion`. You can also retrieve `PaymentSettings` for [offline payments](mobile-payments-sdk/android/offline-payments) with `settingsManager.getPaymentSettings`.
### Settings screen lifecycle
You can check whether the settings screen is currently displayed with `settingsManager.isShowingSettings()` and programmatically dismiss it with `settingsManager.closeSettings()`. This is useful for kiosks, or when your application needs to respond to external events while settings are open.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun showSettings() {
val settingsManager = MobilePaymentsSdk.settingsManager()
settingsManager.showSettings { result ->
when (result) {
is Success -> {
val settingsClosed = result.value
logSettingsResult(settingsClosed)
}
is Failure -> {
logSettingsFailure(result.errorCode, result.errorMessage)
}
}
}
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void showSettings() {
SettingsManager settingManager = MobilePaymentsSdk.settingsManager();
settingManager.showSettings(result -> {
if (result.isSuccess()) {
SettingsClosed settingsClosed = result.value();
logSettingsResult(settingsClosed);
} else {
logSettingsFailure(result.errorCode(), result.errorMessage());
}
return null;
});
}
```
{% /tab %}
{% /tabset %}
## Reader Manager
For more control over your reader pairing and management screens, you can create your own using information from the SDK's `ReaderManager`, which provides methods for pairing and forgetting readers, accessing information about a particular reader, and listening for reader status updates.
### Pairing a reader
Pair a new reader using `readerManager.pairReader()`. Only one reader pairing can be in progress at one time, so check the Boolean value `readerManager.isPairingInProgress` and only begin pairing if it's `false`. `readerManager.pairReader` consumes a `callback` to notify your application when pairing completes. Use this callback to update progress indicators in your application and provide notifications to users based on whether reader pairing is successful.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun pairReader() {
val readerManager = MobilePaymentsSdk.readerManager()
pairingHandle = readerManager.pairReader { result ->
when (result) {
is Success -> {
val readerFound = result.value
logPairingResult(readerFound)
}
is Failure -> {
logPairingFailure(result.errorCode, result.errorMessage)
}
}
}
}
fun onPause() {
pairingHandle?.stop()
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void pairReader() {
ReaderManager readerManager = MobilePaymentsSdk.readerManager();
pairingHandle = readerManager.pairReader(result -> {
if (result.isSuccess()) {
boolean readerFound = result.value();
logPairingResult(readerFound);
} else {
logPairingFailure(result.errorCode(), result.errorMessage());
}
});
}
public void onPause() {
if (pairingHandle != null) {
pairingHandle.stop();
}
}
```
{% /tab %}
{% /tabset %}
The pairing callback is guaranteed to be called when pairing ends, even if no reader was successfully paired. When pairing completes, this callback's `success` value is a Boolean for whether a card reader paired. If the value is `true` a card reader was found, reported to the callback provided using `setReaderChangedCallback`, and added to the list of paired readers accessed with `ReaderManager.getReaders()`. A `false` value means the pairing was canceled. If pairing fails for any reason, the error description contains a `PairingErrorCode` with [details about the failure](mobile-payments-sdk/android/handling-errors).
The Mobile Payments SDK also provides the `setReaderChangedCallback`, which is called when the [status of a reader](#reader-status) changes. Use this callback to notify your application when magstripe readers are inserted or removed, contactless and chip readers are paired or disconnected with Bluetooth, or the battery status changes.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun observeReaderChanges() {
val readerManager = MobilePaymentsSdk.readerManager()
callbackReference = readerManager.setReaderChangedCallback { event ->
val reader = event.reader
val change = event.change
val readerStatus = event.readerStatus
when (change) {
ADDED -> // show reader added message
REMOVED -> // show reader removed message
else -> // handle other reader status changes
}
}
}
fun onPause() {
callbackReference?.clear()
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void observeReaderChanges() {
ReaderManager readerManager = MobilePaymentsSdk.readerManager();
callbackReference = readerManager.setReaderChangedCallback(event -> {
ReaderInfo reader = event.getReader();
ReaderChangedEvent.Change change = event.getChange();
ReaderInfo.Status readerStatus = event.getReaderStatus();
switch (change) {
case ADDED:
// show reader added message
break;
case REMOVED:
// show reader removed message
break;
default:
// handle other reader status changes
break;
}
});
}
public void onPause() {
if (callbackReference != null) {
callbackReference.clear();
}
}
```
{% /tab %}
{% /tabset %}
Paired readers are remembered by the Mobile Payments SDK, so when a new card reader is paired to the application, it remains paired and present in the list of readers provided by `readerManager.getReaders()` and will automatically reconnect when the authorized Square seller loads your application. If you want to stop pairing before it completes, you can do so with the returned `pairingHandle` by calling `pairingHandle.stop()`.
## Reader information
The `ReaderInfo` class provides information about Square readers paired with your application. These properties include:
* The battery level and charging status.
* The model (contactless and chip or magstripe).
* The serial number.
* The firmware info, including version and update status (see [Firmware info](#firmware-info)).
* The card entry methods supported by the reader (`CONTACTLESS`, `EMV`, or `SWIPED`).
You can use this information to notify merchants when a reader is unpaired or its battery is low. You can create your own screens to display information about the status of readers or use a [Square-provided settings screen](#settings-manager) for quick integration.
### Card entry methods
Different readers offer different card entry methods. For example, Square Reader for magstripe can only accept swiped cards, while Square Reader for contactless and chip can accept tapped cards, dipped cards, or digital wallets. The card entry methods supported are available within a reader's `readerInfo.supportedCardEntryMethods`. To track changes in the entry methods (for example, if the NFC connection to a contactless reader times out) register a callback with `paymentManager.setAvailableCardEntryMethodChangedCallback`.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
private fun updateAvailableMethods(view: TextView) {
val paymentManager = MobilePaymentsSdk.paymentManager()
// Set up a callback to update the card entry methods when they change
callbackRef = paymentManager.setAvailableCardEntryMethodChangedCallback { methods ->
updateCardEntryMethods(view, methods)
}
// Update the card entry methods immediately
updateCardEntryMethods(view, paymentManager.getAvailableCardEntryMethods())
}
private fun updateCardEntryMethods(view: TextView, methods: Set) {
view.text = when (methods.size) {
0 -> "Reader not connected"
1 -> when (methods.first()) {
CardEntryMethod.SWIPED -> "Swipe to pay"
CardEntryMethod.CONTACTLESS -> "Tap to pay"
CardEntryMethod.EMV -> "Insert to pay"
}
// Etc..
}
}
```
{% /tab %}
{% tab id="Java" %}
```java
private void updateAvailableMethods(TextView view) {
PaymentManager paymentManager = MobilePaymentsSdk.paymentManager();
// Set up a callback to update the card entry methods when they change
callbackReference = paymentManager.setAvailableCardEntryMethodChangedCallback(
methods -> updateCardEntryMethods(view, methods)
);
// Update the card entry methods immediately
updateCardEntryMethods(view, paymentManager.getAvailableCardEntryMethods());
}
private void updateCardEntryMethods(TextView view, Set methods) {
int size = methods.size();
if (size == 0) {
view.setText("Reader not connected");
} else if (size == 1) {
CardEntryMethod next = methods.iterator().next();
if (next == CardEntryMethod.SWIPED) {
view.setText("Swipe to pay");
} else if (next == CardEntryMethod.CONTACTLESS) {
view.setText("Tap to pay");
} else if (next == CardEntryMethod.EMV) {
view.setText("Insert to pay");
}
// Etc..
}
}
```
{% /tab %}
{% /tabset %}
### Reader status
Your application can monitor the current status of connected readers with `readerInfo.status` to display updates and messages to users. The possible status values are:
* `Ready`: The reader is paired, connected, and able to accept card payments.
* Magstripe readers connect automatically and are always `Ready` until physically disconnected from the mobile device.
* `ConnectingToSquare`: The reader is establishing a connection to Square's servers.
* `ConnectingToDevice`: The reader is establishing a connection to the mobile device.
* `Faulty`: The reader has encountered a hardware or connection error and is in an unrecoverable state.
* `ReaderUnavailable`: The reader is connected but not able to take payments.
If a reader is unavailable, check `ReaderUnavailable.reason` for specific details, which may include bluetooth failure, a blocking firmware update, or issues with the merchant’s Square account. Depending on the reason, you can prompt the user to take action, or retry the connection with Square's servers with `readerManager.retryConnection()`.
{% aside type="info" %}
`readerInfo.status` is available in Android Mobile Payments SDK version `2.3.0` and above. If your integration uses an earlier version of the SDK, monitor the status of connected readers with `readerInfo.state`. The available states are `Connecting`, `UpdatingFirmware`, `Disconnected`, or `FailedToConnect`.
{% /aside %}
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun getReaders() {
val readerManager = MobilePaymentsSdk.readerManager()
val readers = readerManager.getReaders()
// All readers ready to take payments
val availableReaders = readers.filter {
it.status == Ready
}.size
// All readers accepting tap payments
val contactlessReaders = readers.filter {
it.supportedCardEntryMethods.contains(CONTACTLESS)
}
// A specific Square reader
val specificReader = readers.find {
it.serialNumber == "4815162342LS815"
}
// Etc..
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void getReaders() {
ReaderManager readerManager = MobilePaymentsSdk.readerManager();
List readers = readerManager.getReaders();
// Do something with the readers
int availableReaders = 0;
List contactlessReaders = new ArrayList<>();
ReaderInfo specificReader = null;
for (ReaderInfo reader : readers) {
if (reader.getStatus() instanceof ReaderInfo.Status.Ready) {
availableReaders++;
}
if (reader.getSupportedCardEntryMethods()
.contains(CardEntryMethod.CONTACTLESS)) {
contactlessReaders.add(reader);
}
if (Objects.equals(reader.getSerialNumber(), "4815162342LS815")) {
specificReader = reader;
}
}
// Etc..
}
```
{% /tab %}
{% /tabset %}
### Firmware info
The `ReaderInfo.firmwareInfo` property provides structured firmware data through the `ReaderFirmwareInfo` class, which includes:
* `version: String?` — The current firmware version installed on the reader.
* `updateStatus: FirmwareUpdateStatus` — The current firmware update status, represented as a sealed class with the following values:
- `None` — No firmware update is available or in progress.
- `Pending(updateDate: Date)` — A firmware update is scheduled for the specified date.
- `InProgress(updatePercentage: Int?)` — A firmware update is currently being installed, with an optional progress percentage.
{% aside type="warning" %}
__Deprecation notice:__
* `readerInfo.firmwareVersion` is deprecated. Use `readerInfo.firmwareInfo.version` instead.
* `readerInfo.firmwarePercent` is deprecated. Use `readerInfo.firmwareInfo.updateStatus` instead.
{% /aside %}
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun checkFirmwareStatus() {
val readerManager = MobilePaymentsSdk.readerManager()
val readers = readerManager.getReaders()
for (reader in readers) {
val firmwareInfo = reader.firmwareInfo
println("Firmware version: ${firmwareInfo.version}")
when (val status = firmwareInfo.updateStatus) {
is FirmwareUpdateStatus.None -> println("Firmware is up to date")
is FirmwareUpdateStatus.Pending -> println("Update scheduled for: ${status.updateDate}")
is FirmwareUpdateStatus.InProgress -> println("Updating: ${status.updatePercentage ?: "unknown"}%")
}
}
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void checkFirmwareStatus() {
ReaderManager readerManager = MobilePaymentsSdk.readerManager();
List readers = readerManager.getReaders();
for (ReaderInfo reader : readers) {
ReaderFirmwareInfo firmwareInfo = reader.getFirmwareInfo();
Log.d("Firmware", "Version: " + firmwareInfo.getVersion());
FirmwareUpdateStatus status = firmwareInfo.getUpdateStatus();
if (status instanceof FirmwareUpdateStatus.None) {
Log.d("Firmware", "Firmware is up to date");
} else if (status instanceof FirmwareUpdateStatus.Pending) {
Log.d("Firmware", "Update scheduled for: " +
((FirmwareUpdateStatus.Pending) status).getUpdateDate());
} else if (status instanceof FirmwareUpdateStatus.InProgress) {
Log.d("Firmware", "Updating: " +
((FirmwareUpdateStatus.InProgress) status).getUpdatePercentage() + "%");
}
}
}
```
{% /tab %}
{% /tabset %}
### Preferred firmware update time
You can schedule firmware updates to occur at a preferred time of day using `readerSettings.preferredFirmwareUpdateTime`. This property accepts a `TimeOfDay` value with `hour` (0–23) and `minute` (0–59) properties. Setting this value allows sellers to schedule reader firmware updates during off-hours to avoid interruptions during business operations.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun setFirmwareUpdateTime() {
val readerManager = MobilePaymentsSdk.readerManager()
val readerSettings = readerManager.readerSettings
// Schedule firmware updates for 2:00 AM
readerSettings.preferredFirmwareUpdateTime = TimeOfDay(hour = 2, minute = 0)
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void setFirmwareUpdateTime() {
ReaderManager readerManager = MobilePaymentsSdk.readerManager();
ReaderSettings readerSettings = readerManager.getReaderSettings();
// Schedule firmware updates for 2:00 AM
readerSettings.setPreferredFirmwareUpdateTime(new TimeOfDay(2, 0));
}
```
{% /tab %} {% /tabset %}
### Unpairing a reader
Paired contactless and chip readers are remembered by the Mobile Payments SDK and remain paired until forgotten with `readerManager.forget(reader)` or by long-pressing the reader device's pair button. You can also unpair a reader using the Mobile Payments SDK [Settings screen](#settings-manager) UI.
## Next steps
To test your application in the Square Sandbox without a physical Square reader, use the Mobile Payments SDK [Mock Reader UI](mobile-payments-sdk/android#mock-readers) to simulate a reader and accept test payments. When you've successfully paired a physical Square Reader device, you're ready to [take payments](mobile-payments-sdk/android/take-payments) in a production environment.
---
# Take a Payment
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/take-payments
> Status: PUBLIC
> Languages: All
> Platforms: Android
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Payments API](payments-refunds) | [Orders API](orders-api/what-it-does)
{% subheading %}Learn how to use the Mobile Payments SDK for Android to take a payment with a Square Reader.{% /subheading %}
{% toc hide=true /%}
## Overview
Payments in the Mobile Payments SDK are handled by the `PaymentManager`. Prior to starting a payment, you create `PaymentParameters` to represent details of an individual payment and `PromptParameters` indicating how the payment prompts are presented to the buyer.
## Requirements and limitations
Before taking a payment with the SDK in a production environment, ensure that you have done the following:
* [Requested the permissions](mobile-payments-sdk/android#device-permissions) necessary for the type of reader you're using.
* [Installed and initialized](mobile-payments-sdk/android#quickstart) the Mobile Payments SDK in your Android application.
* [Authorized the Mobile Payments SDK](mobile-payments-sdk/android/configure-authorize) with a Square account.
Additionally, before taking a payment in production, you can test your application using [mock readers](mobile-payments-sdk/android#mock-readers) and the Square Sandbox or download the [Mobile Payments SDK sample application](https://github.com/square/mobile-payments-sdk-android) to see an example payment implementation.
## Create payment parameters
To begin a payment with the Mobile Payments SDK, you need to create a `PaymentParameters` object, which includes attributes describing the payment you want to take. For example, there are parameters for the payment amount, optional tip, application fee (if applicable), and the processing mode, which determines whether [payments can be taken offline](mobile-payments-sdk/android/offline-payments). `AUTO_DETECT` is the recommended `processingMode`, as this directs the payment online or offline based on the highest chance of success. For this reason, the resulting Payment object might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both if you're using the `AUTO_DETECT` processing mode. Merchants can optionally add [card surcharges](#card-surcharging) to payments, and your application can allow or override that setting with the `allowCardSurcharge` parameter.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val paymentParams = PaymentParameters.Builder(
amount = Money(100, CurrencyCode.USD),
processingMode = ProcessingMode.AUTO_DETECT,
allowCardSurcharge = true
)
.paymentAttemptId("unique-attempt-id")
.build()
```
{% /tab %}
{% tab id="Java" %}
```java
PaymentParameters paymentParams = new PaymentParameters.Builder(
new Money(100L, CurrencyCode.USD),
ProcessingMode.AUTO_DETECT,
true // allowCardSurcharge - enable surcharging
)
.paymentAttemptId("unique-attempt-id")
.build();
```
{% /tab %}
{% /tabset %}
For the complete list of payment parameter values and details, see the [Android technical reference](https://developer.squareup.com/docs/sdk/mobile-payments/android).
### Idempotency and payment attempts
{% aside type="important" %}
In the Mobile Payments SDK version `2.2.0` and earlier, you generated and added your own idempotency key in your `paymentParameters`. In version `2.3.0` and later, the `idempotencyKey` parameter is deprecated and you instead provide a `paymentAttemptId`.
This is the recommended way to handle idempotent payment requests in the Mobile Payments SDK, and offers both idempotency protection and support for Strong Customer Authentication (SCA) requirements.
{% /aside %}
[Square payment requests](https://developer.squareup.com/reference/square/payments-api/create-payment) contain an idempotency key, a unique string identifier which allows Square to recognize potential duplicate API calls. Using an idempotency key for each payment request ensures that a payment can only occur once, protecting against unintended outcomes like charging a customer twice for the same transaction.
When you provide a `paymentAttemptId` in your `paymentParameters` for each call to `startPaymentActivity`, the Mobile Payments SDK generates a unique idempotency key for the payment request, and stores it along with your payment attempt ID. If multiple requests are made for the same payment attempt (for example, during SCA flows), the SDK generates a new idempotency key for each request and updates the stored idempotency key for the given payment attempt ID. You can't include both an `idempotencyKey` and a `paymentAttemptId` in your `paymentParameters`, only one.
Along with a `paymentAttemptId`, you should include a unique `referenceId` value in your `PaymentParameters` for each payment. This persists with the payment and can be used to identify the payment within your own system if you need to reference it later. Your attempt ID and reference ID aren't interchangeable. You shouldn't use the same value for both parameters because sometimes a payment requires multiple attempts (for example, if the first payment attempt is declined for expiration or insufficient funds, you can retry the payment with the same `referenceId` and a new `paymentAttemptId`). Typically, the `referenceId` is used to match Square payments to an external system, but it can also be used to identify payments within Square.
If you don't receive a server response from a payment made with the Mobile Payments SDK, you should check its status to determine whether to attempt the payment again. Use the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and query by location ID, total payment amount, or other fields to filter the list. You can use your unique `referenceId` to identify the correct payment and check its status. You might need to make a new payment attempt if the prior payment exists, but cannot be completed. In this situation, retrieve the final idempotency key used for the payment attempt with your payment attempt ID using `paymentManager.getIdempotencyKey(paymentAttemptId: String)`, and cancel the incomplete payment by using [CancelPaymentByIdempotencyKey](https://developer.squareup.com/reference/square/payments-api/cancel-payment-by-idempotency-key).
## Create prompt parameters
Each payment also requires `PromptParameters`, consisting of a `mode` and a list of `additionalPaymentMethods`. `PromptParameters.mode` determines whether your application uses the `DEFAULT` Square payment prompt UI or a `CUSTOM` payment prompt where you build your own UI. The default UI provided by Square presents buyers with the payment options available from `paymentManager.availableCardInputMethods()`. While `PaymentParameters` are unique to each payment, you can likely reuse the same `PromptParameters` for most payments in your application.
`PromptParameters.additionalPaymentMethods` specifies a list of additional payment methods available to use for this payment. The current options are `KEYED` (a manually entered credit card payment) or `CASH`. When used with the `DEFAULT` `promptMode`, the Square payment prompt includes these alternative payment methods as options presented to buyers. If you create your own `CUSTOM` `promptMode`, you should use the `additionalPaymentMethods` available from the `PaymentHandle` to display these options to buyers in your own payment prompt UI.
## Start the payment
After the callbacks have been written, you can begin processing a payment by calling `paymentManager.startPaymentActivity()` with the `PaymentParameters` and `PromptParameters` you created previously and calling a `callback` to notify your application of results or [errors](mobile-payments-sdk/android/handling-errors) from the payment flow.
During the payment:
* The SDK provides a `PaymentHandle` as a way for you to interact with the ongoing payment (for example, if you need to [cancel the payment](#canceling-payments)).
* Square takes control of the screen display by launching a new Android Activity to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer.
When the payment completes, regardless of whether it completed successfully, control is returned to the user interface and the `callback` is invoked with the result. Your application can then display [receipt](#receipts) or [error](mobile-payments-sdk/android/handling-errors) information to the user.
{% aside type="info" %}
Only one payment can be in process at a time. If you make a second call to `startPaymentActivity` before the first call completes, the second call fails immediately with a `USAGE_ERROR`, triggering the payment callbacks. The first payment call continues.
{% /aside %}
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
fun startPaymentActivity() {
val paymentManager = MobilePaymentsSdk.paymentManager()
val paymentAttemptId = UUID.randomUUID().toString()
// Configure the payment parameters
val paymentParams = PaymentParameters.Builder(
amount = Money(100, CurrencyCode.USD),
paymentAttemptId = paymentAttemptId,
processingMode = processingMode(ProcessingMode.AUTO_DETECT),
allowCardSurcharge = true
)
.referenceId("1234")
.note("Chocolate Cookies and Lemonade")
.autocomplete(true)
.build()
// Configure the prompt parameters
val promptParams = PromptParameters(
mode = PromptMode.DEFAULT,
additionalPaymentMethods = listOf(AdditionalPaymentMethod
.Type.KEYED)
)
// Start the payment activity
paymentHandle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
// Handle the payment result
when (result) {
is Success -> // show payment details
is Failure -> // show error message
}
}
}
override fun onDestroy() {
paymentHandle?.cancel()
}
```
{% /tab %}
{% tab id="Java" %}
```java
public void startPaymentActivity() {
PaymentManager paymentManager = MobilePaymentsSdk.paymentManager();
String paymentAttemptId = UUID.randomUUID().toString();
// Configure the payment parameters
PaymentParameters paymentParams = new PaymentParameters.Builder(
new Money(100, CurrencyCode.USD),
paymentAttemptId,
ProcessingMode.AUTO_DETECT,
true
)
.referenceId("1234")
.note("Chocolate Cookies and Lemonade")
.autocomplete(true)
.build();
// Configure the prompt parameters
PromptParameters promptParams = new PromptParameters(
PromptMode.DEFAULT,
Collections.singletonList(AdditionalPaymentMethod.Type.KEYED)
);
// Start the payment activity
paymentHandle = paymentManager.startPaymentActivity(paymentParams, promptParams, result -> {
// Handle the payment result
if (result.isSuccess()) {
// show payment details
...
} else {
// show error message
...
}
});
}
@Override public void onDestroy() {
if (paymentHandle != null) {
paymentHandle.cancel();
}
}
```
{% /tab %}
{% /tabset %}
## Delay the capture of payments
As part of your application workflow, you might want to authorize a customer's transaction but delay the capture of the payment (the transfer of funds from the customer to the seller) for a period of time. For example, in a restaurant with a kiosk ordering system, you might want to authorize a customer's credit card when they order, but not complete the payment until they receive their food.
While creating `PaymentParameters` for a payment, set the `autocomplete` value to `false` if you want to delay the capture of a payment. By default, `autocomplete` is `true`, meaning the payment is authorized and captured immediately.
{% aside type="info" %}
Only one of the `autocomplete` and `acceptPartialAuthorization` values can be `true`. If you're accepting multiple payment methods for a single purchase (such as a gift card and credit card), you must set `autocomplete` to `false` and manage the delayed capture of the payment.
{% /aside %}
When `autocomplete` is `false`, there are two more `PaymentParameter` values that handle the delayed payment:
* `delayDuration` - The number of milliseconds to wait before canceling the payment or taking another `delayAction`, in RFC 3339 format. By default, this is 36 hours for card reader payments and 7 days for manually entered payments.
* `delayAction` - The action to take after the `delayDuration` passes with no other action on the payment. The possible options are `CANCEL` (which is the default) or `COMPLETE`.
You can add a tip to the delayed payment by calling the [UpdatePayment](https://developer.squareup.com/reference/square/payments-api/update-payment) endpoint and setting `tip_money` prior to completing the payment. If you don't set the `delayAction` to automatically complete the payment, you can manually complete it by calling `paymentManager.completePayment`.
For more information about delayed payment capture using the Square Payments API, see [Delayed Capture of a Card Payment](payments-api/take-payments/card-payments/delayed-capture).
## Card Surcharging
A surcharge is an additional amount or percentage that sellers can set to pass on credit card processing fees to buyers. Sellers optionally set a surcharge percentage in their Square Dashboard. As a Mobile Payments SDK developer, you can include this surcharge or choose to override the dashboard settings and disallow surcharges on card payments in your application.
{% aside type="important" %}
* Surcharges with the Mobile Payments SDK are only available for credit card payments made in the US.
* Surcharges are not available for offline payments, debit card payments, or pre-existing orders.
{% /aside %}
To add surcharges to credit card payments, your application must have `ITEMS_READ` permission in addition to the [standard payment permissions](mobile-payments-sdk#oauth-permissions).
Use the `allowCardSurcharge` parameter in your `PaymentParameters` to control whether surcharges can be applied to individual payments.
If you're using a custom payment prompt, use the use the `PaymentHandle.totalMoneyWithProposedCardSurcharge` to display surcharge amounts to customers before payment completion. This ensures transparency and compliance with surcharging regulations.
After an Online payment completes, access surcharge information from its `CardPaymentDetails` for receipt generation and record keeping:
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
private fun handlePaymentResult(result: Result) {
when (result) {
is Result.Success -> {
val payment = result.value
if (payment is Payment.OnlinePayment) {
val cardDetails = payment.cardDetails
val surchargeDetails = cardDetails?.appliedCardSurchargeDetails
if (surchargeDetails != null) {
val baseSurcharge = surchargeDetails.cardSurchargeMoney
val taxOnSurcharge = surchargeDetails.taxOnSurchargeMoney
val totalSurcharge = surchargeDetails.totalSurchargeMoney
// Display surcharge information to customer
println("Base surcharge: ${baseSurcharge.amount} ${baseSurcharge.currencyCode}")
println("Tax on surcharge: ${taxOnSurcharge?.amount ?: 0} ${baseSurcharge.currencyCode}")
println("Total surcharge: ${totalSurcharge.amount} ${totalSurcharge.currencyCode}")
// Use for receipt generation
generateReceiptWithSurcharge(payment, surchargeDetails)
} else {
// No surcharge was applied to this payment
generateStandardReceipt(payment)
}
}
}
is Result.Failure -> {
// Handle payment errors
handlePaymentError(result.errorCode)
}
}
}
```
{% /tab %}
{% tab id="Java" %}
```java
private void handlePaymentResult(Result result) {
if (result.isSuccess()) {
Payment payment = result.value();
if (payment instanceof Payment.OnlinePayment) {
Payment.OnlinePayment onlinePayment = (Payment.OnlinePayment) payment;
CardPaymentDetails.OnlineCardPaymentDetails cardDetails = onlinePayment.getCardDetails();
if (cardDetails != null) {
CardPaymentDetails.CardSurchargeDetails surchargeDetails =
cardDetails.getAppliedCardSurchargeDetails();
if (surchargeDetails != null) {
Money baseSurcharge = surchargeDetails.getCardSurchargeMoney();
Money taxOnSurcharge = surchargeDetails.getTaxOnSurchargeMoney();
Money totalSurcharge = surchargeDetails.getTotalSurchargeMoney();
// Display surcharge information to customer
System.out.println("Base surcharge: " + baseSurcharge.getAmount() + " " + baseSurcharge.getCurrencyCode());
System.out.println("Tax on surcharge: " + (taxOnSurcharge != null ? taxOnSurcharge.getAmount() : 0) + " " + baseSurcharge.getCurrencyCode());
System.out.println("Total surcharge: " + totalSurcharge.getAmount() + " " + totalSurcharge.getCurrencyCode());
// Use for receipt generation
generateReceiptWithSurcharge(payment, surchargeDetails);
} else {
// No surcharge was applied to this payment
generateStandardReceipt(payment);
}
}
}
} else {
// Handle payment errors
handlePaymentError(result.errorCode());
}
}
```
{% /tab %}
{% /tabset %}
## Canceling payments
If you need to cancel a payment in progress for any reason, use `paymentHandle.cancel()`. The `CancelResult` returned is `CANCELED`, `NO_PAYMENT_IN_PROGRESS` if there is no payment in progress to be canceled, or `NOT_CANCELABLE` if the payment in progress cannot be canceled. This can happen when the payment is actively being sent to Square servers or has already been completed.
During any payment flow, if the application is backgrounded or the application activity is interrupted, the payment in progress is canceled.
## Receipts
Your application must provide buyers with the option to receive a digital or printed receipt. These receipts aren't sent directly by Square. Therefore, to remain compliant with EMV-certification requirements, you must generate receipts including the following fields found in the `cardDetails` of the successful payment response object from `startPaymentActivity()`:
* `card.cardholderName` (example: James Smith)
* `card.brand` and `card.last4digits` (example: Visa 0094)
* `authorizationCode` (example: Authorization 262921) (not available for offline payments)
* `emvApplicationName` (example: AMERICAN EXPRESS)
* `emvApplicationId` (example: AID: A0 00 00 00 25 01 09 01)
* `entryMethod` (example: Contactless)
{% line-break /%}
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
private fun showPaymentDetails(payment: Payment, receiptScreen: ReceiptScreen) {
val cardDetails = (payment as OnlinePayment).cardDetails
val card = cardDetails!!.card
receiptScreen.setCardInformation(
card.cardholderName,
card.brand,
card.lastFourDigits
)
receiptScreen.setEmvInformation(
cardDetails.authorizationCode,
cardDetails.applicationName,
cardDetails.applicationId
)
receiptScreen.setEntryMethod(cardDetails.entryMethod)
}
```
{% /tab %}
{% tab id="Java" %}
```java
private void showPaymentDetails(Payment payment, ReceiptScreen receiptScreen) {
CardPaymentDetails.OnlineCardPaymentDetails cardDetails = payment.asOnlinePayment().getCardDetails();
Card card = cardDetails.getCard();
receiptScreen.setCardInformation(
card.getCardholderName(),
card.getBrand(),
card.getLastFourDigits());
receiptScreen.setEmvInformation(
cardDetails.getAuthorizationCode(),
cardDetails.getApplicationName(),
cardDetails.getApplicationId());
receiptScreen.setEntryMethod(cardDetails.getEntryMethod());
}
```
{% /tab %}
{% /tabset %}
---
# Offline Payments
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/offline-payments
> Status: BETA
> Languages: Java, Kotlin
> Platforms: Android
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android) | [Payments API](payments-refunds)
{% subheading %}Learn how to take offline payments with the Mobile Payments SDK for Android.{% /subheading %}
{% toc hide=true /%}
## Overview
The Mobile Payments SDK supports taking payments in offline mode, which allows you to take payments when a reader is used in a location with weak network connection or the application momentarily loses connection to Square servers. Offline payments are stored (queued) locally on the mobile device running the Mobile Payments SDK application and processed by Square the next time the device successfully connects to the Internet and Square servers.
## Requirements and limitations
{% aside type="warning" %}
Before upgrading to a new version of the Mobile Payments SDK or a new version of your application, you should ensure all offline payments have been uploaded by verifying that the offline payment queue is empty.
{% /aside %}
* Offline payments aren't supported in the Square Sandbox.
* Interac debit cards don't work in Offline mode. Any offline transaction attempted with an Interac debit card results in a payment failure.
* Offline Payments support is limited to the two most recent versions of Square Reader for contactless and chip, Square Reader for magstripe, and Square Stand second generation. To learn whether your reader device is supported, see [Hardware devices and capabilities](mobile-payments-sdk#hardware-devices-and-capabilities).
* If you're using the Mobile Payments SDK with a [Square Reader for contactless and chip](https://squareup.com/us/en/hardware/contactless-chip-reader), both a bluetooth connection and a secure connection are required to take offline payments.
* Bluetooth connection relies on device settings and physical distance. A reader must maintain a Bluetooth connection with a mobile device's POS application to take payments.
* A secure connection is established when a reader is connected to a mobile device that has its POS application open and online.
To take offline payments with the Mobile Payments SDK and a bluetooth Square reader:
* The reader must be connected to a device that was online and had its POS application opened within the last 24 hours.
* The POS device must have a bluetooth connection to the reader and have offline processing enabled before going offline.
* The reader must maintain a bluetooth connection to your device throughout the offline payment.
{% aside type="important" %}
Sellers must contact Square and [opt-in to accept offline payments with the Mobile Payments SDK](#seller-onboarding). The seller is responsible for any expired, declined, or disputed payments accepted while offline. By providing their merchant ID and using Offline Payments, the seller is aware of and accepting this risk.
{% /aside %}
Before upgrading to a new version of the Mobile Payments SDK or a new version of your application, you should upload all offline payments and verify that the offline payment queue is empty.
## Seller onboarding
At this time, the Offline Payments feature for the Mobile Payments SDK is in Beta, and requires Square sellers to opt in to this feature. If a seller using your application is interested in taking payments offline with the Mobile Payments SDK, send an email to developerbetas@squareup.com. In your message, include:
* The seller's business name.
* The seller's email address (this should be the owner or administrator for the seller's Square account).
* Your application ID.
Square contacts the seller directly and provides them with a seller onboarding form for this Beta feature. After the seller is successfully onboarded, Square sends you (the developer) a confirmation email letting you know that you can accept offline payments for the seller.
At any time, you can check the `isOfflineProcessingAllowed` value within the `PaymentSettings` to determine whether the seller that is authorized with your application can take payments offline. If your application tries to take an offline payment for a seller who doesn't have access to this feature, you receive a [`USAGE_ERROR`](mobile-payments-sdk/android/handling-errors).
## Transaction limits
Each seller taking payments offline with the Mobile Payments SDK has a limit on each offline payment and a limit to the total amount they can store offline on their mobile device. These limits vary by seller. If your application attempts to take an offline payment that exceeds one of these limits, the Mobile Payments SDK returns a `USAGE_ERROR`.
Each device running the Mobile Payments SDK can take up to 1000 payments for up to 24 hours before reconnecting to the network. If this limit is reached, the reader fails to connect and your mobile device must connect to a network to process and upload these payments before accepting more.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val paymentSettings = MobilePaymentsSdk.settingsManager().getPaymentSettings()
val isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed
val offlineTransactionAmountLimit =
paymentSettings.offlineTransactionAmountLimit
val offlineTotalStoredAmountLimit =
paymentSettings.offlineTotalStoredAmountLimit
```
{% /tab %}
{% tab id="Java" %}
```java
PaymentSettings paymentSettings = MobilePaymentsSdk.settingsManager().getPaymentSettings();
boolean isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed();
Money offlineTransactionAmountLimit = paymentSettings.getOfflineTransactionAmountLimit();
Money offlineTotalStoredAmountLimit = paymentSettings.getOfflineTotalStoredAmountLimit();
```
{% /tab %}
{% /tabset %}
### Payment methods
The payment methods available to customers are limited while offline and not all devices support every type of offline payment. Before taking any payment, your application should query the Payment Manager's `getAvailableCardEntryMethods()` and display the possible payment methods to customers.
If you're using the `DEFAULT` [payment prompt](mobile-payments-sdk/android/take-payments#create-prompt-parameters), the SDK automatically displays the card entry methods available while offline.
## Take a payment offline
When you're ready to [take a payment](mobile-payments-sdk/android/take-payments) with the Mobile Payments SDK, you create `PaymentParameters` with details about the payment. The `processingMode` field is required, and determines whether the payment should be taken offline. You can choose from `ONLINE_ONLY`, `OFFLINE_ONLY`, or `AUTO_DETECT`.
It's recommended to set the `processingMode` to `AUTO_DETECT` to improve your application reliability. In this mode, the SDK checks the status of the local network connection and the performance of Square's servers to route the payment online or offline for the highest chance of success. For example, with the `processingMode` set to `AUTO_DETECT`, a seller who has not opted into offline processing always has their payment attempted online, since offline payments would fail when checking opt-in status. If you're using the `AUTO_DETECT` processing mode, the Payment object returned by `startPaymentActivity()` might be an `OnlinePayment` or `OfflinePayment`, and your application should account for both possibilities.
In some situations, such as when a location has a sporadic or weak internet connection, sellers might want to take all payments offline during a period of time. To do so, set the `processingMode` for payments to `OFFLINE_ONLY`. All payments made with this mode are initially queued on the mobile device, even if there is a network connection.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val paymentManager = MobilePaymentsSdk.paymentManager()
val baseMoney = Money(100L, USD)
val builder = PaymentParameters.Builder(
amount = baseMoney,
paymentAttemptId = UUID.randomUUID().toString(),
processingMode = processingMode(ProcessingMode.AUTO_DETECT)
)
val paymentParameters = builder.build()
val promptParameters = PromptParameters(
mode = PromptMode.DEFAULT,
additionalPaymentMethods = listOf(Type.KEYED)
)
viewModel.startPaymentActivity(paymentParameters, promptParameters)
```
{% /tab %}
{% tab id="Java" %}
```java
PaymentManager paymentManager = MobilePaymentsSdk.paymentManager();
Money baseMoney = new Money(100L, CurrencyCode.USD);
PaymentParameters.Builder builder = PaymentParameters.Builder(
baseMoney,
UUID.randomUUID().toString(),
ProcessingMode.AUTO_DETECT
)
PaymentParameters paymentParameters = builder.build();
PromptParameters promptParameters = new PromptParameters(
PromptMode.DEFAULT,
Collections.singletonList(AdditionalPaymentMethod.Type.KEYED)
);
paymentManager.startPaymentActivity(paymentParameters, promptParameters);
```
{% /tab %}
{% /tabset %}
{% aside type="important" %}
When an offline payment is queued, it hasn't yet been processed by Square. The transaction isn't returned from the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint and doesn't have a Square payment ID value. If your application's workflow involves delayed payment capture or syncing Square payments with an outside transaction database, you must write logic to query Square for the completed payment and its details and then perform that sync. For more information, see [Payment IDs](#payment-ids).
{% /aside %}
## Access offline payments
The Mobile Payments SDK provides the `getOfflinePaymentQueue()` method in the Payment Manager to access all payments taken offline by the application on the current mobile device. This includes queued payments waiting to be processed and completed processed payments. Only payments that have a `locationId` matching the current application user's location ID are returned. This prevents two Square sellers logging in to your application on the same mobile device from viewing each other's payments.
The `status` of an `OfflinePayment` indicates its current point in the payment workflow and whether it failed to upload or process. The `status` can be one of the following:
* `QUEUED` - The payment is stored locally on the device running the Mobile Payments SDK application. The SDK attempts to upload the payment to Square after the network connection is restored.
* `UPLOADED` - The payment has been uploaded to the Square server, but hasn't yet been processed.
* `FAILED_TO_UPLOAD` - The payment couldn't be uploaded due to an unrecoverable error.
* `FAILED_TO_PROCESS` - The connection was restored, but Square couldn't process this specific offline payment. This might be because of a declined card or another error with the card-issuing bank. An offline payment with this status cannot be recovered, and the seller doesn't receive funds from the transaction.
* `PROCESSED` - Square processed your offline payment successfully. It can now be seen in the Square Dashboard.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val offlineQueue = MobilePaymentsSdk.paymentManager().getOfflinePaymentQueue()
// Grab total amount stored
when (val totalStoredAmountResult = offlineQueue.getTotalStoredPaymentAmount()) {
is Failure -> { … }
is Success -> {
val totalStoredAmount = totalStoredAmountResult.value
}
}
// Add callback
val callbackReference = offlineQueue.addGetPaymentsCallback { result ->
when (result) {
is Failure -> { … }
is Success -> {
val offlinePayments = result.value
// Number of payments currently stored
val totalNumberOfPayments = offlinePayments.size
// Show each OfflinePayment Status to user
offlinePayments.forEach { offlinePayment ->
when (offlinePayment.status) {
OfflineStatus.QUEUED -> {
//show user via UI
}
OfflineStatus.UPLOADED -> {
//show user via UI
}
OfflineStatus.FAILED_TO_PROCESS -> {
//show user via UI
}
OfflineStatus.FAILED_TO_UPLOAD -> {
//show user via UI
}
OfflineStatus.PROCESSED -> {
//show user via UI
}
}
}
}
}
}
// Start async getPayments()
offlineQueue.getPayments()
// clean up when done fetching
callbackReference.clear()
```
{% /tab %}
{% tab id="Java" %}
```java
OfflinePaymentQueue offlineQueue =
MobilePaymentsSdk.paymentManager().getOfflinePaymentQueue();
// Grab total amount stored
Result totalStoredAmountResult =
offlineQueue.getTotalStoredPaymentAmount();
if (totalStoredAmountResult.isSuccess()) {
Money totalStoredAmount = totalStoredAmountResult.value();
} else if (totalStoredAmountResult.isFailure()) {
…
}
// Add callback
CallbackReference callbackReference = offlineQueue.addGetPaymentsCallback(result -> {
if (result.isFailure()) {
…
} else if (result.isSuccess()) {
List offlinePayments = result.value();
// Number of payments currently stored
int totalNumberOfPayments = offlinePayments.size();
// Show each OfflinePayment Status to user
for (OfflinePayment offlinePayment : offlinePayments) {
switch (offlinePayment.getStatus()) {
case QUEUED:
//show user via UI
break;
case UPLOADED:
//show user via UI
break;
case FAILED_TO_PROCESS:
//show user via UI
break;
case FAILED_TO_UPLOAD:
//show user via UI
break;
case PROCESSED:
//show user via UI
break;
}
}
}
});
// Start async getPayments()
offlineQueue.getPayments();
// clean up when done fetching
callbackReference.clear();
```
{% /tab %}
{% /tabset %}
### Payment IDs
A payment taken offline with the Mobile Payments SDK has two identification values: `localID`, used to identify the payment on your mobile device before it's processed, and `id`, which represents the Square payment `id` value. The second value is always `null` until the SDK uploads the payment to Square and the payment is processed.
When a payment's status changes to `PROCESSED`, you can access its `id` value from the mobile device and match it to the `id` value of payments returned by the [ListPayments](https://developer.squareup.com/reference/square/payments-api/list-payments) endpoint. You can now continue your application's payment workflow and use other Square APIs to access and manage the payment. `PROCESSED` payments are deleted from the mobile device to conserve storage space.
{% tabset %}
{% tab id="Kotlin" %}
```kotlin
val paymentManager = MobilePaymentsSdk.paymentManager()
val handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
when (result) {
is Failure -> { … }
is Success -> {
val payment = result.value
when (payment) {
is OnlinePayment -> {
val paymentId = paymentId.id // not nullable
}
is OfflinePayment -> {
val paymentId = payment.id // nullable
val localPaymentId = payment.localId
val status = payment.status
}
}
}
}
}
// clean up when done fetching
handle.cancel()
```
{% /tab %}
{% tab id="Java" %}
```java
PaymentManager paymentManager = MobilePaymentsSdk.paymentManager();
PaymentHandle handle = paymentManager.startPaymentActivity(paymentParams, promptParams, result -> {
if (result.isFailure()) {
…
} else if (result.isSuccess()) {
Payment payment = result.value();
if (payment.isOnlinePayment()) {
String paymentId = payment.asOnlinePayment().getId(); // not nullable
} else if (payment.isOfflinePayment()) {
String paymentId = payment.asOfflinePayment().getId(); // nullable
String localPaymentId = payment.asOfflinePayment().getLocalId();
OfflineStatus status = payment.asOfflinePayment().getStatus();
}
}
});
// clean up when done fetching
handle.cancel();
```
{% /tab %}
{% /tabset %}
## Process offline payments
The Mobile Payments SDK regularly checks for network connectivity and a connection to Square servers so that queued payments can be processed. This is done automatically while the application is open in the foreground of the device. Assuming that there are no errors in the `PaymentParameters` or issues like cards being declined, the funds are available to the seller in the Square Dashboard and the payment can be accessed and managed by the [Payments API](https://developer.squareup.com/reference/square/payments-api) after this processing is complete.
{% aside type="important" %}
The following actions result in queued payments being removed from the device. If this happens before the payment is uploaded and processed, it cannot be processed and the seller doesn't receive funds from the transaction:
* Wiping the device cache
* Authenticating the Mobile Payments SDK with a different application ID on the same device
* Uninstalling the application from the device using the Mobile Payments SDK
{% /aside %}
Queued payments remain on the device when a user force-quits your application, switches to another application, or a seller logs out of your application. As a best practice, your application should query for any `QUEUED` payments on the device before calling `authorizationManager.deauthorize()`, so that you can alert the seller about any unprocessed payments.
---
# Handling Errors
> Source: https://developer.squareup.com/docs/mobile-payments-sdk/android/handling-errors
> Status: PUBLIC
> Languages: All
> Platforms: Android
Learn how to handling errors in the Mobile Payments SDK for Android.
**Applies to:** [Mobile Payments SDK - Android](https://developer.squareup.com/docs/sdk/mobile-payments/android)
{% subheading %}Learn how to resolve errors in the Mobile Payments SDK for Android.{% /subheading %}
{% toc hide=true /%}
## Authorization errors
`AuthorizeErrorCodes` might be returned when using the `AuthorizationManager`. These errors are surfaced as a result of your authorization callback.
{% table %}
* Error {% width="200px" %}
* Description
---
* `NO_NETWORK`
* The Mobile Payments SDK couldn't connect to the network.
---
* `OBSOLETE_SDK`
* The SDK version is obsolete and no longer supported. Update to a newer version of the Mobile Payments SDK.
---
* `USAGE_ERROR`
* `AuthorizationManager.authorize` was used in an unexpected or unsupported way. For more information, see the `debugCode` and `debugMessage` within `Result.Failure`.
{% /table %}
## Bluetooth and pairing errors
`PairingErrorCodes` might be returned when pairing readers using the `ReaderManager`. These errors are surfaced as a result of your pairing callback.
{% table %}
* Error {% width="300px" %}
* Description
---
* `BLUETOOTH_ALREADY_SCANNING`
* Bluetooth scanning is already in progress. Only one scan can be active at a time. Wait for the first scan to complete and try again.
---
* `BLUETOOTH_DISABLED`
* Bluetooth was disabled by the user. Prompt the user to enable Bluetooth and try again.
---
* `BLUETOOTH_PERMISSION_DENIED`
* Your application is missing one or both Android runtime permissions for Bluetooth: `BLUETOOTH_CONNECT` or `BLUETOOTH_SCAN`. Check for these permissions and try again.
---
* `BLUETOOTH_UNSUPPORTED`
* This device doesn't support Bluetooth.
---
* `NOT_AUTHORIZED`
* The Mobile Payments SDK isn't currently authorized with a Square seller account. Use the `AuthorizationManager` to authorize a Square account.
---
* `TIMEOUT`
* The Mobile Payments SDK timed out while awaiting reader pairing. Try pairing again.
---
* `USAGE_ERROR`
* `ReaderManager.pairReader` was used in an unexpected or unsupported way. For more information, see the `debugCode` and `debugMessage`.
{% /table %}
## Payment errors
`PaymentErrorCodes` might be returned when taking a payment with the `PaymentManager`. These errors are surfaced as a result of your payment callback.
{% table %}
* Error {% width="300px" %}
* Description
---
* `CANCELED`
* The payment was canceled before completion.
---
* `CONSENT_NOT_PROVIDED`
* The merchant is in a market that requires consent for [analytics and performance tracking](mobile-payments-sdk/android#data-privacy-consent), and consent has not been explicitly granted or denied.
---
* `DEVICE_CLOCK_SKEWED`
* The local device time is out of sync with the server time, which could lead to inaccurate payment reporting. Check your device's time and attempt your action again.
---
* `LOCATION_SERVICES_DISABLED`
* The device's location services were disabled and the payment couldn't be completed. Enable location services and try again.
---
* `NOT_AUTHORIZED`
* The Mobile Payments SDK isn't currently authorized with a Square seller account. Use the `AuthorizationManager` to authorize a Square account.
---
* `OBSOLETE_SDK`
* The SDK version is obsolete and no longer supported. Update to a newer version of the Mobile Payments SDK.
---
* `TIMEOUT`
* The Mobile Payments SDK timed out while awaiting a payment. Try the payment again.
---
* `USAGE_ERROR`
* `PaymentManager.startPaymentActivity` was used in an unexpected or unsupported way. For more information, see the `debugCode` and `debugMessage` within `Result.Failure`.
{% /table %}
---
# Events API
> Source: https://developer.squareup.com/docs/events-api/overview
> Status: BETA
> Languages: All
> Platforms: All
Learn how the Events API can be used to search for and retrieve Square API events.
**Applies to:** [Events API](https://developer.squareup.com/reference/square/events-api) | [OAuth API](oauth-api/overview) | [Square Webhooks](webhooks/overview) | [Webhook Subscriptions API](webhooks/webhook-subscriptions-api)
{% subheading %}Learn how the Events API can be used to search for and retrieve Square API events.{% /subheading %}
{% toc hide=true /%}
## Overview
The [Events API](https://developer.squareup.com/reference/square/events-api) lets you search for and retrieve Square API events occurring within a 28-day period. You can use the API to manage event data when real-time responses to data changes aren't necessary.
The Events API serves as a disaster recovery and reconciliation mechanism for missed webhook events due to server outages, misconfigured webhook subscriptions, network errors, and similar issues. By allowing access to and review of past events, the Events API helps you maintain data integrity and continuity during disruptions.
## Requirements and limitations
* You can only retrieve events that occurred within the past 28 days.
* You can search for all event types listed in [Events](https://developer.squareup.com/reference/square/webhooks), except for the deprecated [V1 PAYMENT_UPDATED](https://developer.squareup.com/reference/square/payments-api/webhooks/v1-PAYMENT_UPDATED) event type.
## Security considerations
Because Square events are owned by the application and not by any one seller, you cannot use OAuth access tokens with the Events API. You can only access the Events API using your [personal access token](build-basics/access-tokens#get-a-personal-access-token).
The Events API uses OAuth on the backend to authenticate whether your application is authorized to receive specific events. Your application must have OAuth access to an event at the time it occurs to see it in the search results. For example, with OAuth access to payment permissions of a seller's account, you can use the Events API to search for the `payment.created` event for that seller using your personal access token.
For more information about OAuth processes, see [OAuth Best Practices](oauth-api/best-practices).
## Comparison with webhooks
The Events API is a pull-based alternative to [webhooks](webhooks/overview). In addition to receiving real-time event notifications, you can periodically poll the Events API to retrieve events. The API gives you access to the event data directly, removing the need to rely on a notification URL.
While the Events API allows you to manage event data in scenarios where real-time notifications aren't needed, it doesn't replace webhooks entirely. Instead, it complements the [Webhook Subscriptions API](webhooks/webhook-subscriptions-api) by providing a pull-based method to reconcile real-time events with historical ones (in order).
## Use cases
Use case examples for the Events API include the following:
- **Direct access to event data** - Retrieve event data directly without needing a notification URL.
- **Disaster recovery** - If you miss events due to server downtime or network issues, you can use the Events API to recover them.
- **Data reconciliation** - Regularly poll the Events API to ensure that your system's event data stays current and consistent with Square's records.
- **Audit and reporting** - Access historical event data for audit trails, reporting, and analytics purposes without relying on real-time event notifications.
## Implementation steps
Using the Events API involves the following steps:
1. **Authenticate your requests** - Obtain and use your personal access token to authenticate the Events API.
1. **Define polling intervals** - Determine and set intervals for polling the Events API to retrieve new events.
1. **Handle retrieved events** - Develop logic to process retrieved events based on the event's `created_at` timestamp.
## Endpoints
The Events API includes one primary endpoint, `SearchEvents`, along with three supporting endpoints: `EnableEvents`, `DisableEvents`, and `ListEventTypes`.
| Endpoint{% width="180px" %} | Action |
|--------|-------------------------------|
|[SearchEvents](https://developer.squareup.com/reference/square/events-api/search-events) | To search for Square API events that occurred within a 28-day period. {% line-break /%}{% line-break /%} You can filter events based on event types, seller IDs, location IDs, and `created_at` parameters. For a complete list of filters that you can use, see [SearchEventsFilter](https://developer.squareup.com/reference/square/objects/SearchEventsFilter). By default, Square sorts events by their creation time using the `created_at` timestamp. For a list of sort criteria that you can use, see [SearchEventsSort](https://developer.squareup.com/reference/square/objects/SearchEventsSort).
|[EnableEvents](https://developer.squareup.com/reference/square/events-api/enable-events) | To enable events to make them searchable. {% line-break /%}{% line-break /%} Before you can search for events, you must first enable them using the `EnableEvents` endpoint. You cannot enable individual event types. The `EnableEvents` endpoint doesn’t have a request or response body.
|[DisableEvents](https://developer.squareup.com/reference/square/events-api/disable-events) | To disable events to prevent them from being searchable. {% line-break /%}{% line-break /%} All events are disabled by default. You must enable events to make them searchable. You cannot disable individual event types. Disabling events for a specific time period prevents them from being searchable, even if you re-enable them later. The `DisableEvents` endpoint doesn’t have a request or response body.
|[ListEventTypes](https://developer.squareup.com/reference/square/events-api/list-event-types) | To list event types that you can search for.
## Example use case
The [SearchEvents](https://developer.squareup.com/reference/square/events-api/search-events) request searches for events with the type `labor.shift.created` and limits the number of results to three. To retrieve events beyond these three, send your original query along with the [pagination cursor](build-basics/common-api-patterns/pagination) provided in the response as shown in the following example.
{% tabset %}
{% tab id="Request" %}
````
If you don’t specify an `event_type` filter, the response includes all events. For a complete list of event types that you can filter by, see [Webhook Events](https://developer.squareup.com/reference/square/webhooks).
You can filter events by seller ID. For example, you can retrieve all events for a single seller or a group of sellers. You can also filter events by their creation time using the `created_at` timestamp or the `location_id`. Note that the `created_at` timestamp is inclusive. For a complete list of filters that you can use, see [SearchEventsFilter](https://developer.squareup.com/reference/square/objects/SearchEventsFilter).
{% /tab %}
{% tab id="Response" %}
```json
{
"events": [
{
"merchant_id": "1ZYMKZY1YFGBW",
"type": "labor.shift.created",
"event_id": "d2798d4e-8479-331a-b0cd-4f06cec84551",
"created_at": "2022-12-22 19:46:43.431652523 +0000 UTC",
"data": {
"type": "labor",
"id": "E5WVVC4X3NTKP",
"object": {
"shift": { ... }
}
}
},
{
"merchant_id": "1ZYMKZY1YFGBW",
"type": "labor.shift.created",
"event_id": "5ce40dc9-70f4-39bb-8641-be5d95510df8",
"created_at": "2022-12-22 23:25:09.909082772 +0000 UTC",
"data": { ... }
}
],
"metadata": [
{
"event_id": "d2798d4e-8479-331a-b0cd-4f06cec84551",
"api_version": "2022-07-20"
},
{
"event_id": "5ce40dc9-70f4-39bb-8641-be5d95510df8",
"api_version": "2022-07-20"
}
],
"cursor": "c3EwaWRzLTZNM0FydWY3T20yaVBKbEFfR2VFQmcjMTY3MTc1MTUwOSM1Y2U0MGRjOS03MGY0LTM5YmItODY0MS1iZTVkOTU1MTBkZjg="
}
```
The payload sent by a webhook is identical to the `Event` object returned in this response. This response also includes an [EventMetadata](https://developer.squareup.com/reference/square/objects/EventMetadata) object that corresponds to the API version of each event.
{% aside type="success" %}
Sometimes, responses might only include a pagination cursor. In such cases, continue paginating to retrieve additional events.
{% /aside %}
{% /tab %}
{% /tabset %}
### List event types
The following example shows using the `ListEventTypes` endpoint to list the event types that you can search for:
{% tabset %}
{% tab id="Request" %}
````
{% /tab %}
{% tab id="Response" %}
```json
{
"event_types": [
"bank_account.created",
"card.updated",
"invoice.updated",
"payment_method_enrollment.updated",
"terminal.refund.updated",
...
],
"metadata": [
{
"event_type": "bank_account.created",
"api_version_introduced": "2020-02-26",
"release_status": "PUBLIC"
},
{
"event_type": "card.updated",
"api_version_introduced": "2021-06-16",
"release_status": "PUBLIC"
},
{
"event_type": "invoice.updated",
"api_version_introduced": "2020-07-22",
"release_status": "PUBLIC"
},
{
"event_type": "terminal.refund.updated",
"api_version_introduced": "2020-10-28",
"release_status": "PUBLIC"
},
...
]
}
```
{% /tab %}
{% /tabset %}
## See also
* [Webhook Subscriptions](webhooks/webhook-subscriptions-api)
* [Square Webhooks](webhooks/overview)
---
# Square eCommerce APIs
> Source: https://developer.squareup.com/docs/ecommerce-api
> Status: PUBLIC
> Languages: All
> Platforms: All
eCommerce APIs are building blocks for online marketplaces, allowing developers to create seamless shopping experiences.
{% subheading %}Learn how Square APIs can be used to create custom eCommerce solutions.{% /subheading %}
## Overview
Square eCommerce APIs in the [Square Developer platform](homepage) are building blocks for online marketplaces. By connecting various features and services, developers can create seamless shopping experiences for any business type.
Square APIs for eCommerce solutions offer:
* Scalability for businesses to easily expand their online presence and offerings.
* Flexible online experiences that meet specific needs of different businesses.
* Comprehensive functionality through the integration of various Square products and services.
### Square Online store
Sellers use the [Square Online](https://squareup.com/online-store) eCommerce platform to build and launch an online store. Square Online integrates with [Square Point of Sale](https://squareup.com/point-of-sale), enabling sellers to keep online and in-person orders, items, and inventory in sync — all in one place. Square Online checkouts use [Payment Links](https://squareup.com/payment-links) for PCI-DSS compliant payment processing and provide free fraud protection and payment dispute management.
Square partner integrations are also available to help sellers with shipping and other eCommerce needs. [Learn more](https://squareup.com/help/article/5437-manage-your-square-app-marketplace-subscriptions) or [see all eCommerce apps](https://squareup.com/app-marketplace/category/e-commerce) available in the App Marketplace.
## Common eCommerce API integrations
Developers can integrate Square features into their eCommerce solutions by calling RESTful Square APIs directly, using [language-based platform SDKs](sdks), or sending [Square GraphQL queries](devtools/graphql). Square also provides online and mobile payment SDKs. Many Square APIs have built-in integrations with other APIs that you can leverage in your custom solutions.
### Payment processing
All eCommerce solutions need some way to accept online payments. Square provides options that support low code to advanced customizations and support one-time or [recurring payments](#recurring-payments) securely processed by Square.
Online payment APIs and SDKs options include:
* [Checkout API](checkout-api) - Generate shareable payment links, with optional [Orders API](orders-api/what-it-does) integration and support for [recurring payments](#recurring-payments).
* [Payments API](payments-refunds) - Used with the [Web Payments SDK](web-payments/overview) and [In-App Payments SDK](in-app-payments-sdk/what-it-does) for card payments or the [Customers API](customers-api/what-it-does), [Cards API](cards-api/overview), and [Gift Cards API](gift-cards/using-gift-cards-api) for card-on-file payments.
Both the Payments API and [Refunds API](refunds-api/overview) have built-in Orders API integration for order management.
{% anchor id="order-management" /%}
### Order management
Order management features help streamline and automate efficient end-to-end order processing. Key features include building orders for the cart, [inventory control](#inventory-control), and helping coordinate workflows for picking, packing, and shipping order fulfillments.
The [Orders API](orders-api/what-it-does) is the primary API for managing the order lifecycle. Combine the Orders API with other APIs to build custom order management functionality:
* [Catalog API](catalog-api/what-it-does) - Include detailed itemization and automatic taxes and discounts, with built-in [Inventory API](inventory-api/what-it-does) integration that automatically updates inventory levels for catalog item variations.
* [Payments API](payments-refunds) and [Refunds API](refunds-api/overview) - Automatically update order details, including payment and refund history with detailed transaction information.
* [Customers API](customers-api/what-it-does) and other [customer engagement](#customer-engagement) features - Facilitate customer service requests, inform customer analytics, and implement loyalty and gifting programs.
{% anchor id="inventory-control" /%}
### Inventory control
Use the Inventory API to manage and track product inventory levels in real-time, helping to prevent stockouts and overstocking.
The [Inventory API](inventory-api/what-it-does) is the primary API for inventory control, including updating and tracking inventory changes and retrieving inventory counts. The Inventory API is used with the following APIs:
* [Catalog API](catalog-api/what-it-does) - Manage the product catalog. Inventory quantities are tracked on item variations in the catalog.
* [Orders API](orders-api/what-it-does) - Automatically update inventory levels for item variations sold or returned in an order.
* [Locations API](locations-api) - Find stock availability for in-person pickups.
### Customer engagement
Engaged customers are more likely to make purchases and often spend more. Regular engagement can build strong customer relationships that improve customer retention and increase referrals.
The [Customers API](customers-api/what-it-does) is the primary API for customer relationship management (CRM). Combine the Customers API with other APIs for custom engagement strategies:
* [Loyalty API](loyalty-api/overview) and [Gift Cards API](gift-cards/using-gift-cards-api) - Help drive new and repeat business through loyalty and gifting programs.
* [Orders API](orders-api/what-it-does) and [Customer Segments API](customer-segments-api/what-it-does) - Analyze buying behavior (for segmentation, satisfaction, product affinity, and other insights). Integration with the Orders API also simplifies loyalty and gift card workflows. In addition, the [Payments API](payments-refunds) provides built-in integration by associating a customer with most payments.
* [Customer Groups API](customer-groups-api/what-it-does) and [Customer Custom Attributes API](customer-custom-attributes-api/overview) - Enable personalized customer experiences.
{% anchor id="recurring-payments" /%}
### Recurring payments with subscriptions
Subscriptions offer a convenient recurring delivery of products or services to customers as well as a consistent and predictable revenue stream for businesses with automated payments.
The [Subscriptions API](subscriptions/overview) is the primary API for managing subscriptions. It's used with the following APIs:
* [Catalog API](catalog-api/what-it-does) - Configure the subscription plan and plan variation.
* [Orders API](orders-api/what-it-does) - Create optional order templates for recurring orders for catalog items.
* [Customers API](customers-api/what-it-does) - Allow customers to enroll in subscriptions.
## Square APIs for eCommerce
Square APIs can be used for eCommerce, brick and mortar businesses, or both. Understanding the purpose and functionality of API capabilities can help you create a comprehensive eCommerce solution using multiple APIs.
{% tabset %}
{% tab id="Payment APIs & SDKs" imageWidth=371 imageHeight=190
imageUrl="//images.ctfassets.net/1nw4q0oohfju/3hQ2IGovhpwlmD9ihPELzF/7513e6a0dca8cccd257367053b7225c1/payments-highlight.png" %}
{% card %}
Process online payments securely —
from instant payment links to recurring billing for subscription-based products and services — with support for various payment methods, acceptance flows, and levels of coding and customization.
{% card-link-out href="online-payment-options" %}Online Payment APIs and SDKs{% /card-link-out %}
{% /card %}
{% /tab %}
{% tab id="Commerce APIs" imageWidth=371 imageHeight=190
imageUrl="//images.ctfassets.net/1nw4q0oohfju/5406bYhhpgR7pr37TxLQNP/d39345101c2490006f892626c6452a09/commerce-highlight.png" %}
{% card %}
Manage the order lifecycle from creation to fulfillment, build and manage a catalog of products and services, update inventory pricing and availability. Let customers book appointments online and add snippets to Square Online sites.
{% card-link-out href="commerce" %}Commerce APIs{% /card-link-out %}
{% /card %}
{% /tab %}
{% tab id="Customer APIs" imageWidth=371 imageHeight=190
imageUrl="//images.ctfassets.net/1nw4q0oohfju/6KYlHBFtTwRpRZI1OOpzSX/c339e28c5ead5052c0aaf2241f3c32f8/customers-highlight.png" %}
{% card %}
Manage customer records as a foundation for customer relationship management and for engagement strategies that can encourage new and repeat business or enable personalization.
{% card-link-out href="customers" %}Customer APIs{% /card-link-out %}
{% /card %}
{% /tab %}
{% tab id="Merchant APIs" imageWidth=371 imageHeight=190
imageUrl="//images.ctfassets.net/1nw4q0oohfju/6neLhXOD5wCHp7EM3ZbY47/62241155a90dc38a55dc3eab2a6f6ca3/merchants-highlight.png" %}
{% card %}
Get details about Square sellers and their locations. Location details can enable eCommerce features such as stock availability and in-person pickups.
{% card-link-out href="merchant-details" %}Merchant APIs{% /card-link-out %}
{% /card %}
{% /tab %}
{% /tabset %}
## Security considerations
Security is a critical concern for eCommerce API integrations. While many security features are built into Square APIs, developers must ensure that their calls to API endpoints are secure and data is encrypted both in transit and at rest. To prevent common security threats, developers should:
* Use HTTPS to prevent man-in-the-middle attacks.
* Apply strict input validation to protect against SQL injection and XSS.
* Keep access tokens, application credentials, and sensitive data secure and out of the codebase and use environment variables or secrets management tools.
For more information, see:
* [OAuth Best Practices](oauth-api/best-practices)
* [Best Practices for Collecting Information](build-basics/general-considerations/collecting-information)
* [Strong Customer Authentication](sca-overview)
## Performance optimization
To ensure fast and reliable API performance:
* Implement caching strategies to reduce the load on API servers.
* When possible, use batch and bulk requests to minimize the number of API calls.
* Optimize API calls by requesting only the data needed and reducing payload size. Consider integrating [Square GraphQL queries](devtools/graphql) to minimize data transfer requests.
* Subscribe for [webhook notifications](webhooks/overview) to reduce the need for polling.
## Error handling and debugging
Effective error handling and debugging are crucial for maintaining a functional eCommerce API integration. Developers should:
* Implement comprehensive error logging to track and resolve issues promptly.
* Monitor responses for `429` [rate limiting errors](build-basics/general-considerations/handling-errors#rate-limiting-errors) and use a retry mechanism with an exponential backoff schedule to resend the requests at an increasingly slower rate. It's also a good practice to use a randomized delay (jitter) in your retry schedule.
* Use debugging tools and monitor API response codes to identify and fix errors. For example, use [API logs](devtools/api-logs) to view the logs of the API calls from your application.
## API testing
API testing ensures that integrations work as expected and can handle various scenarios. Developers should conduct:
* Unit tests to validate individual API functions.
* Integration tests to ensure APIs work together seamlessly.
* End-to-end tests to simulate real-world scenarios with different product catalogs and [scoped OAuth permissions](oauth-api/square-permissions).
---
# Web Payments SDK Quickstart
> Source: https://developer.squareup.com/docs/web-payments/quickstart
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to get started with the Web Payments SDK for your application to take secure payments and deploy to production.
**Applies to:** [Web Payments SDK](https://developer.squareup.com/reference/sdks/web/payments) | [Payments API](payments-refunds)
{% subheading %}Learn how to get started with the Web Payments SDK for your application to take secure payments and deploy to production.{% /subheading %}
{% toc hide=true /%}
## Overview
To accept a card payment from a buyer, you need a web client where the buyer enters payment card information and a backend that takes a payment with the card. The SDK produces a secure single-use payment token based on the card. Your web client sends the payment token to your backend where the payment is taken. In summary, a payment is taken with these steps:
1. **Generate a payment token** - Use the Web Payments SDK client library to render a card entry form and generate a payment token that your web client sends to your backend server.
2. **Create a payment with the token** - On your backend, use the Square [Payments API](payments-refunds) to create a payment.
This quickstart guide shows you where to add HTML and JavaScript to your web client to integrate the Web Payments SDK and take a payment on your backend.
You can follow along with the [quickstart sample repository](https://github.com/square/web-payments-quickstart) to set up a web application that's integrated with the Web Payments SDK for taking payments.
{% aside type="important" %}
If you're not familiar with building an application using Square client-side SDKs, Square recommends completing this quickstart using the GitHub project before you attempt to integrate the Web Payments SDK into your application.
{% /aside %}
## Quickstart steps
Use the following steps to take card payments in a web client with the Web Payments SDK:
1. [Set Up the Web Client Application](web-payments/quickstart/set-up-web-client-app) - Learn how to set up a web client application with the Web Payments SDK quickstart sample project.
2. [Add the Web Payments SDK to the Web Client](web-payments/quickstart/add-sdk-to-web-client) - Learn how to initialize the Web Payments SDK with the web client and a Square application to accept a card payment, generate a payment token with buyer verification, and send the resulting payment token to the server for payment verification.
3. [Deploy the Application](web-payments/quickstart/deploy-app) - Learn how to deploy the application with the quickstart project by completing the required deployment tasks.
---
# Add the Web Payments SDK to the Web Client
> Source: https://developer.squareup.com/docs/web-payments/quickstart/add-sdk-to-web-client
> Status: PUBLIC
> Languages: All
> Platforms: All
Learn how to add the Web Payments SDK to the web client.
**Applies to:** [Web Payments SDK](web-payments/overview) | [Payments API](payments-refunds)
{% subheading %}Learn how to initialize the Web Payments SDK with the web client and a Square application to accept a card payment, generate a payment token with buyer verification, and send the resulting payment token to the server for payment verification.{% /subheading %}
{% toc hide=true /%}
## Overview
At the highest level, to add the Web Payments SDK to the web client, you need to:
- Get your application credentials, set up your localhost development environment, and initialize the SDK.
- Collect buyer input.
- Tokenize the buyer input in a call to [`card.tokenize()`](https://developer.squareup.com/reference/sdks/web/payments/objects/Card#Card.tokenize).
- Pass the token for future use in a server-side call to the [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) endpoint.
The following code demonstrates the basic order of operations:
```javascript
// Customer input, hard-coded for example only
const verificationDetails = {
amount: '1.00',
billingContact: {
givenName: 'John',
familyName: 'Doe',
email: 'john.doe@square.example',
phone: '3214563987',
addressLines: ['123 Main Street', 'Apartment 1'],
city: 'London',
state: 'LND',
countryCode: 'GB',
},
currencyCode: 'GBP',
intent: 'CHARGE',
customerInitiated: true,
sellerKeyedIn: false,
};
// Tokenize the input
const token = await card.tokenize(verificationDetails);
// Pass the token to create a Payment
const payment = CreatePayment(token);
```
The following sections explain these steps in more detail and include sample code that you can add to the [quickstart repository](https://github.com/square/web-payments-quickstart) to test a concept.
## 1. Get application credentials
The quickstart application is configured to send requests to the Square Sandbox instead of your production Square account. To find your Sandbox credentials:
1. Open the [Developer Console](https://developer.squareup.com/apps) and choose the plus symbol under **Applications** to create a new application.
2. Open the application, and then choose **Credentials** in the left pane.
3. At the top of the page, set the Developer Console mode to **Sandbox** to get to the **Sandbox Application ID** and **Sandbox Access Token** values.
5. In the left pane, choose **Locations** to find the **Sandbox Location ID**.
6. Paste all of these Sandbox credentials (**Application ID**, **Location ID**, and **Sandbox Access Token**) into a temporary text file.
{% aside type="important" %}
Your Sandbox credentials are secure secrets. Don't share these values with anyone or upload them to the cloud.
{% /aside %}
{% accordion expanded=false %}
{% slot "heading" %}
### ⚠️ Critical Production Requirement
{% /slot %}
You must use your seller's location ID and access token when deploying to production. Your testing credentials will not work for processing real payments.
To properly configure your production environment:
1. Replace your test access token with your seller's production token.
- Obtain this token through the OAuth flow by calling the [ObtainToken](oauth-api/receive-and-manage-tokens#call-the-obtaintoken-endpoint) endpoint.
2. Replace your test location ID with your seller's actual location ID.
- After obtaining the production token, [retrieve a list of the seller's locations](locations-api#retrieve-a-list-of-locations) to get the seller's valid location IDs.
- Select the appropriate location ID for this deployment.
❌ **Common Issue**: Application payments often fail in production because developers forget to replace their test location ID with the seller's actual location ID.
If payments are being rejected in production, verify that you're using the correct seller credentials, especially the location ID.
{% /accordion %}
## 2. Configure the quickstart access token
The quickstart server code calls the [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) endpoint and needs to be updated to use your Sandbox access token.
1. In the project root folder, create a copy of the `.env.example` file and name it `.env.sandbox`.
The [dotenv](https://www.npmjs.com/package/dotenv) library is used to manage secrets that shouldn't be made public. The `.env.sandbox` file should never be committed.
2. In .env.sandbox, define `SQUARE_ACCESS_TOKEN` with your Sandbox access token from the Developer Console.
```javascript
SQUARE_ACCESS_TOKEN={SANDBOX_ACCESS_TOKEN}
```
3. Restart your server for the Sandbox test environment (`npm run dev`) to use this new value.
## 3. Add pay elements to the page
1. Replace the contents of the `` in `public/index.html` with the following HTML elements:
```html
```
This HTML adds an element (`div id="card-container"`) that the Web Payments SDK attaches the card element to and adds a button that starts the tokenization process.
{% aside type="tip" %}
The SDK also enables the [Apple Pay](web-payments/apple-pay), [Google Pay](web-payments/google-pay), [ACH (bank transfer)](web-payments/add-ach), Square [gift card](web-payments/gift-card), and [Cash App Pay](web-payments/add-cash-app-pay) payment methods.
{% /aside %}
## 4. Attach the Card payment method to the pay elements
The quickstart code already includes the following `
```
1. Add an empty `
```
2. Add the following global constants inside the `