API reference

Everything your servers need to create split payments, read their results and receive webhooks.

split.pay API · v0.1.0 · OpenAPI 3.1

Getting started

API keys and modes

Create keys in the merchant dashboard, under Developers. Keys starting with sp_test_ only see test data and move no real money; sp_live_ keys work on live data. The key decides the mode, so requests carry no mode parameter. A key is shown once: keep it on your server only.

Authentication

Send the key as a Bearer token: Authorization: Bearer sp_test_… Each key has scopes, and each endpoint below names the scope it needs; a key without it gets 403 insufficient_scope.

Idempotency

Endpoints marked Idempotency-Key require that header (8 to 255 characters from letters, digits and . _ : -). Repeating a request with the same key returns the first response with the header Idempotent-Replayed: true; the same key with a different request is refused with 409 idempotency_key_reused.

Pagination

Lists return data and next_cursor. Pass next_cursor as cursor to get the next page; limit is 1 to 100.

Buyer fee and who pays it

The first share (position 1) pays no processing fee; every other share adds the per-currency fixed fee from GET /v1/processing-fees. Example: USD 100.00 split in 4 means share #1 pays 25.00, shares #2 to #4 pay 25.30 each, and the payers pay 100.90 in total. The total the payers pay is amount + fee × (participants − 1). List the buyer (the person checking out) first so they get the free share. If the processor’s actual fixed fee is higher, you bear the difference.

Errors

Errors are JSON: { "error": { "type", "code", "message", "request_id", "details" } }. Use the HTTP status and the code, never the message, in your code. Quote request_id when you contact support.

Rate limits

600 requests per minute for each API key, and 3000 per minute for each IP address. Past the limit you get 429 rate_limited; wait for the number of seconds in the Retry-After header.

Webhooks and signatures

Create an endpoint with POST /v1/webhook-endpoints and keep its signing secret. Every delivery carries the Splitpay-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with the secret>, computed over the raw request body. Reject a request when no v1 matches or when t differs from your clock by more than 5 minutes. Delivery is at least once: deduplicate on the event id.

Catching up after downtime

GET /v1/events returns the same envelopes your endpoint received. After downtime, list the events created since you went offline (created_from) and skip the ids you already handled. Events are kept for 90 days.

Checkout SDK

The Checkout SDK opens the payment page in a popup over your site, so the customer does not leave it. Load the script from the split.pay payment page origin and pass the payment_url of a new session to SplitPay.open. The script has no dependencies, sets no cookies and tracks nothing.

<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 receives { type, state } (state is the public session state). The types:

share_authorized — The customer authorized their share.
session_authorized — Every share is authorized.
session_paid — The session is paid.
session_cancelled — The session was cancelled.
session_expired — The session expired.
return — The customer pressed the back-to-merchant button, just before leaving.
cancel — The customer pressed Cancel, just before leaving.

If the browser blocks the popup, the tab is redirected to the payment page (fallback "redirect", the default). With fallback "none", onClose is called with reason "blocked" so you can show a button instead. onClose is also called, once, when the window is closed. SplitPay.open throws a TypeError for a URL that is not on the origin of the script. Messages are sent only when the session has a return_url or cancel_url, and only to the origin of that URL.

These events are hints for your page only. Always confirm the outcome on your server: read the session with GET /v1/split-sessions/{id}, or rely on webhooks and the events feed.

Endpoints

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.

Scope: split_sessions:write

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string	Yes	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.

Request body

Name

Type

Required

Description

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

participants

integer | array<object>

Fields

Name

Type

Required

Description

array<object>

Fields

Name	Type	Required	Description
amount	integer	Yes	min > 0, max 999999999999
label	string	No	min length 1, max length 60

order

object

Yes

Fields

Name	Type	Required	Description
reference	string	Yes	min length 1, max length 100
description	string	No	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

Response 201

Name

Type

Required

Description

split_session

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
position	integer	Yes	min 1, max 9007199254740991
label	string \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
amount_charged	integer	Yes	min > 0, max 999999999999
application_fee_amount	integer	Yes	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
amount_refunded	integer	Yes	min 0, max 9007199254740991

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

min 0, max 9007199254740991

GET`/v1/split-sessions`

List split sessions

Newest first. The key decides the mode.

Scope: split_sessions:read

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	min 1, max 100, default 25
cursor	query	string (uuid)	No
state	query	enum: created \| collecting \| all_authorized \| capturing \| paid \| expiring \| expired \| cancelling \| cancelled \| capture_partial_failure \| compensating \| failed_reversed	No
reference	query	string	No	min length 1, max length 100
created_from	query	string (date-time)	No
created_to	query	string (date-time)	No

Response 200

Name

Type

Required

Description

