الانتقال إلى المحتوى الرئيسي

معالج الدفع

دمج دفع دودو في تطبيق إكسبريس الخاص بك.

بوابة العملاء

السماح للعملاء بإدارة الاشتراكات والتفاصيل.

الويب هوكس

استلام ومعالجة أحداث الويب هوك لمدفوعات دودو.

​
التثبيت

1

تثبيت الحزمة

قم بتشغيل الأمر التالي في جذر مشروعك:
npm install @dodopayments/express
2

إعداد متغيرات البيئة

قم بإنشاء ملف .env في جذر مشروعك:
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url
لا تقم بالتزام ملف .env أو الأسرار في نظام التحكم في الإصدارات.

​
أمثلة معالجات المسار

استخدم هذا المعالج لدمج دفع دودو في تطبيق إكسبريس الخاص بك. يدعم تدفقات الدفع الثابتة (GET)، الديناميكية (POST)، والجلسات (POST).
import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "[email protected]",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_code": "IKHZ23M9GQ",
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "[email protected]",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

​
معالج مسار الدفع

تدعم مدفوعات دودو ثلاثة أنواع من تدفقات الدفع لدمج المدفوعات في موقعك، هذا الموصل يدعم جميع أنواع تدفقات الدفع.
  • روابط الدفع الثابتة: روابط قابلة للمشاركة على الفور لجمع المدفوعات بسرعة وبدون كود.
  • روابط الدفع الديناميكية: توليد روابط دفع برمجياً مع تفاصيل مخصصة باستخدام API أو SDKs.
  • جلسات الدفع: إنشاء تجارب دفع آمنة وقابلة للتخصيص مع عربات منتجات مُعدة مسبقاً وتفاصيل العملاء.

​
معلمات الاستعلام المدعومة

​
productId
string
required
معرف المنتج (على سبيل المثال، ?productId=pdt_nZuwz45WAs64n3l07zpQR).
​
quantity
integer
كمية المنتج.
​
fullName
string
الاسم الكامل للعميل.
​
firstName
string
الاسم الأول للعميل.
​
lastName
string
اسم العائلة للعميل.
​
email
string
البريد الإلكتروني للعميل.
​
country
string
بلد العميل.
​
addressLine
string
عنوان العميل.
​
city
string
مدينة العميل.
​
state
string
ولاية/مقاطعة العميل.
​
zipCode
string
الرمز البريدي للعميل.
​
disableFullName
boolean
تعطيل حقل الاسم الكامل.
​
disableFirstName
boolean
تعطيل حقل الاسم الأول.
​
disableLastName
boolean
تعطيل حقل اسم العائلة.
​
disableEmail
boolean
تعطيل حقل البريد الإلكتروني.
​
disableCountry
boolean
تعطيل حقل البلد.
​
disableAddressLine
boolean
تعطيل حقل عنوان الشارع.
​
disableCity
boolean
تعطيل حقل المدينة.
​
disableState
boolean
تعطيل حقل الولاية.
​
disableZipCode
boolean
تعطيل حقل الرمز البريدي.
​
paymentCurrency
string
حدد عملة الدفع (على سبيل المثال، USD).
​
showCurrencySelector
boolean
عرض محدد العملة.
​
paymentAmount
integer
حدد مبلغ الدفع (على سبيل المثال، 1000 مقابل 10.00 دولار أمريكي).
​
showDiscounts
boolean
عرض حقول الخصم.
​
metadata_*
string
أي معلمة استعلام تبدأ بـ metadata_ سيتم تمريرها كبيانات وصفية.
إذا كانت productId مفقودة، فإن المعالج يرجع استجابة 400. كما أن المعلمات غير الصحيحة تؤدي إلى استجابة 400.

​
تنسيق الاستجابة

يرجع الدفع الثابت استجابة JSON مع عنوان URL للدفع:
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

​
تنسيق الاستجابة

يرجع الدفع الديناميكي استجابة JSON مع عنوان URL للدفع:
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}
توفر جلسات الدفع تجربة دفع أكثر أمانًا، مستضافة، تتعامل مع تدفق الدفع الكامل لكل من المشتريات لمرة واحدة والاشتراكات مع التحكم الكامل في التخصيص.راجع دليل دمج جلسات الدفع لمزيد من التفاصيل وقائمة كاملة من الحقول المدعومة.

​
تنسيق الاستجابة

