مثال интеграции с PayPal

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

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

1.1. حدث "order created" في وحدة "Events".

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

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

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

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

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

يمكنك معرفة المزيد عن عقدة Events هنا.

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

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

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

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

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

• اسحب العقدة "api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "Create Payment Session" والصق الكود من الوصف أدناه في حقل "Data".

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

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

يمكنك معرفة المزيد عن عقدة 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
// بيانات الطلب، التي تم الحصول عليها في العقدة "order created"
// الكائن order يتوافق مع الطلب من واجهة برمجة التطبيقات orders https://oneentry.ru/instructions/api
const order = msg.orderEvent.order
// معرف جلسة الدفع، الذي تم الحصول عليه في العقدة "create payment session"
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. تحديث جلسة الدفع

• اسحب العقدة "api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "Update Payment Session" والصق الكود من الوصف أدناه في حقل "Data".

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

{ "id": {{paymentSessionId}}, "paymentUrl": "{{{payload.links.1.href}}}" }

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

يمكنك معرفة المزيد عن عقدة 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. تحقق من حالة الدفع

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

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

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

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

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

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

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

return msg

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

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

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

• اسحب العقدة "api" إلى مساحة العمل وقم بتوصيلها بالعقدة من الخطوة السابقة.
• اختر طريقة "Update Payment Session" والصق الكود من الوصف أدناه في حقل "Data".

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

{ "id": {{paymentSessionId}}, "status": "completed" }

يمكنك معرفة المزيد عن عقدة api هنا.

7. أضف webhook في لوحة التحكم الخاصة بـ PayPal

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

مثال:

https://integrations-study.oneentry.ru/api/admin/workflows/endpoints/paypal

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

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

8.1. أنشئ طلبًا

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

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

• قم بإجراء طلب POST إلى https://integrations-study.oneentry.ru/api/admin/workflows/endpoints/get-payment-link، بدلاً من https://integrations-study.oneentry.ru، ضع رابط مشروعك.

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

{
    "orderId": 15
}

8.3. ادفع الطلب

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