Square

2026-03-27 新闻来源：网淘吧围观:12

电脑广告

手机广告

Square

通过托管的 OAuth 认证访问 Square API。处理支付、管理客户、订单、目录项目、库存和发票。

快速开始

# List locations
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/squareup/{native-api-path}

将{native-api-path}替换为实际的 Square API 端点路径。网关会将请求代理到connect.squareup.com并自动注入您的 OAuth 令牌。

认证

所有请求都要求在 Authorization 请求头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

登录或在maton.ai
创建一个账户前往
maton.ai/settings

复制您的 API 密钥

在https://ctrl.maton.ai管理您的 Square OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=squareup&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'squareup'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "squareup",
    "metadata": {}
  }
}

在浏览器中打开返回的网址以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Square 连接，请使用Maton-Connection标头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早建立的）活动连接。

API 参考

地点

列出地点

GET /squareup/v2/locations

获取地点

GET /squareup/v2/locations/{location_id}

创建地点

POST /squareup/v2/locations
Content-Type: application/json

{
  "location": {
    "name": "New Location",
    "address": {
      "address_line_1": "123 Main St",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94102",
      "country": "US"
    }
  }
}

更新地点

PUT /squareup/v2/locations/{location_id}
Content-Type: application/json

{
  "location": {
    "name": "Updated Location Name"
  }
}

商户

获取商户

GET /squareup/v2/merchants/me

列出商户

GET /squareup/v2/merchants

支付

列出支付记录

GET /squareup/v2/payments

使用筛选条件：

GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z

获取支付详情

GET /squareup/v2/payments/{payment_id}

创建支付

POST /squareup/v2/payments
Content-Type: application/json

{
  "source_id": "cnon:card-nonce-ok",
  "idempotency_key": "unique-key-12345",
  "amount_money": {
    "amount": 1000,
    "currency": "USD"
  },
  "location_id": "{location_id}"
}

更新支付

PUT /squareup/v2/payments/{payment_id}
Content-Type: application/json

{
  "payment": {
    "tip_money": {
      "amount": 200,
      "currency": "USD"
    }
  },
  "idempotency_key": "unique-key-67890"
}

完成支付

POST /squareup/v2/payments/{payment_id}/complete
Content-Type: application/json

{}

取消支付

POST /squareup/v2/payments/{payment_id}/cancel
Content-Type: application/json

{}

退款

列出退款记录

GET /squareup/v2/refunds

获取退款详情

GET /squareup/v2/refunds/{refund_id}

创建退款

POST /squareup/v2/refunds
Content-Type: application/json

{
  "idempotency_key": "unique-refund-key",
  "payment_id": "{payment_id}",
  "amount_money": {
    "amount": 500,
    "currency": "USD"
  },
  "reason": "Customer requested refund"
}

客户

列出客户

GET /squareup/v2/customers

获取客户详情

GET /squareup/v2/customers/{customer_id}

创建客户

POST /squareup/v2/customers
Content-Type: application/json

{
  "given_name": "John",
  "family_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+15551234567"
}

更新客户

PUT /squareup/v2/customers/{customer_id}
Content-Type: application/json

{
  "email_address": "john.updated@example.com"
}

删除客户

DELETE /squareup/v2/customers/{customer_id}

搜索客户

POST /squareup/v2/customers/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "email_address": {
        "exact": "john.doe@example.com"
      }
    }
  }
}

订单

创建订单

POST /squareup/v2/orders
Content-Type: application/json

{
  "order": {
    "location_id": "{location_id}",
    "line_items": [
      {
        "name": "Item 1",
        "quantity": "1",
        "base_price_money": {
          "amount": 1000,
          "currency": "USD"
        }
      }
    ]
  },
  "idempotency_key": "unique-order-key"
}

获取订单详情

GET /squareup/v2/orders/{order_id}

更新订单

PUT /squareup/v2/orders/{order_id}
Content-Type: application/json

{
  "order": {
    "location_id": "{location_id}",
    "version": 1
  },
  "fields_to_clear": ["line_items"]
}

搜索订单

POST /squareup/v2/orders/search
Content-Type: application/json

{
  "location_ids": ["{location_id}"],
  "query": {
    "filter": {
      "state_filter": {
        "states": ["OPEN"]
      }
    }
  }
}

批量检索订单

POST /squareup/v2/orders/batch-retrieve
Content-Type: application/json

{
  "location_id": "{location_id}",
  "order_ids": ["{order_id_1}", "{order_id_2}"]
}

