مرجع واجهة البرمجة

كل ما تحتاجه خوادمك لإنشاء مدفوعات مقسّمة وقراءة نتائجها واستقبال webhooks.

split.pay API · v0.1.0 · OpenAPI 3.1

البدء

مفاتيح API والأوضاع

أنشئ المفاتيح من لوحة التاجر ضمن «المطورون». المفاتيح التي تبدأ بـ sp_test_ ترى بيانات الاختبار فقط ولا تحرّك أموالًا حقيقية، ومفاتيح sp_live_ تعمل على البيانات الفعلية. المفتاح هو من يحدد الوضع، فلا يوجد معامل للوضع في الطلبات. يظهر المفتاح مرة واحدة: احتفظ به على خادمك فقط.

المصادقة

أرسل المفتاح كرمز Bearer: Authorization: Bearer sp_test_… لكل مفتاح صلاحيات، وكل نقطة نهاية أدناه تذكر الصلاحية التي تحتاجها؛ والمفتاح الذي يفتقدها يحصل على 403 insufficient_scope.

عدم التكرار (Idempotency)

نقاط النهاية المعلَّمة بـ 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 عند التواصل مع الدعم.

حدود الطلبات

600 طلب في الدقيقة لكل مفتاح API، و3000 في الدقيقة لكل عنوان IP. عند تجاوز الحد تحصل على 429 rate_limited؛ انتظر عدد الثواني الموجود في الترويس Retry-After.

Webhooks والتوقيعات

أنشئ نقطة نهاية عبر POST /v1/webhook-endpoints واحتفظ بسرّ التوقيع الخاص بها. يحمل كل تسليم الترويس Splitpay-Signature: t=<ثوانٍ يونكس>,v1=<HMAC-SHA256 بصيغة hex لـ "t.body" بالسرّ>، محسوبًا على جسم الطلب الخام. ارفض الطلب إذا لم يطابق أي v1 أو إذا اختلف t عن ساعتك بأكثر من 5 دقائق. التسليم مرة واحدة على الأقل: تخلّص من التكرار بمعرّف الحدث.

اللحاق بعد التوقف

يعيد GET /v1/events الأظرف نفسها التي استقبلتها نقطة نهايتك. بعد التوقف اعرض الأحداث المنشأة منذ انقطاعك (created_from) وتجاهل المعرّفات التي عالجتها. تُحفظ الأحداث لمدة 90 يومًا.

Checkout SDK

يفتح Checkout SDK صفحة الدفع في نافذة منبثقة فوق موقعك، فلا يغادر العميل موقعك. حمّل السكربت من أصل صفحة الدفع في split.pay ومرّر payment_url لجلسة جديدة إلى SplitPay.open. السكربت بلا تبعيات ولا يضع ملفات تعريف ارتباط ولا يتتبع شيئًا.

<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" يُستدعى onClose بالسبب "blocked" لتعرض زرًا بدلًا من ذلك. ويُستدعى onClose مرة واحدة أيضًا عند إغلاق النافذة. يرمي SplitPay.open خطأ TypeError إذا لم يكن الرابط على أصل السكربت. لا تُرسل الرسائل إلا إذا كان للجلسة return_url أو cancel_url، وإلى أصل ذلك الرابط فقط.

هذه الأحداث تلميحات لصفحتك فقط. تأكد دائمًا من النتيجة على خادمك: اقرأ الجلسة عبر GET /v1/split-sessions/{id}، أو اعتمد على webhooks وسجل الأحداث.

نقاط النهاية

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

ملف CSV بترميز UTF-8.

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

ملف CSV بترميز UTF-8.

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

ملف CSV بترميز UTF-8.

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 والأوضاع

المصادقة

عدم التكرار (Idempotency)

تقسيم الصفحات

رسوم المشتري ومن يتحملها

الأخطاء

حدود الطلبات

Webhooks والتوقيعات

اللحاق بعد التوقف

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`