OpenAPI Specification
openapi: 3.0.3
info:
title: Square Catalog Payments API
description: Square API provides payment processing, commerce, customer management, and business operations capabilities for sellers, developers, and merchants. Supports point-of-sale, ecommerce, invoicing, loyalty, gift cards, and more.
version: 2026-01-22
contact:
name: Square Developer Support
url: https://developer.squareup.com/forums
termsOfService: https://squareup.com/us/en/legal/general/developer
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://connect.squareup.com/v2
description: Production
- url: https://connect.squareupsandbox.com/v2
description: Sandbox
security:
- BearerAuth: []
- OAuth2: []
tags:
- name: Payments
description: Process and manage payments
paths:
/payments:
get:
operationId: list-payments
summary: Block Square List Payments
description: Retrieves a list of payments taken by the account making the request.
tags:
- Payments
parameters:
- name: begin_time
in: query
schema:
type: string
format: date-time
description: The start of the time range to retrieve payments for.
- name: end_time
in: query
schema:
type: string
format: date-time
description: The end of the time range to retrieve payments for.
- name: cursor
in: query
schema:
type: string
description: A pagination cursor returned by a previous call.
- name: limit
in: query
schema:
type: integer
maximum: 100
description: The maximum number of results to be returned.
- name: location_id
in: query
schema:
type: string
description: Limit results to the location supplied.
responses:
'200':
description: List of payments retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListPaymentsResponse'
examples:
list-payments:
summary: List of payments
value:
payments:
- id: GQTFp1ZlXdpoW4o6eGiZhbjosiDFf
status: COMPLETED
source_type: CARD
amount_money:
amount: 1500
currency: USD
total_money:
amount: 1500
currency: USD
created_at: '2026-01-15T10:00:00Z'
updated_at: '2026-01-15T10:00:05Z'
location_id: L1234567890
x-microcks-default: true
x-microcks-operation:
delay: 50
dispatcher: FALLBACK
post:
operationId: create-payment
summary: Block Square Create Payment
description: Creates a payment using the provided source.
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
examples:
create-payment:
summary: Card payment request
value:
source_id: cnon:card-nonce-ok
idempotency_key: 7b0f3ec5-086a-4871-8f13-3c81b3875218
amount_money:
amount: 1500
currency: USD
location_id: L1234567890
x-microcks-default: true
responses:
'200':
description: Payment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponse'
examples:
created-payment:
summary: Created payment
value:
payment:
id: GQTFp1ZlXdpoW4o6eGiZhbjosiDFf
status: COMPLETED
source_type: CARD
amount_money:
amount: 1500
currency: USD
total_money:
amount: 1500
currency: USD
created_at: '2026-01-15T10:00:00Z'
updated_at: '2026-01-15T10:00:05Z'
location_id: L1234567890
x-microcks-default: true
x-microcks-operation:
delay: 100
dispatcher: SCRIPT
/payments/{payment_id}:
get:
operationId: get-payment
summary: Block Square Get Payment
description: Retrieves details for a specific payment.
tags:
- Payments
parameters:
- name: payment_id
in: path
required: true
schema:
type: string
description: A unique ID for the desired payment.
responses:
'200':
description: Payment retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentResponse'
examples:
get-payment:
summary: Payment details
value:
payment:
id: GQTFp1ZlXdpoW4o6eGiZhbjosiDFf
status: COMPLETED
source_type: CARD
amount_money:
amount: 1500
currency: USD
total_money:
amount: 1500
currency: USD
created_at: '2026-01-15T10:00:00Z'
updated_at: '2026-01-15T10:00:05Z'
location_id: L1234567890
x-microcks-default: true
x-microcks-operation:
delay: 50
dispatcher: URI_PARTS
dispatcherRules: payment_id
components:
schemas:
Payment:
type: object
description: Represents a payment processed by Square.
properties:
id:
type: string
description: Unique ID for this payment.
example: GQTFp1ZlXdpoW4o6eGiZhbjosiDFf
status:
type: string
description: Indicates whether the payment is APPROVED, COMPLETED, CANCELED, or FAILED.
example: COMPLETED
source_type:
type: string
description: The source type for this payment (e.g., CARD, CASH, BANK_ACCOUNT).
example: CARD
amount_money:
$ref: '#/components/schemas/Money'
total_money:
$ref: '#/components/schemas/Money'
location_id:
type: string
description: The ID of the location associated with the payment.
example: L1234567890
created_at:
type: string
format: date-time
description: The timestamp of when the payment was created.
example: '2026-01-15T10:00:00Z'
updated_at:
type: string
format: date-time
description: The timestamp of when the payment was last updated.
example: '2026-01-15T10:00:05Z'
CreatePaymentResponse:
type: object
properties:
payment:
$ref: '#/components/schemas/Payment'
GetPaymentResponse:
type: object
properties:
payment:
$ref: '#/components/schemas/Payment'
ListPaymentsResponse:
type: object
properties:
payments:
type: array
items:
$ref: '#/components/schemas/Payment'
cursor:
type: string
description: Pagination cursor for next page.
CreatePaymentRequest:
type: object
required:
- source_id
- idempotency_key
- amount_money
properties:
source_id:
type: string
description: Payment source (card nonce, token, etc.).
example: cnon:card-nonce-ok
idempotency_key:
type: string
description: Unique key to ensure idempotency.
example: 7b0f3ec5-086a-4871-8f13-3c81b3875218
amount_money:
$ref: '#/components/schemas/Money'
location_id:
type: string
description: ID of the accepting location.
example: L1234567890
Money:
type: object
description: Represents an amount of money in a specific currency.
properties:
amount:
type: integer
description: Amount in the smallest denomination of the currency.
example: 1500
currency:
type: string
description: 3-letter ISO 4217 currency code.
example: USD
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Personal access token for Square API
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://connect.squareup.com/oauth2/authorize
tokenUrl: https://connect.squareup.com/oauth2/token
scopes:
PAYMENTS_READ: Read payments
PAYMENTS_WRITE: Write payments
ORDERS_READ: Read orders
ORDERS_WRITE: Write orders
CUSTOMERS_READ: Read customers
CUSTOMERS_WRITE: Write customers
x-generated-from: documentation
x-source-url: https://developer.squareup.com/reference/square