支付订单

POST /squareup/v2/orders/{order_id}/pay
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "payment_ids": ["{payment_id}"]
}

商品目录

列出目录

GET /squareup/v2/catalog/list

按类型筛选：

GET /squareup/v2/catalog/list?types=ITEM,CATEGORY

获取目录对象

GET /squareup/v2/catalog/object/{object_id}

更新或插入目录对象

POST /squareup/v2/catalog/object
Content-Type: application/json

{
  "idempotency_key": "unique-catalog-key",
  "object": {
    "type": "ITEM",
    "id": "#new-item",
    "item_data": {
      "name": "Coffee",
      "description": "Hot brewed coffee",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "#small-coffee",
          "item_variation_data": {
            "name": "Small",
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 300,
              "currency": "USD"
            }
          }
        }
      ]
    }
  }
}

删除目录对象

DELETE /squareup/v2/catalog/object/{object_id}

批量更新或插入目录对象

POST /squareup/v2/catalog/batch-upsert
Content-Type: application/json

{
  "idempotency_key": "unique-batch-key",
  "batches": [
    {
      "objects": [...]
    }
  ]
}

搜索目录对象

POST /squareup/v2/catalog/search
Content-Type: application/json

{
  "object_types": ["ITEM"],
  "query": {
    "text_query": {
      "keywords": ["coffee"]
    }
  }
}

获取目录信息

GET /squareup/v2/catalog/info

库存

检索库存数量

GET /squareup/v2/inventory/{catalog_object_id}

批量检索库存数量

POST /squareup/v2/inventory/counts/batch-retrieve
Content-Type: application/json

{
  "catalog_object_ids": ["{object_id_1}", "{object_id_2}"],
  "location_ids": ["{location_id}"]
}

批量变更库存

POST /squareup/v2/inventory/changes/batch-create
Content-Type: application/json

{
  "idempotency_key": "unique-inventory-key",
  "changes": [
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "catalog_object_id": "{object_id}",
        "location_id": "{location_id}",
        "quantity": "10",
        "from_state": "NONE",
        "to_state": "IN_STOCK"
      }
    }
  ]
}

检索库存调整

GET /squareup/v2/inventory/adjustments/{adjustment_id}

发票

列出发票

GET /squareup/v2/invoices?location_id={location_id}

获取发票

GET /squareup/v2/invoices/{invoice_id}

创建发票

POST /squareup/v2/invoices
Content-Type: application/json

{
  "invoice": {
    "location_id": "{location_id}",
    "order_id": "{order_id}",
    "primary_recipient": {
      "customer_id": "{customer_id}"
    },
    "payment_requests": [
      {
        "request_type": "BALANCE",
        "due_date": "2026-02-15"
      }
    ],
    "delivery_method": "EMAIL"
  },
  "idempotency_key": "unique-invoice-key"
}

更新发票

PUT /squareup/v2/invoices/{invoice_id}
Content-Type: application/json

{
  "invoice": {
    "version": 1,
    "payment_requests": [
      {
        "uid": "{payment_request_uid}",
        "due_date": "2026-02-20"
      }
    ]
  },
  "idempotency_key": "unique-update-key"
}

发布发票

POST /squareup/v2/invoices/{invoice_id}/publish
Content-Type: application/json

{
  "version": 1,
  "idempotency_key": "unique-publish-key"
}

取消发票

POST /squareup/v2/invoices/{invoice_id}/cancel
Content-Type: application/json

{
  "version": 1
}

删除发票

DELETE /squareup/v2/invoices/{invoice_id}?version=1

搜索发票

POST /squareup/v2/invoices/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "location_ids": ["{location_id}"],
      "customer_ids": ["{customer_id}"]
    }
  }
}

团队成员

搜索团队成员

POST /squareup/v2/team-members/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "location_ids": ["{location_id}"],
      "status": "ACTIVE"
    }
  }
}

获取团队成员

GET /squareup/v2/team-members/{team_member_id}

更新团队成员

PUT /squareup/v2/team-members/{team_member_id}
Content-Type: application/json

{
  "team_member": {
    "given_name": "Updated Name"
  }
}

忠诚度

列出忠诚度计划

GET /squareup/v2/loyalty/programs

获取忠诚度计划

GET /squareup/v2/loyalty/programs/{program_id}

搜索忠诚度账户

POST /squareup/v2/loyalty/accounts/search
Content-Type: application/json

{
  "query": {
    "customer_ids": ["{customer_id}"]
  }
}

