API 参考

你的服务器创建分摊付款、读取结果和接收 webhook 所需的一切。

split.pay API · v0.1.0 · OpenAPI 3.1

下载 OpenAPI (JSON)

快速入门

API 密钥与模式

在商户后台的“开发者”中创建密钥。以 sp_test_ 开头的密钥只能看到测试数据，不会产生真实资金流动；sp_live_ 密钥用于正式数据。模式由密钥决定，因此请求中没有模式参数。密钥只显示一次：请只保存在你的服务器上。

身份验证

以 Bearer 令牌发送密钥：Authorization: Bearer sp_test_… 每个密钥有权限范围，下面每个接口都注明所需范围；缺少该范围的密钥会收到 403 insufficient_scope。

幂等性

标有 Idempotency-Key 的接口必须带此请求头（8 到 255 个字符，可用字母、数字和 . _ : -）。用相同密钥重复请求会返回第一次的响应，并带有请求头 Idempotent-Replayed: true；相同密钥但请求不同则返回 409 idempotency_key_reused。

分页

列表返回 data 和 next_cursor。把 next_cursor 作为 cursor 传入即可获取下一页；limit 范围为 1 到 100。

买家费用及承担方

第一份（position 1）无需支付手续费；其余每份在份额之外加上 GET /v1/processing-fees 返回的按币种固定费用。示例：100.00 美元分成 4 份，第 1 份支付 25.00，第 2 至 4 份各支付 25.30，付款人合计支付 100.90。付款人合计支付 = amount + fee × (参与者数 − 1)。请把买家（正在结账的人）列在第一位，让其享受免费份额。若支付处理方的实际固定费用更高，差额由您承担。

错误

错误为 JSON：{ "error": { "type", "code", "message", "request_id", "details" } }。请在代码中依据 HTTP 状态和 code 判断，不要依赖 message。联系支持时请提供 request_id。

速率限制

每个 API 密钥每分钟 600 次请求，每个 IP 地址每分钟 3000 次。超出限制将返回 429 rate_limited；请等待 Retry-After 请求头给出的秒数。

Webhook 与签名

通过 POST /v1/webhook-endpoints 创建端点并保存其签名密钥。每次投递都带有 Splitpay-Signature 请求头：t=<Unix 秒>,v1=<用密钥对 "t.body" 计算的十六进制 HMAC-SHA256>，基于原始请求体计算。若没有匹配的 v1，或 t 与你的时钟相差超过 5 分钟，请拒绝该请求。投递至少一次：请按事件 id 去重。

停机后补齐

GET /v1/events 返回与你的端点收到的相同的事件信封。停机后，列出离线以来创建的事件（created_from），并跳过已处理的 id。事件保留 90 天。

Checkout SDK

Checkout SDK 会在您的网站上方以弹出窗口打开付款页面，顾客无需离开您的网站。从 split.pay 付款页面的源加载脚本，并把新会话的 payment_url 传给 SplitPay.open。该脚本没有依赖，不设置 cookie，也不做任何跟踪。

<script src="https://pay.example.com/sdk/v1/splitpay.js"></script>
<script>
  // payment_url comes from POST /v1/split-sessions, created on your server.
  const checkout = SplitPay.open(paymentUrl, {
    onEvent: ({ type, state }) => {
      if (type === 'session_paid') showOrderStatus(); // a hint: your server confirms
    },
    onClose: ({ reason }) => showOrderStatus(), // reason: 'closed' | 'blocked'
    fallback: 'redirect', // or 'none'
  });
  // checkout.close(), checkout.focus(), checkout.closed
</script>

onEvent 收到 { type, state }（state 为会话的公开状态）。类型：

share_authorized — 顾客已授权自己的份额。
session_authorized — 所有份额均已授权。
session_paid — 会话已支付。
session_cancelled — 会话已取消。
session_expired — 会话已过期。
return — 顾客在离开前点击了返回商家按钮。
cancel — 顾客在离开前点击了取消。

如果浏览器拦截了弹出窗口，当前标签页会跳转到付款页面（fallback 为 "redirect"，默认值）。使用 fallback "none" 时，会以 reason "blocked" 调用 onClose，您可以改为显示一个按钮。窗口关闭时 onClose 也会被调用一次。若网址不在脚本所在的源上，SplitPay.open 会抛出 TypeError。只有会话设置了 return_url 或 cancel_url 时才会发送消息，且只发送到该网址的源。

