فئة PaymentClient

نقطة الإدخال للتفاعل مع Meta Pay.

أمثلة

فيما يلي مثال على كيفية الاستخدام PaymentClient.

أولاً أنشئ طلب دفع. يحتوي PaymentRequest على تفاصيل الدفع التي يجب أن تظهر للعميل والخيارات والتكوينات اللازمة لإنشاء استجابة دفع لشريك الدفع لمعالجة المعاملة.

function buildPaymentRequest(): PaymentRequest 
{
  return
  {
    paymentDetails:
    {
     total: {label: 'Board Game', amount: {value: '19.99', currency: 'USD'}},
    },
    paymentOptions:
    {
      requestPayerName: true,
      requestPayerEmail: false,
      requestPayerPhone: false,
      requestShipping: false,
      allowOfferCodes: false
    },
    paymentConfiguration:
    {
      mode: 'TEST',
      partnerId: 'TEST_PARTNER_ID',
      partnerMerchantId: '<your merchant id>',
      acquirerCountryCode: 'US',
      supportedContainers: {
        'basic-card-v1': {}, // no configurations, use {}
      },
      containerContext: '<a unique identifier for the payment>',
    },
  };
}

ثانيًا، أنشئ PaymentClient وحدّد ما إذا كان Meta Pay متوفرًا في بيئة المتصفح الذي يستخدمه عميلك. وإذا كان Meta Pay متوفرًا، فاعرض زر Meta Pay وأرفق طريقة الاستدعاء عندما ينقر العميل على الزر.

const paymentClient = new window.metapay.PaymentClient('1.0');

window.onload = async function ()
{
  const availability = await paymentClient.getAvailability();
  
  if (availability === 'AVAILABLE')
  {
    // display the Meta Pay button
    await paymentClient.renderButton
    (
      '#btn_container',
      buildPaymentRequest,
      responsePromise => onMetaPayClick(responsePromise),
      {theme: 'light'}
    );

    async function onMetaPayClick(responsePromise)
    {
      const response = await responsePromise;

      try
      {
        // process payment by sending response.container to partner
        // ...

        // dismiss the Meta Pay interface with a successful signal
        await response.complete(PaymentComplete.success);
      }
      catch (err)
      {
        // error handling
        // ...
  
        // dismiss the Meta Pay interface with a failure signal
        await response.complete(PaymentComplete.fail);
      }

      // more code
      // ...
    };
  }
  else
  {
    console.log('Meta Pay is not available');
  }
};

دفق إتمام الشراء الاستباقي

في بعض السياقات على سبيل المثال، عندما يقوم مستخدم لديه طريقة دفع موجودة في الملف بالدخول إلى صفحة إتمام الشراء ضمن مجموعة تطبيقات Meta، على سبيل المثال: فيسبوك أو Instagram، يمكن لمجموعة SDK بدء تجربة إتمام شراء أكثر سلاسة بشكل استباقي. يوضح الرسم البياني التالي طريقة عمل الأمر:

في بعض سياقات المستخدم، يُعد بدء إتمام الشراء عند تحميل الصفحة ليس تجربة المستخدم المناسبة، على سبيل المثال، إذا كان المستخدم موجودًا في صفحة تفاصيل المنتج في وجود زر "الشراء من خلال MetaPay"، فهو لم يعرب بعد عن نيته في الشراء. تعامل مع هذه السيناريوهات عدم إتمام الشراء هذه من خلال تعيين خاصية uxFlags لكائن PaymentConfiguration على سبيل المثال paymentConfig.uxFlags = ['DISABLE_PROACTIVE_CHECKOUT']

جهات الإنشاء

PaymentClient(clientVersion: string): PaymentClient

تنشئ PaymentClient.

الأساليب

getAvailability

getAvailability(paymentConfig: PaymentConfiguration): Promise<string>

قبل عرض زر Meta Pay على موقعك، استدع getAvailability لتحديد ما إذا كان Meta Pay متوفرًا في بيئة المتصفح الذي يستخدمه العميل أم لا. وتضمن لك عملية التحقق هذه عرض تجربة Meta Pay فقط حيث يتم دعمها. إذا كانت خدمة Meta Pay متوفرة، فأعرض زر Meta Pay.

يعمل هذا الأسلوب على إرجاع Availability أو PaymentError.

renderButton

renderButton(container: string, providePaymentRequest: () => PaymentRequest, onResponse: (responsePromise: Promise<PaymentResponse>) => void, _options?: ThemeOptions): Promise<void>

بعد التحقق من توّفر خدمة Meta Pay، استخدم هذه الطريقة لعرض زر Meta Pay في صفحة الويب. سيتم تصميم الزر باستخدام الأنماط وموارد CDN حسب المعلمة _options. سيقوم هذا الأسلوب بإرفاق عناصر تسجيل لمرات النقر والتحميل لدعم تشغيل صفحة الدفع من خلال Meta Pay عندما ينقر المستخدم على الزر باستخدام paymentRequest المتوفر في هذا الأسلوب. بعد أن يكمل المستخدم التفاعل مع صفحة الدفع، سيتم استدعاء طلب onResponse مع استجابة الدفع.

بالإضافة إلى ذلك، يمكن استخدام وظيفة PaymentRequest التي يتم إرجاعها من providePaymentRequest وonResponse لبدء عرض صفحة الدفع تلقائيًا لإنشاء تجربة إتمام شراء أكثر سلاسة لمستخدمي Meta Pay المؤهلين.