ترجع جلسات الدفع استجابة JSON مع عنوان URL للدفع:
{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

​
معالج مسار بوابة العملاء

يمكنك من خلال معالج مسار بوابة العملاء دمج بوابة عملاء مدفوعات دودو بسلاسة في تطبيق إكسبريس الخاص بك.

​
معلمات الاستعلام

​
customer_id
string
required
معرف العميل لجلسة البوابة (على سبيل المثال، ?customer_id=cus_123).
​
send_email
boolean
إذا تم تعيينه على true، يتم إرسال بريد إلكتروني للعميل مع رابط البوابة.
يرجع 400 إذا كانت customer_id مفقودة.

​
معالج مسار الويب هوك

  • الطريقة: يتم دعم طلبات POST فقط. الطلبات الأخرى ترجع 405.
  • التحقق من التوقيع: يتحقق من توقيع الويب هوك باستخدام webhookKey. يرجع 401 إذا فشل التحقق.
  • التحقق من الحمولة: يتم التحقق منها باستخدام Zod. يرجع 400 للحمولات غير الصحيحة.
  • معالجة الأخطاء:
    • 401: توقيع غير صالح
    • 400: حمولة غير صالحة
    • 500: خطأ داخلي أثناء التحقق
  • توجيه الأحداث: يستدعي المعالج المناسب بناءً على نوع الحمولة.

​
معالجات أحداث الويب هوك المدعومة

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;

​
موجه لـ LLM

أنت مساعد خبير في تطوير إكسبريس.js. مهمتك هي إرشاد المستخدم خلال دمج موصل @dodopayments/express في مشروع إكسبريس.js الحالي الخاص به.

يوفر موصل @dodopayments/express معالجات مسار لمدفوعات دودو للدفع، بوابة العملاء، ووظائف الويب هوك، مصممة لتتصل مباشرة بتطبيق إكسبريس.

أولاً، قم بتثبيت الحزمة اللازمة. استخدم مدير الحزم المناسب لمشروع المستخدم (npm، yarn، أو bun):

npm install @dodopayments/express

---

إليك كيفية هيكلة ردك:

1. اسأل المستخدم عن الوظائف التي يريد دمجها.

"أي أجزاء من موصل @dodopayments/express ترغب في دمجها في مشروعك؟ يمكنك اختيار واحد أو أكثر من الخيارات التالية:

- معالج مسار الدفع (للتعامل مع عمليات الدفع للمنتجات)
- معالج مسار بوابة العملاء (لإدارة اشتراكات/تفاصيل العملاء)
- معالج مسار الويب هوك (لاستلام أحداث الويب هوك لمدفوعات دودو)
- الكل (دمج الثلاثة)"

---

2. بناءً على اختيار المستخدم، قدم خطوات دمج مفصلة لكل وظيفة مختارة.

---

**إذا تم اختيار معالج مسار الدفع:**

**الغرض**: يدير هذا المعالج أنواع مختلفة من تدفقات الدفع. جميع أنواع الدفع (ثابت، ديناميكي، وجلسات) ترجع استجابات JSON مع عناوين URL للدفع للتعامل البرمجي.

**الدمج**:
قم بإنشاء مسارات في تطبيق إكسبريس الخاص بك للدفع الثابت (GET)، الديناميكي (POST)، وجلسات الدفع (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// لجلسات الدفع
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

خيارات التكوين:

    bearerToken: مفتاح API لمدفوعات دودو (يوصى بتخزينه في متغير البيئة DODO_PAYMENTS_API_KEY).

    returnUrl (اختياري): عنوان URL لإعادة توجيه المستخدم بعد الدفع الناجح.

    environment: "test_mode" أو "live_mode"

    type: "static" (GET)، "dynamic" (POST)، أو "session" (POST)

يتوقع GET (الدفع الثابت) معلمات استعلام:

    productId (مطلوب)

    الكمية، حقول العميل (fullName، email، إلخ)، والبيانات الوصفية (metadata_*) اختيارية.

    يرجع: {"checkout_url": "https://checkout.dodopayments.com/..."}

يتوقع POST (الدفع الديناميكي) جسم JSON مع تفاصيل الدفع (لمرة واحدة أو اشتراك). راجع الوثائق للحصول على مخطط POST الكامل:

    المدفوعات لمرة واحدة: https://docs.dodopayments.com/api-reference/payments/post-payments

    الاشتراكات: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    يرجع: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (جلسات الدفع) - (موصى به) تجربة دفع أكثر تخصيصًا. ترجع JSON مع checkout_url: يتم إرسال المعلمات كجسم JSON. يدعم كل من المدفوعات لمرة واحدة والمدفوعات المتكررة. يرجع: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. للحصول على قائمة كاملة من الحقول المدعومة، راجع:

  دليل دمج جلسات الدفع: https://docs.dodopayments.com/developer-resources/checkout-session

إذا تم اختيار معالج مسار بوابة العملاء:

الغرض: يتيح هذا المسار للعملاء إدارة اشتراكاتهم عبر بوابة مدفوعات دودو.

الدمج:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

معلمات الاستعلام:

    customer_id (مطلوب): على سبيل المثال، ?customer_id=cus_123

    send_email (اختياري): إذا كان صحيحًا، يتم إرسال بريد إلكتروني للعميل برابط البوابة

يرجع 400 إذا كانت customer_id مفقودة.

إذا تم اختيار معالج مسار الويب هوك:

الغرض: يعالج أحداث الويب هوك الواردة من مدفوعات دودو لتفعيل الأحداث في تطبيقك.

الدمج:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // التعامل مع الحمولة العامة
  },
  // يمكنك أيضًا توفير معالجات دقيقة لكل نوع حدث أدناه
}));

الميزات:

    يُسمح فقط بطريقة POST - الأخرى ترجع 405

    يتم إجراء التحقق من التوقيع باستخدام webhookKey. يرجع 401 إذا كان غير صالح.

    تحقق من الحمولة المعتمد على Zod. يرجع 400 إذا كان المخطط غير صالح.

    جميع المعالجات هي وظائف غير متزامنة.

معالجات أحداث الويب هوك المدعومة:

يمكنك تمرير أي من المعالجات التالية:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened، onDisputeExpired، onDisputeAccepted، onDisputeCancelled، onDisputeChallenged، onDisputeWon، onDisputeLost

    onSubscriptionActive، onSubscriptionOnHold، onSubscriptionRenewed، onSubscriptionPlanChanged، onSubscriptionCancelled، onSubscriptionFailed، onSubscriptionExpired

    onLicenseKeyCreated

إعداد متغيرات البيئة:

تأكد من تعريف هذه المتغيرات البيئية في مشروعك:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" أو "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

استخدم هذه داخل كودك كالتالي:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

ملاحظة أمان: لا تقم بالتزام الأسرار في نظام التحكم في الإصدارات. استخدم ملفات .env محليًا ومديري الأسرار في بيئات النشر (مثل AWS، Vercel، Heroku، إلخ).