这些事件只是给您页面的提示。请务必在您的服务器上确认结果：用 GET /v1/split-sessions/{id} 读取会话，或依靠 webhook 和事件流。

接口

Split sessions

One bill paid by several people.

POST`/v1/split-sessions`

Create a split session

Creates a split session and its payment link. Share payment_url with the people who pay.

范围: split_sessions:write

参数

名称	位置	类型	必填	说明
Idempotency-Key	header	string	是	Makes the request safe to repeat: the same key returns the first response (header Idempotent-Replayed: true). The same key with a different request is refused with 409 idempotency_key_reused.

请求体

名称

类型

必填

说明

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

participants

integer | array<object>

否

字段

名称

类型

必填

说明

array<object>

否

字段

名称	类型	必填	说明
amount	integer	是	min > 0, max 999999999999
label	string	否	min length 1, max length 60

order

object

是

字段

名称	类型	必填	说明
reference	string	是	min length 1, max length 100
description	string	否	min length 1, max length 200

return_url

string

否

max length 2048

cancel_url

string

否

max length 2048

expires_in

integer

否

min 600, max 518400

响应 201

名称

类型

必填

说明

split_session

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
position	integer	是	min 1, max 9007199254740991
label	string \| null	是
amount	integer	是	min > 0, max 999999999999
amount_charged	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

GET`/v1/split-sessions`

List split sessions

Newest first. The key decides the mode.

范围: split_sessions:read

参数

名称	位置	类型	必填	说明
limit	query	integer	否	min 1, max 100, default 25
cursor	query	string (uuid)	否
state	query	enum: created \| collecting \| all_authorized \| capturing \| paid \| expiring \| expired \| cancelling \| cancelled \| capture_partial_failure \| compensating \| failed_reversed	否
reference	query	string	否	min length 1, max length 100
created_from	query	string (date-time)	否
created_to	query	string (date-time)	否

响应 200

名称

类型

必填

说明

data

array<object>

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

participant_count

integer

是

min 0, max 9007199254740991

participants_summary

object

是

字段

名称

类型

必填

说明

counts

array<object>

是

字段

名称	类型	必填	说明
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
count	integer	是	min 1, max 9007199254740991

items

array<object>

是

字段

名称	类型	必填	说明
label	string \| null	是
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

amount_refunded

integer

是

min 0, max 9007199254740991

source

enum: merchant_api | merchant_dashboard

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

next_cursor

string | null

是

GET`/v1/split-sessions/{split_session_id}`

Retrieve a split session

范围: split_sessions:read

参数

名称	位置	类型	必填	说明
split_session_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

split_session

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
position	integer	是	min 1, max 9007199254740991
label	string \| null	是
amount	integer	是	min > 0, max 999999999999
amount_charged	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

POST`/v1/split-sessions/{split_session_id}/cancel`

Cancel a split session

Releases the card holds of a session that is not yet paid.

范围: split_sessions:write

参数

名称	位置	类型	必填	说明
split_session_id	path	string (uuid)	是
Idempotency-Key	header	string	是	Makes the request safe to repeat: the same key returns the first response (header Idempotent-Replayed: true). The same key with a different request is refused with 409 idempotency_key_reused.

响应 200

名称

类型

必填

说明

split_session

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
position	integer	是	min 1, max 9007199254740991
label	string \| null	是
amount	integer	是	min > 0, max 999999999999
amount_charged	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

Refunds

Return money to the participants of a paid order.

POST`/v1/orders/{order_id}/refunds`

Refund an order

Without an amount, the whole remaining refundable amount is refunded.

范围: refunds:write

参数

名称	位置	类型	必填	说明
order_id	path	string (uuid)	是
Idempotency-Key	header	string	是	Makes the request safe to repeat: the same key returns the first response (header Idempotent-Replayed: true). The same key with a different request is refused with 409 idempotency_key_reused.

请求体

名称	类型	必填	说明
amount	integer	否	min > 0, max 999999999999
reason	enum: requested_by_customer \| duplicate \| fraudulent \| other	否

响应 201

名称

类型

必填

说明

refund

object

是