للرد على تفاعلات المستخدمين أثناء فتح صفحة الدفع، يرجى تعيين معالجات الأحداث onPaymentDetailsChanged وonPaymentConsent على مثيل PaymentClient.

[تم إيقاف الاستخدام] preparePaymentSheet

preparePaymentSheet(paymentConfig: PaymentConfiguration): Promise<PaymentSheetStatus>

استخدم هذا الأسلوب لإعداد صفحة دفع Meta Pay. قم باستدعاء هذا الأسلوب استجابةً لأي إجراء من جانب العميل، مثل نقرة الزر، بحيث يمكن لصفحة الدفع إنشاء مكونات واجهة المستخدم مثل نافذة منبثقة.

بعد استدعاء preparePaymentSheet، قم باستدعاء getPaymentResponse لتوفير تفاصيل طلب الدفع.

إذا قمت باستدعاء getPaymentResponse بدون استدعاء preparePaymentSheet أولاً، فستحاول مجموعة SDK بدء صفحة الدفع. ولكن، قد تفشل getPaymentResponse إذا لم يكن هناك أي إجراء من جانب العميل أولاً.

يرجع هذا الأسلوب PaymentSheetStatus أو PaymentError.

getPaymentResponse

getPaymentResponse(request: PaymentRequest): Promise<PaymentResponse>

يعمل هذا الأسلوب على إنشاء واجهة Meta Pay. يمكن للعميل تحديد طريقة الدفع وتوفير معلومات، مثل الاسم ومعلومات الشحن إذا كانت مطلوبة في PaymentOptions للطلب.

يعمل هذا الأسلوب على إرجاع PaymentResponse.

attemptProactivePayment

attemptProactivePayment(request: PaymentRequest): Promise<PaymentResponse>

تمامًا كما هو الحال في getPaymentResponse، يعمل هذا الأسلوب على إنشاء تجربة Meta Pay. ولكن، يمكنك استدعاء هذا الأسلوب عندما تعرض زر Meta Pay. بالنسبة للمنصات المدعومة، يمكن أن يوفر ذلك تجربة إتمام شراء أكثر بساطة للعملاء.

يعمل هذا الأسلوب على إرجاع Promise<PaymentResponse>. إذا لم يكن إتمام الشراء الاستباقي مدعومًا، فسيتم رفض الالتزام مع عرض خطأ.

الأحداث

onPaymentConsent

معالج أحداث اختياري يتيح للتاجر محاولة إجراء تصريح الدفع قبل إغلاق صفحة الدفع.

عند استخدام معالج الأحداث هذا، تنتظر واجهة صفحة الدفع حتى يتم حل الطلب الذي تم إرجاعه من المعالج. وإذا قام الحدث بإرجاع PaymentAuthorizationResult بالحالة authorizationState لـ ERROR، فستظهر الرسالة للعميل ويمكن للعميل اختيار تحديث طريقة الدفع أو تغييرها.

مثال على onPaymentConsent

// before you call paymentClient.renderButton() attach a consent handler
paymentClient.onPaymentConsent = paymentConsentHandler;

async function paymentConsentHandler(paymentResponse)
{
  try
  {
    console.log('payment response received');

    // submit paymentResponse to payment processor for authorization
    return Promise.resolve({authorizationState: 'SUCCESS'});
  }
  catch (error)
  {
    return Promise.reject
    ({
       authorizationState: 'ERROR',
       error:
       {
         reason: 'INVALID_PAYMENT_DATA',
         message: 'We were unable to process payment. Please try again with a different card.'
       },
    });
  }
}

onPaymentDetailsChanged

معالج حدث اختياري يسمح للتاجر بتحديث FBPaymentRequest الأولي استجابةً للتغييرات التي يجريها العميل في صفحة الدفع. يمكن استخدامه أيضًا لعرض الأخطاء على العميل في حال تسببت أي تغييرات في اعتبار المعاملة باطلة من قبل التاجر. هذا الاستدعاء مسؤول عن تحديث paymentDetails.total و/أو paymentDetails.summaryItems استجابة لتغييرات العملاء في الصفحة. يجب تنفيذ الاستدعاء عند تقديم طلب الدفع الأولي بالسيناريوهات التالية:

• paymentOptions.requestShipping بالقيمة true
• paymentOptions.shippingType بالقيمة PICKUP
• paymentOptions.requestBilling بالقيمة true ويجب إعادة حساب القيم الضريبية للمبلغ الإجمالي.
• paymentOptions.allowOfferCodes بالقيمة true. يجب على المعالج تعديل القيم الإجمالية والملخصة لتتوافق مع التغييرات المرتبطة برمز العرض الذي حدده العميل.

يجب أن يرجع الاستدعاء Promise<PaymentDetailsUpdate>.

مثال على onPaymentDetailsChanged

// before you call paymentClient.renderButton() attach a handler
paymentClient.onPaymentDetailsChanged = paymentDetailsChangedHandler;

async function paymentDetailsChangedHandler(event)
{	
  // Create an PaymentDetailsUpdate object
  let update = {
  	paymentDetails: event.paymentDetails,
  	errors: [],
  }
  if (event.changeTypes.length != 0) {
  	// Modify the FBPaymentDetailsUpdate object based on 
  	// the incoming FBPaymentDetailsChangedEvent
  	// ...
  }
  
  return Promise.resolve(update);
}

راجع أيضًا

• نظرة عامة حول دمج Meta Pay
• مجموعة JavaScript SDK في Meta Pay