Square POS 私有数据 API:支付、订单与商品目录
Square Point of Sale 是 Block, Inc.(前身为 2009 年由 Jack Dorsey 与 Jim McKelvey 创立的 Square)推出的免费收银应用,把 Android 手机或平板配上 Square Reader 读卡器,就成了能收银行卡、非接、现金与数字钱包付款的收银台。商户可以用数字键盘,或用由商品库(商品、规格、分类)生成的可视化商品网格开单;为酒吧挂账和桌台服务保留未结工单,先预授权、后完成扣款;也能在退款界面办理全额或部分退款。Order Manager 可按门店、员工和支付状态检索未结、已履约与已退款订单,交易历史覆盖每一笔销售,包括离线收款后再捕获的交易。收银之外,应用还内置会员积分计划(在柜台累积与兑换积分)、带顾客资料卡的客户名录、按规格的库存跟踪(售罄商品自动隐藏)、同步到收据与 Square Online 网店的商户资料,以及管理 Square Checking 借记卡、余额、即时到账与结算报表的银行模块。它面向美国商户——从咖啡馆、酒吧到零售柜台与流动摊贩——在小商户收银市场与 Clover、Toast、Shopify POS 等竞争。
收银台录入的付款会生成支付记录,携带 amount_money、tip_money、tax_money、payment.source_type 与 payment.receipt_number,并通过 location_id、order_id 与 customer_id 与商户账目的其余部分关联。预授权挂账在完成时补充 payment.approved_money,重新加载的支付通过 payment.card_details 给出捕获状态与卡品牌,退款则记录原始 payment_id、reason 以及经办的 team_member_id。
工单补上订单层:order.line_items、order.total_money 与 order.state,可按 employee_ids 和 payment_statuses 检索。商品库返回目录 objects 及其 related_objects,按规格的库存标记 statuses.tracking_enabled 与 statuses.sold_count 标示各门店哪些商品在跟踪库存、已售出多少。
销售周边还有买家与商户记录:会员账户的 loyalty_account.balance、loyalty_account.enrollment_type 与兑换所得的 coupon.discount_money;客户名录的 given_name、email_address 与 phone_number;商户资料的 entity.mcc、entity.business_type 与 entity.iana_time_zone;以及 Square Checking 资金的 balance_header.available_balance、balance_header.pending_balance,和携带 pending_settlement_report.net_money 与 pending_settlement_report.status 的待到账结算。
ERP 与会计团队按夜拉取含金额、小费、门店与明细行的已完成工单,与账簿对账;自助终端与第二屏凭会员令牌查询积分并提交兑换,让折扣在捕获前落到未结工单上;财资工具无需打开收银界面即可监控可用余额、待到账存款与手续费;线上商城镜像商品库与按规格的库存标记,让售罄规格同时从收银键盘和网店下架。openData Studio 把这些收银、会员与 Checking 记录变成可调用的开放数据,正好服务上述集成。
应用截图
API 端点一览
以下端点与请求/响应示例均依据应用界面推导重构,为示意说明,并非实际抓包。
创建收银扣款
POST
/v1/checkout/chargeopenbanking在收银台对银行卡、非接、现金或钱包支付方式发起扣款。扣款调用是收银流程背后的线上请求,返回成功界面所用的支付 id、金额、status 与收据。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌,JSON 请求体)。
- source_id
- idempotency_key
- amount_money
- tip_money
- tax_money
- location_id
- order_id
- customer_id
- autocomplete
- payment.id
- payment.status
- payment.source_type
- payment.receipt_number
POST /v1/checkout/charge HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "source_id": "cnon:card-nonce-ok", "idempotency_key": "pay-7f3a9c2e", "amount_money": {"amount": 1299, "currency": "USD"}, "tip_money": {"amount": 200, "currency": "USD"}, "location_id": "LXXXXXXXXXXXX", "order_id": "OrdXXXXXXXXXXXX", "customer_id": "CXXXXXXXXXXXX", "autocomplete": true, "note": "Table 12" }{ "payment": { "id": "NpyXwGPzL9X5kXgT0example", "created_at": "2026-09-27T14:03:11.000Z", "updated_at": "2026-09-27T14:03:12.000Z", "amount_money": {"amount": 1299, "currency": "USD"}, "tip_money": {"amount": 200, "currency": "USD"}, "tax_money": {"amount": 104, "currency": "USD"}, "status": "COMPLETED", "source_type": "CARD", "location_id": "LXXXXXXXXXXXX", "order_id": "OrdXXXXXXXXXXXX", "customer_id": "CXXXXXXXXXXXX", "receipt_number": "NpyX", "receipt_url": "https://merchant-receipts.example/preview/NpyXwGPzL9X5kXgT0example" } }获取收银扣款
GET
/v1/checkout/charge/{charge_id}openbanking按 id 重新加载单笔支付,使 POS 能在离线或延迟捕获的收银之后展示捕获状态、卡品牌/后四位、金额与关联订单。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- payment.id
- payment.created_at
- payment.updated_at
- payment.amount_money
- payment.tip_money
- payment.status
- payment.location_id
- payment.order_id
- payment.customer_id
- payment.card_details
- errors
GET /v1/checkout/charge/NpyXwGPzL9X5kXgT0example HTTP/1.1 Authorization: Bearer <merchant-session>{ "payment": { "id": "NpyXwGPzL9X5kXgT0example", "created_at": "2026-09-27T14:03:11.000Z", "updated_at": "2026-09-27T14:03:12.000Z", "amount_money": {"amount": 1299, "currency": "USD"}, "tip_money": {"amount": 200, "currency": "USD"}, "status": "COMPLETED", "location_id": "LXXXXXXXXXXXX", "order_id": "OrdXXXXXXXXXXXX", "customer_id": "CXXXXXXXXXXXX", "card_details": {"status": "CAPTURED", "card": {"card_brand": "VISA", "last_4": "1111"}} }, "errors": [] }捕获已授权扣款
POST
/v1/checkout/charge/{charge_id}/captureopenbanking当卖家在工单上点击完成时,捕获先前已授权(延迟捕获/预授权)的支付——用于酒吧挂账与酒店式预授权冻结。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- version_token
- payment.id
- payment.status
- payment.amount_money
- payment.approved_money
- payment.location_id
- payment.order_id
POST /v1/checkout/charge/NpyXwGPzL9X5kXgT0example/capture HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "version_token": "payver_8c21" }{ "payment": { "id": "NpyXwGPzL9X5kXgT0example", "status": "COMPLETED", "amount_money": {"amount": 1299, "currency": "USD"}, "approved_money": {"amount": 1299, "currency": "USD"}, "location_id": "LXXXXXXXXXXXX", "order_id": "OrdXXXXXXXXXXXX" } }创建退款
POST
/v1/billing/refundsopenbanking在 POS 退款界面对已完成支付发起全额或部分退款,携带原始 payment_id、amount_money 与可选 reason。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- idempotency_key
- amount_money
- payment_id
- order_id
- reason
- location_id
- team_member_id
- refund.id
- refund.status
- refund.created_at
POST /v1/billing/refunds HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "idempotency_key": "ref-aa12", "amount_money": {"amount": 1299, "currency": "USD"}, "payment_id": "NpyXwGPzL9X5kXgT0example", "order_id": "OrdXXXXXXXXXXXX", "reason": "Customer returned item", "location_id": "LXXXXXXXXXXXX", "team_member_id": "TMxxxxxxxx" }{ "refund": { "id": "NpyXwGPzL9X5kXgT0example_r1", "status": "COMPLETED", "amount_money": {"amount": 1299, "currency": "USD"}, "payment_id": "NpyXwGPzL9X5kXgT0example", "order_id": "OrdXXXXXXXXXXXX", "location_id": "LXXXXXXXXXXXX", "reason": "Customer returned item", "created_at": "2026-09-27T15:10:00.000Z" } }查询工单
POST
/v1/tickets/queryopendata驱动订单管理器/工单列表:按门店、员工、支付状态与自由文本筛选,分页搜索未结、已履约与已退款订单。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- merchant_id
- location_ids
- limit
- cursor
- search_term
- include_refund_orders
- employee_ids
- payment_statuses
- orders
- status
- localized_prompt_title
POST /v1/tickets/query HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "merchant_id": "MLXXXXXXXXXXXX", "location_ids": ["LXXXXXXXXXXXX"], "limit": 25, "cursor": "", "search_term": "Table 12", "include_refund_orders": false }{ "status": {"success": true}, "orders": [ { "id": "OrdXXXXXXXXXXXX", "location_id": "LXXXXXXXXXXXX", "state": "OPEN", "total_money": {"amount": 1499, "currency": "USD"}, "created_at": "2026-09-27T13:55:00.000Z" } ], "cursor": "eyJvIjoiT3JkIn0", "localized_prompt_title": "", "localized_prompt_description": "" }获取工单
POST
/v1/tickets/getopendata按 id 为订单详情视图加载单个工单/订单,含行项目、合计,以及是否把退货解析进返回载荷。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- order_id
- resolve_returns
- client_support
- order.id
- order.location_id
- order.state
- order.line_items
- order.total_money
- order.customer_id
POST /v1/tickets/get HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "order_id": "OrdXXXXXXXXXXXX", "resolve_returns": true }{ "order": { "id": "OrdXXXXXXXXXXXX", "location_id": "LXXXXXXXXXXXX", "state": "COMPLETED", "line_items": [ {"name": "Latte", "quantity": "1", "total_money": {"amount": 550, "currency": "USD"}} ], "total_money": {"amount": 1499, "currency": "USD"}, "customer_id": "CXXXXXXXXXXXX" } }查询商品目录对象
POST
/v1/library/queryopendata搜索商户商品库(商品、规格、分类),用于填充 POS 收银键盘、可视化浏览网格与支付链接的商品选择器。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- object_types
- include_related_objects
- include_deleted_objects
- include_inventory
- include_counts
- limit
- cursor
- query
- objects
- related_objects
POST /v1/library/query HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "object_types": ["ITEM", "ITEM_VARIATION", "CATEGORY"], "include_related_objects": true, "include_deleted_objects": false, "include_inventory": true, "limit": 50, "cursor": "" }{ "objects": [ { "type": "ITEM", "id": "ITEM_LATTE", "updated_at": "2026-09-20T18:00:00.000Z", "item_data": {"name": "Latte", "variations": [{"id": "VAR_LATTE_SM", "item_variation_data": {"name": "Small", "price_money": {"amount": 450, "currency": "USD"}}}]} } ], "related_objects": [], "cursor": "" }获取积分账户
POST
/v1/rewards/accountopenfinance按令牌查询买家的会员积分账户,使收银台能在累积或兑换前展示积分余额、注册类型与联系方式映射。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- loyalty_account_token
- options
- loyalty_account.balance
- loyalty_account.contact
- loyalty_account.enrolled_at
- loyalty_account.enrollment_type
- loyalty_account.mappings
- status
- errors
POST /v1/rewards/account HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "loyalty_account_token": "LoyAccXXXXXXXX" }{ "loyalty_account": { "loyalty_account_token": "LoyAccXXXXXXXX", "created_at": "2024-03-12T00:00:00Z", "enrolled_at": "2024-03-12T10:15:00Z", "balance": 420, "enrollment_type": "PHONE", "contact": {"name": "Alex Rivera", "phone_number": "+14155550123"}, "mappings": [{"type": "PHONE", "value": "+14155550123"}] }, "status": "SUCCESS", "errors": [] }兑换积分奖励
POST
/v1/rewards/redeemopenfinance对当前工单兑换会员奖励,返回优惠券令牌与更新后的积分余额,用于收银的折扣行。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- loyalty_account_token
- phone_token
- coupon_definition_token
- return_coupon_token
- idempotence_token
- coupon.coupon_token
- coupon.discount_money
- loyalty_account.balance
POST /v1/rewards/redeem HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "loyalty_account_token": "LoyAccXXXXXXXX", "coupon_definition_token": "CpnDef$5OFF", "idempotence_token": "redeem-9f2" }{ "coupon": { "coupon_token": "CpnXXXXXXXX", "discount_money": {"amount": 500, "currency": "USD"}, "name": "$5 off" }, "loyalty_account": { "loyalty_account_token": "LoyAccXXXXXXXX", "balance": 170 } }获取商户经营资料
GET
/v1/business/profileosint返回已登录商户的公开资料——法定/经营名称、地址、MCC、时区、联系方式与 published 标记——供设置、收据与线上商城使用。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- entity.name
- entity.nickname
- entity.business_type
- entity.country_code
- entity.street1
- entity.city
- entity.state
- entity.postal_code
- entity.phone
- entity.email
- entity.website
- entity.mcc
- entity.iana_time_zone
- entity.published
- entity.mobile_business
GET /v1/business/profile HTTP/1.1 Authorization: Bearer <merchant-session>{ "entity": { "name": "River Cafe", "nickname": "rivercafe", "business_type": "FOOD_AND_DRINK", "country_code": "US", "street1": "500 3rd St", "city": "San Francisco", "state": "CA", "postal_code": "94107", "phone": "+14155550100", "email": "[email protected]", "website": "https://rivercafe.example", "mcc": "5812", "iana_time_zone": "America/Los_Angeles", "published": true, "mobile_business": false }, "success": true }银行卡与账户详情
POST
/v1/banking/card-accountopenbanking为 POS 内的银行小程序加载商户借记卡与 Checking 账户详情(掩码 PAN、路由号码、可用余额、卡状态)。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- card_details
- card_details.last_4
- card_details.status
- card_details.available_balance
- error
POST /v1/banking/card-account HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "instrument_token": "inst_chk_01" }{ "card_details": { "last_4": "4421", "card_brand": "VISA", "status": "ACTIVE", "account_number_last_4": "8901", "routing_number": "121000248", "available_balance": {"amount": 482350, "currency": "USD"} }, "error": null }银行余额汇总
POST
/v1/banking/balance-summaryopenbanking返回余额标签页头部——商户 Checking 账户与即时到账功能的可用及在途余额——由 POS 银行小程序渲染在界面顶部。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- balance_header
- balance_header.available_balance
- balance_header.pending_balance
- balance_header.instrument_token
- error_message
POST /v1/banking/balance-summary HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "client_capability": {"capable_header_type": "BALANCE"} }{ "balance_header": { "available_balance": {"amount": 482350, "currency": "USD"}, "pending_balance": {"amount": 12500, "currency": "USD"}, "instrument_token": "inst_chk_01", "title": "Checking" }, "error_message": null }待到账结算报表
POST
/v1/banking/settlements/pendingopenfinance列出当前销售批次与待到账银行存款(总额、手续费、净额、状态),驱动 POS 的存款/到账报表。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- request_params
- active_sales_report
- pending_settlement_report
- pending_settlement_report.settlement_id
- pending_settlement_report.net_money
- pending_settlement_report.status
POST /v1/banking/settlements/pending HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "request_params": {"location_id": "LXXXXXXXXXXXX"} }{ "active_sales_report": { "settlement_id": "setl_today", "gross_money": {"amount": 184250, "currency": "USD"}, "net_money": {"amount": 178900, "currency": "USD"}, "fee_money": {"amount": 5350, "currency": "USD"} }, "pending_settlement_report": [ { "settlement_id": "setl_2026-09-26", "initiated_at": "2026-09-26T23:00:00Z", "net_money": {"amount": 96210, "currency": "USD"}, "status": "PENDING" } ] }库存跟踪状态
POST
/v1/stock/tracking-statusopendata返回某门店按规格的库存跟踪标记,使 POS 能展示库存数量、隐藏售罄商品,并决定销售是否扣减库存。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- location_id
- statuses
- statuses.catalog_object_id
- statuses.tracking_enabled
- statuses.sold_count
POST /v1/stock/tracking-status HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "location_id": "LXXXXXXXXXXXX" }{ "statuses": [ { "catalog_object_id": "VAR_LATTE_SM", "location_id": "LXXXXXXXXXXXX", "tracking_enabled": true, "sold_count": 42 } ] }更新客户
PUT
/v1/customers/{customer_id}osint在销售后或从客户资料界面,从 POS CRM 卡片更新客户名录中的客户(姓名、邮箱、电话、备注)。
认证方式: 已登录的商户会话,通过带认证的 HTTP API 客户端发起(Bearer 会话令牌)。
- given_name
- family_name
- email_address
- phone_number
- note
- version
- customer.id
- customer.created_at
- customer.updated_at
PUT /v1/customers/CXXXXXXXXXXXX HTTP/1.1 Authorization: Bearer <merchant-session> Content-Type: application/json { "given_name": "Alex", "family_name": "Rivera", "email_address": "[email protected]", "phone_number": "+14155550123", "note": "Prefers oat milk", "version": 7 }{ "customer": { "id": "CXXXXXXXXXXXX", "given_name": "Alex", "family_name": "Rivera", "email_address": "[email protected]", "phone_number": "+14155550123", "note": "Prefers oat milk", "created_at": "2024-01-08T16:00:00.000Z", "updated_at": "2026-09-27T14:20:00.000Z", "version": 8 } }
数据类别
- 支付
- 订单
- 商品目录
- 会员积分
- 商户资料
- 账户余额
- 结算到账
- 库存
- 客户
数据使用场景与案例
POS 销售账本同步至 ERP
夜间任务调用创建扣款与工单查询端点,拉取已完成工单(含 amount_money、tip_money、location_id 与订单行项目),再与商户的会计系统对账。
收银台积分余额查询
自助终端或第二屏流程按令牌调用积分账户端点展示积分余额,并提交积分兑换,让折扣在捕获扣款前落到未结工单上。
Square Checking 现金流监控
财资工具读取余额汇总与待到账端点,无需打开 POS 界面即可关注 available_balance、待到账存款与 fee_money。
面向第二渠道的商品目录与库存同步
线上商城通过目录查询端点与各规格库存跟踪标记镜像 POS 商品库,让售罄规格同时从收银键盘与网店下架。
常见问题
Square Point of Sale 在收银时发送哪些支付字段?
收银扣款调用携带 source_id、idempotency_key、amount_money、tip_money、tax_money、location_id、order_id 与 customer_id,并返回支付 id、status 与 receipt_number,供成功界面展示。
应用如何加载未结工单与订单历史?
订单管理器提交工单查询,携带 merchant_id、location_ids、limit、cursor 与 search_term,然后按 order_id 加载单个工单,在详情视图渲染行项目与合计。
能否在同一个 API 面上读取 Checking 余额?
可以。银行小程序调用余额汇总端点获取可用与在途余额,并调用卡账户端点获取掩码卡号、路由号码与状态数据。
会员积分相对支付处于什么位置?
会员积分是独立的积分服务:账户查询返回 loyalty_account_token、balance 与联系方式映射,兑换调用则在扣款捕获前把优惠券挂到当前工单上。
与 Square Point of Sale: Payment 相似的应用
- Clover POS — Fiserv 的 Clover 是一体式收银系统,提供终端机和应用市场,并可选用第三方收单机构,而不必绑定 Square 自有支付通道。
- Shopify POS — Shopify POS 是 Shopify 商户的线下收银端,把网店与实体收银台的库存和商品目录同步在一起。
- Toast POS — Toast 面向餐饮,提供厨房显示屏、桌台管理、线上点餐和排班工具,这些是 Square 通用收银机并不专攻的场景。
- Lightspeed Retail — Lightspeed Retail 是面向多门店的云 POS,支持供应商目录、商品规格、条码打印和库存报表,功能超出 Square 的基础库存工具。
- Helcim POS — Helcim 是免月费的 POS,采用 interchange-plus 定价,并带发票、库存和客户管理,面向希望使用独立商户账户而非 Square 固定费率套餐的卖家。
- PayPal POS — PayPal Point of Sale(原 Zettle)是免合约的移动收银方案,提供免费应用和读卡器,现场收款还可受理 Venmo。
- SumUp — SumUp 是面向快闪店和流动摊贩的低成本移动读卡器与应用,只需收卡而不必部署完整的 Square 式收银台。
- Stripe — Stripe 是可定制线上结账与 API 的支付平台,适合希望自行搭建收款流程、而不是使用 Square 打包 POS 的商家。
相关主题
- Square Point of Sale API
- Square POS 支付端点
- Square 收银扣款 API
- Square 订单管理器工单查询
- Square 会员积分账户
- Square Checking 余额汇总
- Square 待到账结算报表
- Square 商品目录库
- Square 商户经营资料
需要集成这个 App 的数据 API?
我们可为任意指定 App 交付定制集成——源码交付 USD 500 起,或托管 API 按调用计费。告诉我们您需要的数据即可。
- 每个项目均签 NDA 与 SOW
- 3–7 天交付
- 验收通过后才付款
- 仅在授权范围内作业