مثال على التكامل مع PayPal

في هذا الدرس التعليمي، سنوضح كيفية دمج PayPal وسنستعرض العقد الجديدة.

1. تتبع حدث إنشاء الطلب

1.1. حدث "تم إنشاء الطلب" في وحدة "الأحداث".

لتتبع الأحداث في وحدة "التكاملات"، قم بإنشاء حدث في وحدة "الأحداث".

تم وصف وحدة الأحداث بالتفصيل هنا.

1.2. تتبع حدث إنشاء الطلب.

• اسحب العقدة "الأحداث" إلى مساحة العمل.
• قم بتغيير القيمة في حقل "Set" إلى "orderEvent".
• سيتم حفظ الحدث في كائن "msg.orderEvent" ويمكن استخدامه في عقود أخرى.
• اختر من القائمة الحدث الذي تم إنشاؤه "تم إنشاء الطلب" واضغط على "submit".

في هذا المثال، نحن نشترك في حدث إنشاء الطلب ونحفظ الحدث في "msg.orderEvent" لاستخدامه لاحقًا.

يمكنك معرفة المزيد عن وحدة الأحداث هنا.

2. إنشاء جلسة الدفع

2.1. أنشئ حساب دفع

قبل بدء التكامل، قم بإنشاء حساب مخصص لـ PayPal.

تم وصف كيفية القيام بذلك هنا.

2.2. أنشئ جلسة دفع

• اسحب العقدة "admin-api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "إنشاء جلسة دفع" وأدخل الكود من الوصف أدناه في حقل "Request body".

{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}

هنا نستخرج معرف الطلب من كائن "msg.orderEvent" ونشكل طلبًا لإنشاء جلسة دفع. يقبل طلب إنشاء الجلسة المعلمات: "orderId" - المعرف و "type" - نوع جلسة الدفع (session أو intent).

يمكنك معرفة المزيد عن وحدة admin-api هنا.

2.3. قم بتعيين المعرف المستلم في msg.paymentSessionId

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هنا نقوم بتعيين "msg.paymentSessionId" إلى معرف جلسة الدفع الذي تم الحصول عليه نتيجة تنفيذ العقدة السابقة.

msg.paymentSessionId = msg.payload.id

return msg

يمكنك معرفة المزيد عن وحدة Function هنا.

3. المصادقة في PayPal

3.1. قم بتعيين المعلمات للمصادقة في PayPal

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هنا نقوم بتعيين القيم في حقول "payload" و "headers" لكائن "msg". تحتاج هذه القيم لتنفيذ العقدة التالية.

// تعيين جسم الطلب
msg.payload = {
    grant_type: 'client_credentials',
}
// تعيين الرؤوس
msg.headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    Accept: 'application/json',
}

return msg

يمكنك معرفة المزيد عن معلمات الدفع في وثائق PayPal

يمكنك معرفة المزيد عن وحدة Function هنا.

3.2. طلب الحصول على access token

• اسحب العقدة "http request" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر في حقل Method الخيار "POST".
• اختر في حقل Data الخيار "Send as request body".
• أدخل في حقل Link الرابط https://api-m.sandbox.paypal.com/v1/oauth2/token.
• اختر في حقل Return الخيار "Object JSON".
• اختر "Use Authentication".
• في حقل "Username" أدخل معرف العميل الخاص بك، وفي حقل "Password" أدخل السر الخاص بك لـ PayPal.

هذا الطلب مطلوب للحصول على "access_token".

يمكنك معرفة المزيد عن المصادقة في وثائق PayPal

يمكنك معرفة المزيد عن وحدة http request هنا.

3.3. قم بتعيين المعلمات لإنشاء رابط الدفع

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

في هذا المثال، يتم تشكيل طلب لإنشاء رابط الدفع بناءً على البيانات من العقد السابقة.

// access_token لـ PayPal، الذي تم الحصول عليه في العقدة "paypal auth"
const accessToken = msg.payload.access_token
// بيانات الطلب، التي تم الحصول عليها في العقدة "تم إنشاء الطلب"
// كائن الطلب يتوافق مع الطلب من واجهة برمجة التطبيقات orders https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// معرف جلسة الدفع، الذي تم الحصول عليه في العقدة "إنشاء جلسة الدفع"
const paymentSessionId = msg.paymentSessionId