字段

名称

类型

必填

说明

string (uuid)

是

object

"refund"

是

order_id

string (uuid)

是

split_session_id

string (uuid)

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

是

status

enum: pending | processing | succeeded | partially_succeeded | failed

是

allocations

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
participant_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	是

created_at

string (date-time)

是

updated_at

string (date-time)

是

GET`/v1/refunds/{refund_id}`

Retrieve a refund

范围: refunds:read

参数

名称	位置	类型	必填	说明
refund_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

refund

object

是

字段

名称

类型

必填

说明

string (uuid)

是

object

"refund"

是

order_id

string (uuid)

是

split_session_id

string (uuid)

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

是

status

enum: pending | processing | succeeded | partially_succeeded | failed

是

allocations

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
participant_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	是

created_at

string (date-time)

是

updated_at

string (date-time)

是

GET`/v1/refunds`

List refunds

Newest first. The key decides the mode.

范围: refunds:read

参数

名称	位置	类型	必填	说明
limit	query	integer	否	min 1, max 100, default 25
cursor	query	string (uuid)	否
status	query	enum: pending \| processing \| succeeded \| partially_succeeded \| failed	否
reference	query	string	否	min length 1, max length 100
created_from	query	string (date-time)	否
created_to	query	string (date-time)	否

响应 200

名称

类型

必填

说明

data

array<object>

是

字段

名称

类型

必填

说明

string (uuid)

是

object

"refund"

是

order_id

string (uuid)

是

split_session_id

string (uuid)

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

是

status

enum: pending | processing | succeeded | partially_succeeded | failed

是

allocations

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
participant_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	是

created_at

string (date-time)

是

updated_at

string (date-time)

是

settled_amount

integer | null

是

settled_currency

string | null

是

next_cursor

string | null

是

Payments

The individual payments of your split sessions.

GET`/v1/payments`

List payments

Newest first. The key decides the mode.

范围: payments:read

参数

名称	位置	类型	必填	说明
limit	query	integer	否	min 1, max 100, default 25
cursor	query	string (uuid)	否
state	query	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	否
reference	query	string	否	min length 1, max length 100
created_from	query	string (date-time)	否
created_to	query	string (date-time)	否

响应 200

名称

类型

必填

说明

data

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"payment"	是
split_session_id	string (uuid)	是
order_id	string (uuid)	是
order_reference	string	是
participant_id	string (uuid)	是
participant_label	string \| null	是
amount	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
currency	string	是	pattern ^[A-Z]{3}$
presentment_amount	integer \| null	是
presentment_currency	string \| null	是
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991
settled_amount	integer \| null	是
settled_currency	string \| null	是
refunded_settled	integer \| null	是
fees_total	integer \| null	是
net	integer \| null	是
fees_currency	string \| null	是
gateway_fee	integer \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

next_cursor

string | null

是

GET`/v1/payments/{payment_id}`

Retrieve a payment

范围: payments:read

参数

名称	位置	类型	必填	说明
payment_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

payment

object

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"payment"	是
split_session_id	string (uuid)	是
order_id	string (uuid)	是
order_reference	string	是
participant_id	string (uuid)	是
participant_label	string \| null	是
amount	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
currency	string	是	pattern ^[A-Z]{3}$
presentment_amount	integer \| null	是
presentment_currency	string \| null	是
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991
settled_amount	integer \| null	是
settled_currency	string \| null	是
refunded_settled	integer \| null	是
fees_total	integer \| null	是
net	integer \| null	是
fees_currency	string \| null	是
gateway_fee	integer \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

Events

The events behind your webhooks, to catch up after downtime.

GET`/v1/events`

List events

Each event is the envelope a webhook endpoint received. Use it to catch up after downtime.

范围: events:read

参数

名称	位置	类型	必填	说明
limit	query	integer	否	min 1, max 100, default 25
cursor	query	string (uuid)	否
type	query	enum: split_session.paid \| split_session.failed \| split_session.cancelled \| split_session.expired \| refund.succeeded \| refund.partially_succeeded \| refund.failed \| dispute.created \| dispute.updated \| dispute.closed	否
created_from	query	string (date-time)	否
created_to	query	string (date-time)	否

响应 200

名称

类型

必填

说明

data

array<object | object | object>

是