data

array<object>

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

participant_count

integer

Yes

min 0, max 9007199254740991

participants_summary

object

Yes

Fields

Name

Type

Required

Description

counts

array<object>

Yes

Fields

Name	Type	Required	Description
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
count	integer	Yes	min 1, max 9007199254740991

items

array<object>

Yes

Fields

Name	Type	Required	Description
label	string \| null	Yes
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

amount_refunded

integer

Yes

min 0, max 9007199254740991

source

enum: merchant_api | merchant_dashboard

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

next_cursor

string | null

Yes

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

Retrieve a split session

Scope: split_sessions:read

Parameters

Name	In	Type	Required	Description
split_session_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

split_session

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
position	integer	Yes	min 1, max 9007199254740991
label	string \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
amount_charged	integer	Yes	min > 0, max 999999999999
application_fee_amount	integer	Yes	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
amount_refunded	integer	Yes	min 0, max 9007199254740991

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

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.

Scope: split_sessions:write

Parameters

Name	In	Type	Required	Description
split_session_id	path	string (uuid)	Yes
Idempotency-Key	header	string	Yes	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.

Response 200

Name

Type

Required

Description

split_session

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
position	integer	Yes	min 1, max 9007199254740991
label	string \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
amount_charged	integer	Yes	min > 0, max 999999999999
application_fee_amount	integer	Yes	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
amount_refunded	integer	Yes	min 0, max 9007199254740991

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

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.

Scope: refunds:write

Parameters

Name	In	Type	Required	Description
order_id	path	string (uuid)	Yes
Idempotency-Key	header	string	Yes	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.

Request body

Name	Type	Required	Description
amount	integer	No	min > 0, max 999999999999
reason	enum: requested_by_customer \| duplicate \| fraudulent \| other	No

Response 201

Name

Type

Required

Description

refund

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"refund"

Yes

order_id

string (uuid)

Yes

split_session_id

string (uuid)

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

Yes

status

enum: pending | processing | succeeded | partially_succeeded | failed

Yes

allocations

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
participant_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	Yes

created_at

string (date-time)

Yes

updated_at

string (date-time)

Yes

GET`/v1/refunds/{refund_id}`

Retrieve a refund

Scope: refunds:read

Parameters

Name	In	Type	Required	Description
refund_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

refund

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"refund"

Yes

order_id

string (uuid)

Yes

split_session_id

string (uuid)

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

Yes

status

enum: pending | processing | succeeded | partially_succeeded | failed

Yes

allocations

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
participant_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	Yes

created_at

string (date-time)

Yes

updated_at

string (date-time)

Yes

GET`/v1/refunds`

List refunds

Newest first. The key decides the mode.

Scope: refunds:read

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	min 1, max 100, default 25
cursor	query	string (uuid)	No
status	query	enum: pending \| processing \| succeeded \| partially_succeeded \| failed	No
reference	query	string	No	min length 1, max length 100
created_from	query	string (date-time)	No
created_to	query	string (date-time)	No

Response 200

Name

Type

Required

Description

data

array<object>

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"refund"

Yes

order_id

string (uuid)

Yes

split_session_id

string (uuid)

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

Yes

status

enum: pending | processing | succeeded | partially_succeeded | failed

Yes

allocations

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
participant_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	Yes

created_at

string (date-time)

Yes

updated_at

string (date-time)

Yes

settled_amount

integer | null

Yes

settled_currency

string | null

Yes

next_cursor

string | null

Yes

Payments

The individual payments of your split sessions.

GET`/v1/payments`

List payments

Newest first. The key decides the mode.

Scope: payments:read

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	min 1, max 100, default 25
cursor	query	string (uuid)	No
state	query	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	No
reference	query	string	No	min length 1, max length 100
created_from	query	string (date-time)	No
created_to	query	string (date-time)	No

Response 200

Name

Type

Required

Description

data

array<object>

Yes

Fields

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

next_cursor

string | null

Yes

GET`/v1/payments/{payment_id}`

Retrieve a payment

Scope: payments:read

Parameters

Name	In	Type	Required	Description
payment_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

payment

object

Yes

Fields

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

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.

Scope: events:read

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	min 1, max 100, default 25
cursor	query	string (uuid)	No
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	No
created_from	query	string (date-time)	No
created_to	query	string (date-time)	No

Response 200

Name

Type

Required

Description

data

array<object | object | object>

Yes

Fields

Name

Type

Required

Description

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

