الأدلةمرجع الـ APIلوحة التحكم
English

المدفوعات

كائن Payment وحالاته وكيف تنتقل عملية الدفع من الإنشاء إلى نتيجة نهائية.

يمثّل كائن Payment محاولة واحدة لتحصيل مبلغ من العميل. تنشئه من خادمك، ويدفع العميل في صفحة الدفع المستضافة، ثم تنتهي العملية بالحالة succeeded أو expired.

دورة الحياة

مفتوحة
requires_payment

أُنشئت. بانتظار أن يدفع العميل عبر checkout_url.

قيد المعالجة
processing

أرسل العميل الدفع. النتيجة لم تُحسم بعد.

النتيجة
succeeded

تم تحصيل المبلغ. حالة نهائية. يمكنك تنفيذ الطلب، والاسترداد متاح.

failed

رُفضت أو حدث خطأ. راجع failure_code. يمكن دفعها عبر checkout_url حتى expires_at.

canceled

ألغى العميل الدفع من صفحة الدفع. يمكن دفعها حتى expires_at.

expired

لم تُدفع قبل expires_at. حالة نهائية.

دورة حياة حالة الدفع
الحالةنهائيةالمعنىما الذي تفعله
requires_paymentلاأُنشئت وتنتظر العميل في checkout_url.وجّه العميل إلى checkout_url.
processingلاأرسل العميل الدفع ولم تُعرف النتيجة بعد.اعرض رسالة "نتحقق من دفعتك" وانتظر الـ Webhook.
succeededنعمتم تحصيل المبلغ.نفّذ الطلب. الاسترداد متاح.
failedلارُفضت أو حدث خطأ. يوضح failure_code وfailure_message السبب.اسمح للعميل بالمحاولة مجددًا عبر checkout_url نفسه حتى expires_at.
canceledلاضغط العميل إلغاء في صفحة الدفع.اعرض عليه المحاولة مجددًا عبر checkout_url نفسه.
expiredنعملم تُدفع قبل expires_at.أنشئ عملية دفع جديدة إذا عاد العميل.

الحالتان succeeded وexpired نهائيتان ولا تتغيران أبدًا، أما failed وcanceled فليستا كذلك: حتى expires_at يستطيع العميل فتح checkout_url نفسه والدفع مجددًا، فتصبح العملية succeeded. لا تُغلق الطلب عند payment.failed أو payment.canceled، بل انتظر payment.succeeded أو payment.expired.

الاسترداد لا يغيّر status، بل يزيد قيمة amount_refunded. عندما تساوي amount_refunded قيمة amount تكون العملية مستردة بالكامل، وما بين ذلك استرداد جزئي. راجع الاسترداد.

كل تغيير من هذه التغييرات في الحالة يرسل حدث Webhook: payment.succeeded أو payment.failed أو payment.canceled أو payment.expired.

إنشاء عملية دفع

POST /v1/payments

المعاملالنوعمطلوبالوصف
amountعدد صحيحنعمالمبلغ بالوحدات الصغرى. القيمة 12500 مع KWD تعني 12.500 د.ك.
currencyنصنعمKWD أو SAR أو AED أو QAR أو BHD أو OMR أو JOD أو EGP.
return_urlنصنعمالرابط الذي يعود إليه العميل بعد الدفع، حتى 2,000 حرف. يجب أن يبدأ بـ https:// في الوضع الحي، ويقبل وضع الاختبار http:// أيضًا. راجع معالجة رابط العودة.
descriptionنصلاحتى 500 حرف. يظهر للعميل في صفحة الدفع وفي لوحة التحكم.
referenceنصلامعرّفك الخاص، مثل رقم الطلب، حتى 100 حرف. يمكنك تصفية المدفوعات به.
customerكائنلاname وemail وphone (بالصيغة الدولية مثل +96550000000). كلها اختيارية.
payment_methodنصلاعرض هذه الوسيلة وحدها في صفحة الدفع: knet أو mada أو card أو apple_pay أو google_pay أو benefit أو stc_pay. تعتمد الوسائل المتاحة لك على حسابك، والوسيلة التي لا يدعمها حسابك تعيد 422 validation_error. راجع وسائل الدفع وحسابك.
languageنصلالغة صفحة الدفع: en أو ar.
send_emailمنطقيلاtrue يرسل الدفعة إلى customer.email كفاتورة مع زر ادفع الآن. الافتراضي false. يتطلب customer.email. راجع رسائل الفواتير والإيصالات.
metadataكائنلاحتى 20 زوجًا من المفاتيح والقيم النصية. راجع البيانات الوصفية.
expires_in_minutesعدد صحيحلاالمهلة المتاحة للعميل كي يدفع، من 5 إلى 43200 (30 يومًا). الافتراضي 60.