字段

名称

类型

必填

说明

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: split_session.paid | split_session.failed | split_session.cancelled | split_session.expired

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: refund.succeeded | refund.partially_succeeded | refund.failed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"refund"	是
order_id	string (uuid)	是
split_session_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
currency	string	是	pattern ^[A-Z]{3}$
reason	enum: requested_by_customer \| duplicate \| fraudulent \| other \| null	是
status	enum: pending \| processing \| succeeded \| partially_succeeded \| failed	是
allocations	array<object>	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: dispute.created | dispute.updated | dispute.closed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"dispute"	是
payment_id	string (uuid) \| null	是
amount	integer	是	min > 0, max 999999999999
currency	string	是	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	是
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	是
evidence_due_by	string (date-time) \| null	是
created_at	string (date-time)	是

next_cursor

string | null

是

GET`/v1/events/{event_id}`

Retrieve an event

范围: events:read

参数

名称	位置	类型	必填	说明
event_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: split_session.paid | split_session.failed | split_session.cancelled | split_session.expired

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
position	integer	是	min 1, max 9007199254740991
label	string \| null	是
amount	integer	是	min > 0, max 999999999999
amount_charged	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: refund.succeeded | refund.partially_succeeded | refund.failed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称

类型

必填

说明

string (uuid)

是

object

"refund"

是

order_id

string (uuid)

是

split_session_id

string (uuid)

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

是

status

enum: pending | processing | succeeded | partially_succeeded | failed

是

allocations

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
participant_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	是

created_at

string (date-time)

是

updated_at

string (date-time)

是

object

否

字段

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: dispute.created | dispute.updated | dispute.closed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"dispute"	是
payment_id	string (uuid) \| null	是
amount	integer	是	min > 0, max 999999999999
currency	string	是	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	是
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	是
evidence_due_by	string (date-time) \| null	是
created_at	string (date-time)	是

Reports

CSV downloads.

GET`/v1/reports/payments.csv`

Download the payments report

UTF-8 CSV with a header row; at most 25 months per download.

范围: reports:read

参数

名称	位置	类型	必填	说明
from	query	string (date-time)	是
to	query	string (date-time)	是
tz	query	string	是	min length 1, max length 64

响应 200

UTF-8 CSV 文件。

GET`/v1/reports/refunds.csv`

Download the refunds report

UTF-8 CSV with a header row; at most 25 months per download.

范围: reports:read

参数

名称	位置	类型	必填	说明
from	query	string (date-time)	是
to	query	string (date-time)	是
tz	query	string	是	min length 1, max length 64

响应 200

UTF-8 CSV 文件。

GET`/v1/reports/split-sessions.csv`

Download the split sessions report

UTF-8 CSV with a header row; at most 25 months per download.

范围: reports:read

参数

名称	位置	类型	必填	说明
from	query	string (date-time)	是
to	query	string (date-time)	是
tz	query	string	是	min length 1, max length 64

响应 200

UTF-8 CSV 文件。

Webhook endpoints

Where split.pay delivers your events.

POST`/v1/webhook-endpoints`

Create a webhook endpoint

The signing secret is returned only here and when it is rotated.

范围: webhook_endpoints:write

请求体

名称	类型	必填	说明
url	string	是	max length 2048
enabled_events	array<any> \| array<enum: split_session.paid \| split_session.failed \| split_session.cancelled \| split_session.expired \| refund.succeeded \| refund.partially_succeeded \| refund.failed \| dispute.created \| dispute.updated \| dispute.closed>	是
description	string	否	min length 1, max length 200

响应 201

名称

类型

必填

说明

webhook_endpoint

object

是

字段

名称	类型	必填
id	string (uuid)	是
object	"webhook_endpoint"	是
url	string	是
enabled_events	array<string>	是
status	enum: enabled \| disabled	是
description	string \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是
secret	string	是

GET`/v1/webhook-endpoints`

List webhook endpoints

范围: webhook_endpoints:read

响应 200

名称

类型

必填

说明

data

array<object>

是

字段

名称	类型	必填
id	string (uuid)	是
object	"webhook_endpoint"	是
url	string	是
enabled_events	array<string>	是
status	enum: enabled \| disabled	是
description	string \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

next_cursor

string | null

是