// تشكيل البيانات لـ PayPal بناءً على بيانات الطلب
const items = order.products.map((product) => {
    return {
        name: product.title,
        description: 'وصفك',
        quantity: String(product.quantity),
        unit_amount: {
            currency_code: order.currency,
            value: product.price,
        },
    }
})

const totalSum = parseFloat(order.totalSum)

const data = {
    intent: 'CAPTURE',
    purchase_units: [
        {
            items,
            custom_id: String(paymentSessionId),
            amount: {
                currency_code: order.currency,
                value: totalSum,
                breakdown: {
                    item_total: {
                        currency_code: order.currency,
                        value: totalSum,
                    },
                },
            },
            payment_instruction: {
                billingId: String(order.id),
            },
        },
    ],
    payment_source: {
        paypal: {
            experience_context: {
                payment_method_preference: 'UNRESTRICTED',
                payment_method_selected: 'PAYPAL',
                brand_name: 'EXAMPLE INC',
                locale: 'en-US',
                landing_page: 'LOGIN',
                shipping_preference: 'NO_SHIPPING',
                user_action: 'PAY_NOW',
                return_url: 'https://example.com/return',
                cancel_url: 'https://example.com/cancel',
            },
        },
    },
}

// جسم الطلب
msg.payload = data
// رؤوس الطلب
msg.headers = {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
    Prefer: 'return=representation',
}

return msg

يمكنك معرفة المزيد في وثائق PayPal

يمكنك معرفة المزيد عن وحدة Function هنا.

4. إنشاء رابط الدفع

في هذا المثال، يتم استخدام العقدة "http request". يمكن استخدامها لإجراء طلبات http.

• اسحب العقدة "http request" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر في حقل Method الخيار "POST".
• اختر في حقل Data الخيار "Send as request body".
• أدخل في حقل Link الرابط https://api-m.sandbox.paypal.com/v2/checkout/orders.
• اختر في حقل Return الخيار "Object JSON".

في هذا المثال، قمنا بإجراء طلب إلى PayPal لتشكيل رابط الدفع باستخدام البيانات من العقد السابقة.

يمكنك معرفة المزيد في وثائق PayPal

يمكنك معرفة المزيد عن وحدة http request هنا.

5. تحديث جلسة الدفع

• اسحب العقدة "admin-api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "تحديث جلسة الدفع".
• أدخل الكود من الوصف أدناه في حقل "Query parameters".

{
  "id": {{paymentSessionId}}
}

• أدخل الكود من الوصف أدناه في حقل "Request body".

{
  "paymentUrl": "{{{payload.links.1.href}}}"
}

هنا نستخرج معرف رابط الدفع "msg.paymentSessionId" ورابط الدفع "msg.payload.links[0].href" من الطلبات السابقة.

يمكنك معرفة المزيد عن القيم المعادة في وثائق PayPal

يمكنك معرفة المزيد عن وحدة admin-api هنا.

6. إضافة نقطة نهاية للحصول على رابط الدفع

6.1. قم بتعيين الموضوع "createPaymentLink"

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هذا ضروري لتحديد تدفق العمل الحالي.

msg.topic = 'createPaymentLink'

return msg

يمكنك معرفة المزيد عن وحدة Function هنا.

6.2. أنشئ نقطة نهاية للحصول على رابط الدفع

• اسحب العقدة "http in" إلى مساحة العمل.
• اختر الطريقة "POST".
• أدخل الرابط /get-payment-link.

تحتاج هذه النقطة النهائية للحصول على رابط الدفع الحالي.

يمكنك معرفة المزيد عن وحدة http in هنا.

6.3. قم بتعيين الموضوع "getPaymentLink"

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هذا ضروري لتحديد تدفق العمل الحالي.

msg.topic = 'getPaymentLink'

return msg

يمكنك معرفة المزيد عن وحدة Function هنا.

6.4. احفظ البيانات في السياق

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هذا ضروري لتشكيل الاستجابة.

// احصل على معرف الطلب الحالي
const orderId = msg.payload.orderId
// مفتاح السياق الحالي
const contextKey = `payment_link_${orderId}`
// احصل على واجهة برمجة التطبيقات OneEntry
const api = global.get('api')
// بيانات السياق الحالية
const contextData = flow.get(contextKey) || {}
// تعيين البيانات إلى السياق حسب الموضوع
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// تعيين بيانات السياق إلى السياق
flow.set(contextKey, contextData)
// إذا اكتمل createPaymentLink و getPaymentLink، أرسل الاستجابة مع الجلسة الحالية
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // احصل على جلسة الدفع حسب المعرف من واجهة برمجة التطبيقات
    const paymentSession = await api.getPaymentSessionById({
        id: contextData.paymentSessionId,
    })
    msg.payload = paymentSession
    msg.res = contextData.res

    // امسح واجهة برمجة التطبيقات
    flow.set(contextKey, null)

    return msg
}

