الميزات الجديدة
1. دعم تحليلات الطرف الثالث
تتبع سلوك العملاء عبر واجهة المتجر، ومرحلة الدفع، وبوابة العملاء باستخدام Google Analytics 4 وGoogle Tag Manager وMeta Pixel. أضف معرفات التتبع في الإعدادات → التحليلات لبدء جمع أحداث التجارة الإلكترونية.
المنصات المدعومة
| Platform | ID Format |
|---|
| Google Analytics 4 | G-XXXXXXXXXX |
| Google Tag Manager | GTM-XXXXXXX |
| Meta Pixel | Numeric (10-20 digits) |
purchase، add_payment_info، view_item، وview_item_list تلقائيًا إلى منصات التحليلات أثناء تصفح العملاء وإتمام عمليات الشراء.
مدعومة على واجهة المتجر، ومرحلة الدفع المستضافة، ومرحلة الدفع المتراكبة/المضمنة، وبوابة العملاء.
2. تخصيص موضوع صفحة الدفع
خصص مظهر صفحة الدفع عبر المعامل customization.theme_config عند إنشاء جلسات الدفع. قم بتكوين الألوان والخطوط ونصف القطر للحدود ونص الزر للوضعين الفاتح والداكن.
خيارات التكوين
| Property | Description |
|---|
light / dark | مخططات الألوان لكل وضع |
font_primary_url | عنوان URL مخصص للخط |
font_size | xs، sm، md، lg، xl، 2xl |
radius | نصف قطر الحد (مثل 8px) |
pay_button_text | نص الزر المخصص |
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_123', quantity: 1 }],
customization: {
theme_config: {
radius: '8px',
pay_button_text: 'Complete Purchase',
light: { button_primary: '#0066ff', text_primary: '#1a1a1a' },
dark: { button_primary: '#3385ff', text_primary: '#ffffff' }
}
},
return_url: 'https://yoursite.com/return'
});
3. منع تغيير الخطة عند فشل الدفع
المعامل الجديد on_payment_failure لتغيير خطة الاشتراك يتحكم بسلوك النظام عند فشل الدفع.
| الوضع | السلوك |
|---|
prevent_change | الاحتفاظ بالاشتراك في الخطة الحالية حتى ينجح الدفع |
apply_change | تطبيق تغيير الخطة فورًا بغض النظر عن نتيجة الدفع (افتراضي) |
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
proration_billing_mode: 'prorated_immediately',
on_payment_failure: 'prevent_change'
});
استخدم prevent_change للترقيات الحرجة حيث تريد التأكد من الدفع قبل منح الوصول إلى الميزات المتميزة.
تحديثات واجهة برمجة التطبيقات
واجهة برمجة تطبيقات دفتر الأستاذ الرصيد
نقطة النهاية الجديدة GET /balances/ledger لاسترداد سجلات دفتر حسابك مع التصفية والترقيم.
| Parameter | Description |
|---|
created_at_gte / created_at_lte | التصفية حسب النطاق الزمني |
event_type | التصفية حسب payment، refund، dispute، payout، إلخ. |
currency | التصفية حسب رمز العملة |
reference_object_id | التصفية حسب معرف الدفع/الاسترداد/النزاع المحدد |
استجابة الدفع: refund_status
تمت إضافة الحقل refund_status إلى استجابة GET /payments/{paymentId} للتحقق بسرعة من ما إذا تم استرداد الدفع دون الحاجة للاستعلام عن نقطة نهاية الاستردادات بشكل منفصل.