创建忠诚度账户

POST /squareup/v2/loyalty/accounts
Content-Type: application/json

{
  "loyalty_account": {
    "program_id": "{program_id}",
    "mapping": {
      "phone_number": "+15551234567"
    }
  },
  "idempotency_key": "unique-key"
}

累积忠诚度积分

POST /squareup/v2/loyalty/accounts/{account_id}/accumulate
Content-Type: application/json

{
  "accumulate_points": {
    "order_id": "{order_id}"
  },
  "location_id": "{location_id}",
  "idempotency_key": "unique-key"
}

支付链接（在线结账）

列出支付链接

GET /squareup/v2/online-checkout/payment-links

获取支付链接

GET /squareup/v2/online-checkout/payment-links/{id}

创建支付链接

POST /squareup/v2/online-checkout/payment-links
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "quick_pay": {
    "name": "Payment for Service",
    "price_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "location_id": "{location_id}"
  }
}

更新支付链接

PUT /squareup/v2/online-checkout/payment-links/{id}
Content-Type: application/json

{
  "payment_link": {
    "version": 1,
    "description": "Updated description"
  }
}

删除支付链接

DELETE /squareup/v2/online-checkout/payment-links/{id}

卡

列出卡

GET /squareup/v2/cards
GET /squareup/v2/cards?customer_id={customer_id}

获取卡

GET /squareup/v2/cards/{card_id}

创建卡

POST /squareup/v2/cards
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "source_id": "cnon:card-nonce-ok",
  "card": {
    "customer_id": "{customer_id}"
  }
}

停用卡

POST /squareup/v2/cards/{card_id}/disable

支出

列出支出

GET /squareup/v2/payouts
GET /squareup/v2/payouts?location_id={location_id}

获取支出

GET /squareup/v2/payouts/{payout_id}

列出付款条目

GET /squareup/v2/payouts/{payout_id}/payout-entries

银行账户

列出银行账户

GET /squareup/v2/bank-accounts

获取银行账户

GET /squareup/v2/bank-accounts/{bank_account_id}

终端

列出终端结账记录

GET /squareup/v2/terminals/checkouts

创建终端结账

POST /squareup/v2/terminals/checkouts
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "checkout": {
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "device_options": {
      "device_id": "{device_id}"
    }
  }
}

获取终端结账

GET /squareup/v2/terminals/checkouts/{checkout_id}

搜索终端结账记录

POST /squareup/v2/terminals/checkouts/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "status": "COMPLETED"
    }
  }
}

取消终端结账

POST /squareup/v2/terminals/checkouts/{checkout_id}/cancel

分页

Square使用基于游标的分页机制。列表接口会在存在更多结果时返回一个游标字段：

GET /squareup/v2/payments?cursor={cursor_value}

响应包含分页信息：

{
  "payments": [...],
  "cursor": "next_page_cursor_value"
}

通过在后续请求中传递游标值来继续获取数据，直到不再返回游标为止。

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/squareup/v2/locations',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/squareup/v2/locations',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

注意事项

所有金额均以最小货币单位表示（例如，美元以美分为单位：1000 = 10.00美元）
ID为字母数字字符串
时间戳采用 ISO 8601 格式（例如，2026-02-07T01:59:28.459Z）
大多数写入操作都需要一个幂等键以防止重复操作
某些端点需要特定的 OAuth 权限范围（CUSTOMERS_READ、ORDERS_READ、ITEMS_READ、INVOICES_READ 等）
重要提示：使用 curl 命令时，如果 URL 包含方括号，请使用curl -g以禁用通配符解析
重要提示：当将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开

错误处理

状态码	含义
400	缺少 Square 连接或请求错误
401	Maton API 密钥无效或缺失
403	OAuth 权限不足
404	资源未找到
429	请求频率受限
4xx/5xx	来自 Square API 的透传错误

错误响应格式

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "NOT_FOUND",
      "detail": "Could not find payment with id: {payment_id}"
    }
  ]
}

故障排除：API 密钥问题

请检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

请确保您的 URL 路径以squareup开头。例如：

正确：https://gateway.maton.ai/squareup/v2/locations
错误：https://gateway.maton.ai/v2/locations

故障排除：权限不足

如果您收到带有INSUFFICIENT_SCOPES的 403 错误，说明 OAuth 连接不具备所需的权限。请创建一个新的连接，并确保在 OAuth 授权过程中授予所有必要的权限。

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Apollo 下一篇：Apollo