محول Fastify

Checkout Handler

قم بدمج صفحة دفع Dodo Payments في تطبيق Fastify الخاص بك.

Customer Portal

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

Webhooks

استقبل وعرّف أحداث webhook الخاصة بـ Dodo Payments.

التثبيت

Install the package

قم بتشغيل الأمر التالي في جذر المشروع الخاص بك:

npm install @dodopayments/fastify

Set up environment variables

أنشئ ملف .env في جذر المشروع الخاص بك:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""

لا تقم بتضمين ملف .env الخاص بك أو الأسرار في نظام التحكم بالإصدارات.

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

تفترض جميع الأمثلة أنك تستخدم Fastify App Router.

Checkout Handler
Customer Portal Handler
Webhook Handler

استخدم هذه المعالجة لدمج صفحة دفع Dodo Payments في تطبيق Fastify الخاص بك. تدعم تدفقات الدفع الثابتة (GET) والديناميكية (POST) وجلسات (POST).

  // route.ts
  import { Checkout } from '@dodopayments/fastify';
  import Fastify from 'fastify'

  const fastify = Fastify({})
  const checkoutGet = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'static'
  });

  const checkoutPost = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'dynamic'
  });

  const checkoutSession = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'session'
  });

  fastify.get('/api/checkout', checkoutGet.getHandler);
  fastify.post('/api/checkout', checkoutPost.postHandler);
  fastify.post('/api/checkout-session', checkoutSession.postHandler);

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": "test@example.com",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout-session \
--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": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

استخدم هذه المعالجة للسماح للعملاء بإدارة اشتراكاتهم وتفاصيلهم عبر بوابة عملاء Dodo Payments.

// route.ts
import { CustomerPortal } from "@dodopayments/fastify";
import Fastify from 'fastify'

const fastify = Fastify({})
const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});
fastify.get('/api/customer-portal', customerPortalHandler);

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

استخدم هذه المعالجة لاستقبال ومعالجة أحداث webhook الخاصة بـ Dodo Payments بأمان في تطبيق Fastify الخاص بك.

// route.ts
import Fastify from 'fastify'
import { Webhooks } from '@dodopayments/fastify'

const fastify = Fastify({})
fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
    done(null, body)
})

fastify.post('/api/webhooks', Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
    // Handle Payload Here
    console.log(payload)
}
}));

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

تدعم Dodo Payments ثلاثة أنواع من تدفقات الدفع لدمج المدفوعات في موقعك، ويدعم هذا الموصل جميع أنواع التدفقات.

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

Static Checkout (GET)

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

string

مطلوب

معرّف المنتج (مثلًا، ?productId=pdt_nZuwz45WAs64n3l07zpQR).

integer

كمية المنتج.

string

الاسم الكامل للعميل.

string

الاسم الأول للعميل.

string

اسم العائلة للعميل.

string

عنوان البريد الإلكتروني للعميل.

string

بلد العميل.

string

سطر عنوان العميل.

string

مدينة العميل.

string

ولاية/مقاطعة العميل.

string

الرمز البريدي للعميل.

boolean

تعطيل حقل الاسم الكامل.

boolean

تعطيل حقل الاسم الأول.

boolean

تعطيل حقل اسم العائلة.

boolean

تعطيل حقل البريد الإلكتروني.

boolean

تعطيل حقل البلد.

boolean

تعطيل حقل سطر العنوان.

boolean

تعطيل حقل المدينة.

boolean

تعطيل حقل الولاية.

boolean

تعطيل حقل الرمز البريدي.

string

تحديد عملة الدفع (مثلًا، USD).

boolean

إظهار محدد العملة.

number

يثبّت المبلغ المُحصّل بوحدات العملة الأساسية (مثلًا، 12.5 مقابل 12.50 دولارًا). لمنتجات ادفع ما تريد فقط، ويتم تجاهله إذا كان أقل من الحد الأدنى لسعر المنتج.

boolean

إظهار حقول الخصم.

string

سيتم تمرير أي معلمة استعلام تبدأ بـ metadata_ كـ metadata.

إذا كان productId مفقودًا، تعيد المعالجة استجابة 400. تؤدي معلمات الاستعلام غير الصالحة أيضًا إلى استجابة 400.

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

يرجع الدفع الثابت استجابة JSON مع عنوان URL للدفع:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Dynamic Checkout (POST)

أرسل المعلمات كجسم JSON في طلب POST.
يدعم كلا من المدفوعات لمرة واحدة والمتكررة.
للحصول على قائمة كاملة بحقول جسم POST المدعومة، راجع:
- Request body for a One Time Payment Product
- Request body for a Subscription Product

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

يرجع الدفع الديناميكي استجابة JSON مع عنوان URL للدفع:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Checkout Sessions (POST)

توفر جلسات الدفع تجربة دفع أكثر أمانًا مستضافة تتولى تدفق الدفع الكامل لكل من المشتريات لمرة واحدة والاشتراكات مع تحكم كامل بالتخصيص.راجع دليل تكامل جلسات الدفع لمزيد من التفاصيل وقائمة كاملة من الحقول المدعومة.

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

ترجع جلسات الدفع استجابة JSON مع عنوان URL للدفع:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

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

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

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

string

مطلوب

معرّف العميل لجلسة البوابة (مثال: ?customer_id=cus_123).

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

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

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

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

npm install @dodopayments/fastify

---

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

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

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

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

---

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

---

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

**الغرض**: يقوم هذا المعالج بإعادة توجيه المستخدمين إلى صفحة الدفع الخاصة بمدفوعات دودي.

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

import { Checkout } from '@dodopayments/fastify';
import Fastify from 'fastify'

const fastify = Fastify({})
const checkoutGet = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'static'
});

const checkoutPost = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'dynamic'
});

const checkoutSession = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session'
});

fastify.get('/api/checkout', checkoutGet.getHandler);
fastify.post('/api/checkout', checkoutPost.postHandler);
fastify.post('/api/checkout-session', checkoutSession.postHandler);

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

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

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

    environment: "test_mode" أو "live_mode"

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

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

    productId (مطلوب)

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

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

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

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

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

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

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

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

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

الدمج:

import { CustomerPortal } from "@dodopayments/fastify";
import Fastify from 'fastify'

const fastify = Fastify({})
const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});
fastify.get('/api/customer-portal', customerPortalHandler);

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

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

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

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

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

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

الدمج:

import Fastify from 'fastify'
import { Webhooks } from '@dodopayments/fastify'

const fastify = Fastify({})
fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
    done(null, body)
})

fastify.post('/api/webhooks', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // معالجة الحمولة هنا
    console.log(payload)
  }
}));

الميزات:

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

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

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

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

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

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

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

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

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

    onLicenseKeyCreated

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

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

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" أو "live_mode""

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

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

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

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

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Handler

Customer Portal

Webhooks

التثبيت

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

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

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

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

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

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

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

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

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

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

موجه لـ LLM

Checkout Handler

Customer Portal

Webhooks

​التثبيت

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

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

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

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

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

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

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

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

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

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

​موجه لـ LLM

التثبيت

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

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

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

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

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

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

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

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

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

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

موجه لـ LLM