Square POS 私有数据 API:支付、订单与商品目录
Square Point of Sale 是商户用来受理银行卡、非接、现金与钱包付款的收银台应用。在收银背后,它创建扣款、查询未结工单与订单历史,并在同一个经认证的商户会话中读取会员积分余额、Checking 账户数字与待到账结算。下面的接口面是这份数据 API 的示意地图。
预授权工单通过 /v1/checkout/charge/{charge_id}/capture 携带 version_token 完成捕获,退款界面则提交 /v1/billing/refunds,携带 payment_id 与 amount_money。收银键盘同样由数据驱动:/v1/library/query 按 object_types 分页读取商品目录,/v1/stock/tracking-status 按规格返回 tracking_enabled 与 sold_count,让售罄商品在网格中变灰。
Square Point of Sale 是 Block 推出的线下收银应用,支持银行卡、非接、现金与钱包等收款方式。在收银台、工单、商品目录、会员积分、Checking 账户与存款到账等界面背后,应用通过经认证的 JSON 调用交换支付、订单、目录对象、会员账户、库存跟踪与商户余额数据。
应用截图
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 }依据应用界面推导;端点细节为示意说明,并非实际抓包。
依据银行小程序的卡详情界面重建与 Checking 区块展示的掩码卡号及路由字段一致
银行余额汇总
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 API
- Square POS 支付端点
- Square 收银扣款 API
- Square 订单管理器工单查询
- Square 会员积分账户
- Square Checking 余额汇总
- Square 待到账结算报表
- Square 商品目录库
- Square 商户经营资料
需要集成这个 App 的数据 API?
我们可为任意指定 App 交付定制集成——源码交付 USD 500 起,或托管 API 按调用计费。告诉我们您需要的数据即可。
- 每个项目均签 NDA 与 SOW
- 3–7 天交付
- 验收通过后才付款
- 仅在授权范围内作业