GET`/v1/webhook-endpoints/{webhook_endpoint_id}`

Retrieve a webhook endpoint

范围: webhook_endpoints:read

参数

名称	位置	类型	必填	说明
webhook_endpoint_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

webhook_endpoint

object

是

字段

名称	类型	必填
id	string (uuid)	是
object	"webhook_endpoint"	是
url	string	是
enabled_events	array<string>	是
status	enum: enabled \| disabled	是
description	string \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

PATCH`/v1/webhook-endpoints/{webhook_endpoint_id}`

Update a webhook endpoint

范围: webhook_endpoints:write

参数

名称	位置	类型	必填	说明
webhook_endpoint_id	path	string (uuid)	是

请求体

名称	类型	必填	说明
url	string	否	max length 2048
enabled_events	array<any> \| array<enum: split_session.paid \| split_session.failed \| split_session.cancelled \| split_session.expired \| refund.succeeded \| refund.partially_succeeded \| refund.failed \| dispute.created \| dispute.updated \| dispute.closed>	否
status	enum: enabled \| disabled	否
description	string \| null	否

响应 200

名称

类型

必填

说明

webhook_endpoint

object

是

字段

名称	类型	必填
id	string (uuid)	是
object	"webhook_endpoint"	是
url	string	是
enabled_events	array<string>	是
status	enum: enabled \| disabled	是
description	string \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是

DELETE`/v1/webhook-endpoints/{webhook_endpoint_id}`

Delete a webhook endpoint

Past deliveries stay available for history.

范围: webhook_endpoints:write

参数

名称	位置	类型	必填	说明
webhook_endpoint_id	path	string (uuid)	是

响应 204

无响应体。

POST`/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret`

Rotate the signing secret

Returns the new secret once. The previous secret keeps signing for 24 hours, so deliveries made in that window carry two signatures.

范围: webhook_endpoints:write

参数

名称	位置	类型	必填	说明
webhook_endpoint_id	path	string (uuid)	是

响应 200

名称

类型

必填

说明

webhook_endpoint

object

是

字段

名称	类型	必填
id	string (uuid)	是
object	"webhook_endpoint"	是
url	string	是
enabled_events	array<string>	是
status	enum: enabled \| disabled	是
description	string \| null	是
created_at	string (date-time)	是
updated_at	string (date-time)	是
secret	string	是

Reference data

Currencies and split.pay fees.

GET`/v1/processing-fees`

List the split.pay fee per share

The fixed fee per share, for each currency. Share #1 pays no fee; every other share adds it, so the total the payers pay is amount + fee × (participants − 1).

范围: split_sessions:read

响应 200

名称

类型

必填

说明

processing_fees

array<object>

是

字段

名称	类型	必填	说明
currency	string	是	pattern ^[A-Z]{3}$
processing_fee_per_share	integer	是	min 0, max 9007199254740991

GET`/v1/currencies`

List supported currencies

Public: no API key needed.

无需 API 密钥

响应 200

名称

类型

必填

说明

currencies

array<object>

是

字段

名称	类型	必填	说明
code	string	是	pattern ^[A-Z]{3}$
exponent	integer	是	min 0, max 3
processing_fee_per_share	integer \| null	是

Webhook 事件

split_session.paid — The session was paid in full.
split_session.failed — The session failed after authorisation and its payments were reversed.
split_session.cancelled — The session was cancelled.
split_session.expired — The session expired before everyone paid.

内容

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: split_session.paid | split_session.failed | split_session.cancelled | split_session.expired

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称

类型

必填

说明

string (uuid)

是

state

是

split_mode

enum: merchant_defined | payer_defined

是

amount

integer

是

min > 0, max 999999999999

processing_fee_per_share

integer

是

min 0, max 9007199254740991

total_charged

integer

是

min 0, max 9007199254740991

currency

string

是

pattern ^[A-Z]{3}$

order

object

是

字段

名称	类型	必填
id	string (uuid)	是
reference	string	是
description	string \| null	是

participants

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
position	integer	是	min 1, max 9007199254740991
label	string \| null	是
amount	integer	是	min > 0, max 999999999999
amount_charged	integer	是	min > 0, max 999999999999
application_fee_amount	integer	是	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	是
amount_refunded	integer	是	min 0, max 9007199254740991