في بعض الحسابات يجب أن تنتهي المبالغ بالعملات ذات المنازل العشرية الثلاث (KWD وBHD وOMR وJOD) بصفر، وإلا فشل الطلب بالخطأ 422 validation_error (details.fields.amount). راجع المبالغ ذات المنازل الثلاث.

الاستجابة 201 Created مع كائن Payment. أرسل الترويسة Idempotency-Key حتى لا تُنشئ إعادةُ المحاولة عمليةَ دفع ثانية (منع التكرار).

كائن Payment

{
  "id": "pay_01JBX4T9W2",
  "object": "payment",
  "livemode": false,
  "amount": 12500,
  "currency": "KWD",
  "amount_refunded": 0,
  "status": "succeeded",
  "description": "Order #1042",
  "reference": "1042",
  "customer": { "name": "Sara Ali", "email": "sara@example.com", "phone": "+96550000000" },
  "payment_method": "card",
  "card": { "brand": "visa", "last4": "1019" },
  "channel": "api",
  "checkout_url": "https://api.teyra.co/checkout/pay_01JBX4T9W2",
  "return_url": "https://shop.example.com/thanks",
  "failure_code": null,
  "failure_message": null,
  "commission": 313,
  "net": 12187,
  "metadata": { "order_id": "1042" },
  "payment_link_id": null,
  "created_at": "2026-10-28T14:07:00.000Z",
  "paid_at": "2026-10-28T14:08:12.000Z",
  "expires_at": "2026-10-28T15:07:00.000Z"
}
الحقلالوصف
idمعرّف فريد يبدأ بـ pay_.
livemodefalse للمدفوعات التجريبية وtrue للمدفوعات الحية.
amount وcurrencyما يدفعه العميل، بالوحدات الصغرى.
amount_refundedإجمالي ما تم استرداده حتى الآن، من 0 إلى amount.
statusراجع دورة الحياة.
payment_methodوسيلة الدفع بعد معرفتها: card أو mada أو knet أو apple_pay أو google_pay أو benefit أو stc_pay، أو null. ومع Apple Pay وGoogle Pay يحمل card علامة بطاقة المحفظة وآخر أربعة أرقام منها.
cardلمدفوعات البطاقات: brand وlast4 فقط. لا تكشف تيرا باي أرقام البطاقات كاملة أبدًا.
channelمصدر عملية الدفع: api أو payment_link أو shopify أو woocommerce أو dashboard.
checkout_urlصفحة الدفع المستضافة لهذه العملية.
failure_code وfailure_messageسبب الفشل عندما تكون الحالة failed.
commission وnetتُحدَّدان عند نجاح الدفع، بالوحدات الصغرى. commission هي رسوم تيرا باي: سعرك (نسبة مئوية زائد مبلغ ثابت لكل عملية دفع)، وهي الرسوم الوحيدة التي تُخصم من الدفعة. وnet هو ما تستلمه: amount − commission. راجع الرسوم والمبلغ الصافي.
payment_link_idرابط الدفع الذي أنشأ هذه العملية، إن وُجد.
paid_at وexpires_atوقت نجاح الدفع، والموعد النهائي للدفع.

جلب المدفوعات وعرضها

# One payment
curl https://api.teyra.co/v1/payments/pay_01JBX4T9W2 \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY"

# Succeeded payments created in October 2026
curl -G https://api.teyra.co/v1/payments \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY" \
  -d status=succeeded \
  -d created_gte=2026-10-01T00:00:00Z \
  -d created_lte=2026-10-31T23:59:59Z \
  -d limit=50

مرشحات GET /v1/payments: status وreference وcreated_gte وcreated_lte، إضافة إلى limit وcursor (ترقيم الصفحات). المعرّف غير الموجود، أو الذي يخص الوضع الآخر، يعيد 404 payment_not_found.

التالي

وضع الاختبار والوضع الحي

ابنِ تكاملك في وضع الاختبار دون أموال حقيقية، ثم انتقل إلى المفاتيح الحية بعد اعتماد حسابك مستعينًا بقائمة التحقق قبل الإطلاق.

وسائل الدفع وحسابك

قيم payment_method التي يقبلها حسابك، وقاعدة المبالغ في العملات ذات المنازل الثلاث، وكيف تعمل صفحة الدفع والرسوم والاسترداد والاعتراضات في كل نوع من الحسابات.

في هذه الصفحة

دورة الحياة
إنشاء عملية دفع
كائن Payment
جلب المدفوعات وعرضها
التالي