return null

يمكنك معرفة المزيد عن وحدة Function هنا.

6.5. نقطة الخروج لرابط الدفع

• اسحب العقدة "http response" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.

هذا ضروري لإخراج الاستجابة على الطلب.

يمكنك معرفة المزيد عن وحدة http response هنا.

7. إعداد الويب هوكس لـ PayPal

7.1. نقطة الدخول لـ PayPal

• اسحب العقدة "http in" إلى مساحة العمل.
• اختر الطريقة "POST".
• أدخل الرابط /paypal.

تحتاج هذه النقطة النهائية لتحديث حالة الدفع عبر PayPal.

يمكنك معرفة المزيد عن وحدة http in هنا.

7.2. الاستجابة على الطلب

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

هذا ضروري لتشكيل الاستجابة.

msg.payload = {
    ok: true,
}

return msg

يمكنك معرفة المزيد عن وحدة function هنا.

7.3. نقطة الخروج لـ PayPal

• اسحب العقدة "http response" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.

تحتاج هذه العقدة لإخراج الاستجابة على الطلب.

يمكنك معرفة المزيد عن وحدة http response هنا.

7.4. الحصول على حالة الدفع

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

في هذه العقدة، نأخذ القيمة المستلمة من العقدة "paypal webhook" ونكتبها في "msg.status" لاستخدامها في العقدة التالية.

msg.status = msg.payload.resource.status

return msg

يمكنك معرفة المزيد عن وحدة Function هنا.

7.5. التحقق من حالة الدفع

• اسحب العقدة "switch" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• في "Property" اكتب القيمة "status".
• أضف القاعدة الأولى للتحقق. اختر الشرط "=="، وأدخل القيمة "APPROVED".
• أضف القاعدة الثانية للتحقق. اختر الشرط "else".

ستتحقق هذه العقدة من القيمة في "msg.status" وفقًا للقواعد المحددة. إذا كانت القيمة تساوي "APPROVED"، فسيتم تنفيذ العقد من الفرع الأول، وإلا من الفرع الثاني.

يمكنك معرفة المزيد عن وحدة switch هنا.

7.6. الحصول على معرف جلسة الدفع

• اسحب العقدة "function" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• أدخل الكود من المثال في حقل "Function".

في هذه العقدة، نأخذ معرف جلسة الدفع الذي حفظناه في العقدة "تعيين بيانات الدفع".

msg.paymentSessionId = parseInt(
    msg.payload.resource.purchase_units[0].custom_id,
    10
)

return msg

يمكنك معرفة المزيد عن القيم المعادة في وثائق PayPal

يمكنك معرفة المزيد عن وحدة Function هنا.

7.7. تحديث حالة الدفع

• اسحب العقدة "admin-api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "تحديث جلسة الدفع".
• أدخل الكود من الوصف أدناه في حقل "Query parameters".

{
    "id": {{paymentSessionId}}
}

• أدخل الكود من الوصف أدناه في حقل "Request body".

{
    "status": "completed"
}

هنا نقوم بتحديث حالة الدفع بناءً على معرفه من "msg.paymentSessionId".

يمكنك معرفة المزيد عن وحدة admin-api هنا.

7.8. أضف webhook في لوحة تحكم PayPal

الرابط إلى مشروعك + /api/admin/workflows/endpoints/paypal

مثال:

https://<مشروعك>.oneentry.cloud/api/admin/workflows/endpoints/paypal

يمكنك معرفة المزيد في وثائق PayPal

8. التحقق من التكامل

8.1. أنشئ طلبًا

تم وصف كيفية إنشاء طلب في وثائق API

8.2. احصل على رابط الدفع

• قم بإجراء طلب POST إلى https://<مشروعك>.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link، بدلاً من https://<مشروعك>.oneentry.cloud، أدخل الرابط إلى مشروعك.

• في جسم الطلب، أدخل معرف الطلب الذي تم إنشاؤه سابقًا:

{
    "orderId": 15
}

8.3. ادفع الطلب

8.4. تحقق من حالة الطلب