fees

object

是

字段

名称	类型	必填	说明
policy_version	string	是
application_fee_total	integer	是	min 0, max 9007199254740991

payment_url

string

是

expires_at

string (date-time)

是

created_at

string (date-time)

是

amount_refunded

integer

是

min 0, max 9007199254740991

refund.succeeded — A refund completed.
refund.partially_succeeded — A refund completed for some participants only.
refund.failed — A refund failed.

内容

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: refund.succeeded | refund.partially_succeeded | refund.failed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称

类型

必填

说明

string (uuid)

是

object

"refund"

是

order_id

string (uuid)

是

split_session_id

string (uuid)

是

amount

integer

是

min > 0, max 999999999999

currency

string

是

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

是

status

enum: pending | processing | succeeded | partially_succeeded | failed

是

allocations

array<object>

是

字段

名称	类型	必填	说明
id	string (uuid)	是
participant_id	string (uuid)	是
amount	integer	是	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	是

created_at

string (date-time)

是

updated_at

string (date-time)

是

dispute.created — A customer opened a dispute.
dispute.updated — A dispute changed.
dispute.closed — A dispute was closed.

内容

名称

类型

必填

说明

string (uuid)

是

object

"event"

是

created_at

string (date-time)

是

livemode

boolean

是

type

enum: dispute.created | dispute.updated | dispute.closed

是

data

object

是

字段

名称

类型

必填

说明

object

是

字段

名称	类型	必填	说明
id	string (uuid)	是
object	"dispute"	是
payment_id	string (uuid) \| null	是
amount	integer	是	min > 0, max 999999999999
currency	string	是	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	是
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	是
evidence_due_by	string (date-time) \| null	是
created_at	string (date-time)	是

API 参考

快速入门

API 密钥与模式

身份验证

幂等性

分页

买家费用及承担方

错误

速率限制

Webhook 与签名

停机后补齐

Checkout SDK

接口

Split sessions

POST/v1/split-sessions

参数

请求体

响应 201

GET/v1/split-sessions

参数

响应 200

GET/v1/split-sessions/{split_session_id}

参数

响应 200

POST/v1/split-sessions/{split_session_id}/cancel

参数

响应 200

Refunds

POST/v1/orders/{order_id}/refunds

参数

请求体

响应 201

GET/v1/refunds/{refund_id}

参数

响应 200

GET/v1/refunds

参数

响应 200

Payments

GET/v1/payments

参数

响应 200

GET/v1/payments/{payment_id}

参数

响应 200

Events

GET/v1/events

参数

响应 200

GET/v1/events/{event_id}

参数

响应 200

Reports

GET/v1/reports/payments.csv

参数

响应 200

GET/v1/reports/refunds.csv

参数

响应 200

GET/v1/reports/split-sessions.csv

参数

响应 200

Webhook endpoints

POST/v1/webhook-endpoints

请求体

响应 201

GET/v1/webhook-endpoints

响应 200

GET/v1/webhook-endpoints/{webhook_endpoint_id}

参数

响应 200

PATCH/v1/webhook-endpoints/{webhook_endpoint_id}

参数

请求体

响应 200

DELETE/v1/webhook-endpoints/{webhook_endpoint_id}

参数

响应 204

POST/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret

参数

POST`/v1/split-sessions`

GET`/v1/split-sessions`

GET`/v1/split-sessions/{split_session_id}`

POST`/v1/split-sessions/{split_session_id}/cancel`

POST`/v1/orders/{order_id}/refunds`

GET`/v1/refunds/{refund_id}`

GET`/v1/refunds`

GET`/v1/payments`

GET`/v1/payments/{payment_id}`

GET`/v1/events`

GET`/v1/events/{event_id}`

GET`/v1/reports/payments.csv`

GET`/v1/reports/refunds.csv`

GET`/v1/reports/split-sessions.csv`

POST`/v1/webhook-endpoints`

GET`/v1/webhook-endpoints`

GET`/v1/webhook-endpoints/{webhook_endpoint_id}`

PATCH`/v1/webhook-endpoints/{webhook_endpoint_id}`

DELETE`/v1/webhook-endpoints/{webhook_endpoint_id}`

POST`/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret`

GET`/v1/processing-fees`

GET`/v1/currencies`