min 0, max 9007199254740991

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
object	"refund"	Yes
order_id	string (uuid)	Yes
split_session_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
currency	string	Yes	pattern ^[A-Z]{3}$
reason	enum: requested_by_customer \| duplicate \| fraudulent \| other \| null	Yes
status	enum: pending \| processing \| succeeded \| partially_succeeded \| failed	Yes
allocations	array<object>	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
object	"dispute"	Yes
payment_id	string (uuid) \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
currency	string	Yes	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	Yes
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	Yes
evidence_due_by	string (date-time) \| null	Yes
created_at	string (date-time)	Yes

next_cursor

string | null

Yes

GET`/v1/events/{event_id}`

Retrieve an event

Scope: events:read

Parameters

Name	In	Type	Required	Description
event_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
position	integer	Yes	min 1, max 9007199254740991
label	string \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
amount_charged	integer	Yes	min > 0, max 999999999999
application_fee_amount	integer	Yes	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
amount_refunded	integer	Yes	min 0, max 9007199254740991

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

min 0, max 9007199254740991

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"refund"

Yes

order_id

string (uuid)

Yes

split_session_id

string (uuid)

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

Yes

status

enum: pending | processing | succeeded | partially_succeeded | failed

Yes

allocations

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
participant_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	Yes

created_at

string (date-time)

Yes

updated_at

string (date-time)

Yes

object

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
object	"dispute"	Yes
payment_id	string (uuid) \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
currency	string	Yes	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	Yes
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	Yes
evidence_due_by	string (date-time) \| null	Yes
created_at	string (date-time)	Yes

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.

Scope: reports:read

Parameters

Name	In	Type	Required	Description
from	query	string (date-time)	Yes
to	query	string (date-time)	Yes
tz	query	string	Yes	min length 1, max length 64

Response 200

A UTF-8 CSV file.

GET`/v1/reports/refunds.csv`

Download the refunds report

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

Scope: reports:read

Parameters

Name	In	Type	Required	Description
from	query	string (date-time)	Yes
to	query	string (date-time)	Yes
tz	query	string	Yes	min length 1, max length 64

Response 200

A UTF-8 CSV file.

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

Download the split sessions report

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

Scope: reports:read

Parameters

Name	In	Type	Required	Description
from	query	string (date-time)	Yes
to	query	string (date-time)	Yes
tz	query	string	Yes	min length 1, max length 64

Response 200

A UTF-8 CSV file.

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.

Scope: webhook_endpoints:write

Request body

Name	Type	Required	Description
url	string	Yes	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>	Yes
description	string	No	min length 1, max length 200

Response 201

Name

Type

Required

Description

webhook_endpoint

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
object	"webhook_endpoint"	Yes
url	string	Yes
enabled_events	array<string>	Yes
status	enum: enabled \| disabled	Yes
description	string \| null	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes
secret	string	Yes

GET`/v1/webhook-endpoints`

List webhook endpoints

Scope: webhook_endpoints:read

Response 200

Name

Type

Required

Description

data

array<object>

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
object	"webhook_endpoint"	Yes
url	string	Yes
enabled_events	array<string>	Yes
status	enum: enabled \| disabled	Yes
description	string \| null	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

next_cursor

string | null

Yes

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

Retrieve a webhook endpoint

Scope: webhook_endpoints:read

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

webhook_endpoint

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
object	"webhook_endpoint"	Yes
url	string	Yes
enabled_events	array<string>	Yes
status	enum: enabled \| disabled	Yes
description	string \| null	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

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

Update a webhook endpoint

Scope: webhook_endpoints:write

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string (uuid)	Yes

Request body

Name	Type	Required	Description
url	string	No	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>	No
status	enum: enabled \| disabled	No
description	string \| null	No

Response 200

Name

Type

Required

Description

webhook_endpoint

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
object	"webhook_endpoint"	Yes
url	string	Yes
enabled_events	array<string>	Yes
status	enum: enabled \| disabled	Yes
description	string \| null	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

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

Delete a webhook endpoint

Past deliveries stay available for history.

Scope: webhook_endpoints:write

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string (uuid)	Yes

Response 204

No body.

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.

Scope: webhook_endpoints:write

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string (uuid)	Yes

Response 200

Name

Type

Required

Description

webhook_endpoint

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
object	"webhook_endpoint"	Yes
url	string	Yes
enabled_events	array<string>	Yes
status	enum: enabled \| disabled	Yes
description	string \| null	Yes
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes
secret	string	Yes

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).

Scope: split_sessions:read

Response 200

Name

Type

Required

Description

processing_fees

array<object>

Yes

Fields

Name	Type	Required	Description
currency	string	Yes	pattern ^[A-Z]{3}$
processing_fee_per_share	integer	Yes	min 0, max 9007199254740991

GET`/v1/currencies`

List supported currencies

Public: no API key needed.

No API key needed

Response 200

Name

Type

Required

Description

currencies

array<object>

Yes

Fields

