محول هونو - Dodo Payments Documentation

Checkout Handler

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

Customer Portal

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

Webhooks

استقبل وقم بمعالجة أحداث webhook من Dodo Payments.

التثبيت

Install the package

نفّذ الأمر التالي في جذر مشروعك:

npm install @dodopayments/hono

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 أو الأسرار في نظام التحكم بالإصدار.

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

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

Checkout Handler
Customer Portal Handler
Webhook Handler

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

  // route.ts
  import { Checkout } from '@dodopayments/hono';
  import Hono from 'hono'

  const app = new Hono()

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

  app.post(
  "/api/checkout",
  Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'dynamic'
  })
  );
  
  app.post(
  "/api/checkout",
  Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      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": "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 \
--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 { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
app.get(
    "/api/customer-portal",
    CustomerPortal({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT
    })
);

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 بأمان في تطبيق Hono الخاص بك.

// route.ts
import Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.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)

Supported Query Parameters

productId

string

مطلوب

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

quantity

integer

كمية المنتج.

fullName

string

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

firstName

string

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

lastName

string

الاسم الأخير للعميل.

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/..."
}

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/..."
}

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

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

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

customer_id

string

مطلوب

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

send_email

boolean

إذا تم تعيينه إلى true، يرسل بريدًا إلكترونيًا للعميل مع رابط البوابة.

يعيد 400 إذا كان customer_id مفقودًا.

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

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

معالجات أحداث Webhook المدعومة

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>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

موجه لـ LLM

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

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

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

npm install @dodopayments/hono

---

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

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

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

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

---

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

---

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

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

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

import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()

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

app.post(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session' // أو 'dynamic' للرابط الديناميكي
  })
);

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

    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_*) اختيارية.

يتوقع POST (الدفع الديناميكي) جسماً JSON مع تفاصيل الدفع (لمرة واحدة أو اشتراك). راجع الوثائق للحصول على مخطط 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 { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
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 (اختياري): إذا كانت true، يتم إرسال بريد إلكتروني للعميل برابط البوابة

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

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

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

الدمج:

import Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.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, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

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

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

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، إلخ.).

Checkout Handler

Customer Portal

Webhooks

​التثبيت

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

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

​Supported Query Parameters

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

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

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

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

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

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

​معالجات أحداث Webhook المدعومة

​موجه لـ LLM

التثبيت

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

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

Supported Query Parameters

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

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

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

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

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

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

معالجات أحداث Webhook المدعومة

موجه لـ LLM