Name	Type	Required	Description
code	string	Yes	pattern ^[A-Z]{3}$
exponent	integer	Yes	min 0, max 3
processing_fee_per_share	integer \| null	Yes

Webhook events

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.

Payload

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

state

Yes

split_mode

enum: merchant_defined | payer_defined

Yes

amount

integer

Yes

min > 0, max 999999999999

processing_fee_per_share

integer

Yes

min 0, max 9007199254740991

total_charged

integer

Yes

min 0, max 9007199254740991

currency

string

Yes

pattern ^[A-Z]{3}$

order

object

Yes

Fields

Name	Type	Required
id	string (uuid)	Yes
reference	string	Yes
description	string \| null	Yes

participants

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
position	integer	Yes	min 1, max 9007199254740991
label	string \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
amount_charged	integer	Yes	min > 0, max 999999999999
application_fee_amount	integer	Yes	min 0, max 9007199254740991
state	enum: created \| waiting_for_payment_method \| confirming \| requires_action \| authorized \| capturing \| captured \| cancelling \| cancelled \| failed \| refunding \| partially_refunded \| refunded	Yes
amount_refunded	integer	Yes	min 0, max 9007199254740991

fees

object

Yes

Fields

Name	Type	Required	Description
policy_version	string	Yes
application_fee_total	integer	Yes	min 0, max 9007199254740991

payment_url

string

Yes

expires_at

string (date-time)

Yes

created_at

string (date-time)

Yes

amount_refunded

integer

Yes

min 0, max 9007199254740991

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

Payload

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name

Type

Required

Description

string (uuid)

Yes

object

"refund"

Yes

order_id

string (uuid)

Yes

split_session_id

string (uuid)

Yes

amount

integer

Yes

min > 0, max 999999999999

currency

string

Yes

pattern ^[A-Z]{3}$

reason

enum: requested_by_customer | duplicate | fraudulent | other | null

Yes

status

enum: pending | processing | succeeded | partially_succeeded | failed

Yes

allocations

array<object>

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
participant_id	string (uuid)	Yes
amount	integer	Yes	min > 0, max 999999999999
status	enum: pending \| processing \| succeeded \| failed	Yes

created_at

string (date-time)

Yes

updated_at

string (date-time)

Yes

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

Payload

Name

Type

Required

Description

string (uuid)

Yes

object

"event"

Yes

created_at

string (date-time)

Yes

livemode

boolean

Yes

type

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

Yes

data

object

Yes

Fields

Name

Type

Required

Description

object

Yes

Fields

Name	Type	Required	Description
id	string (uuid)	Yes
object	"dispute"	Yes
payment_id	string (uuid) \| null	Yes
amount	integer	Yes	min > 0, max 999999999999
currency	string	Yes	pattern ^[A-Z]{3}$
status	enum: needs_response \| under_review \| won \| lost \| closed	Yes
reason	enum: fraudulent \| duplicate \| product_not_received \| product_unacceptable \| credit_not_processed \| subscription_canceled \| unrecognized \| processing_error \| general	Yes
evidence_due_by	string (date-time) \| null	Yes
created_at	string (date-time)	Yes

API reference

Getting started

API keys and modes

Authentication

Idempotency

Pagination

Buyer fee and who pays it

Errors

Rate limits

Webhooks and signatures

Catching up after downtime

Checkout SDK

Endpoints

Split sessions

POST/v1/split-sessions

Parameters

Request body

Response 201

GET/v1/split-sessions

Parameters

Response 200

GET/v1/split-sessions/{split_session_id}

Parameters

Response 200

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

Parameters

Response 200

Refunds

POST/v1/orders/{order_id}/refunds

Parameters

Request body

Response 201

GET/v1/refunds/{refund_id}

Parameters

Response 200

GET/v1/refunds

Parameters

Response 200

Payments

GET/v1/payments

Parameters

Response 200

GET/v1/payments/{payment_id}

Parameters

Response 200

Events

GET/v1/events

Parameters

Response 200

GET/v1/events/{event_id}

Parameters

Response 200

Reports

GET/v1/reports/payments.csv

Parameters

Response 200

GET/v1/reports/refunds.csv

Parameters

Response 200

GET/v1/reports/split-sessions.csv

Parameters

Response 200

Webhook endpoints

POST/v1/webhook-endpoints

Request body

Response 201

GET/v1/webhook-endpoints

Response 200

GET/v1/webhook-endpoints/{webhook_endpoint_id}

Parameters

Response 200

PATCH/v1/webhook-endpoints/{webhook_endpoint_id}

Parameters

Request body

Response 200

DELETE/v1/webhook-endpoints/{webhook_endpoint_id}

Parameters

Response 204

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

Parameters

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`