استخدام Meta Pay API

عند معالجة مدفوعات Meta Pay، يجب عليك إرسال إشعار إلى Meta بشأن نشاط معاملات الدفع، مثل التصاريح وعمليات استرداد الأموال، من خلال استدعاء أحداث webhooks في Meta Pay API> يظهر نشاط معاملات الدفع في صفحة الطلبات وعمليات الدفع لحساب العميل على فيسبوك.

للتعرف على كيفية استخدام واجهات API من Meta، راجع نظرة عامة على Graph API ولاحظ أن واجهات API الموضحة أدناه مرتبطة بـ عنوان URL القياسي لمضيف Graph API (https://graph.facebook.com). لمزيد من المعلومات العامة، راجع نظرة عامة على دمج Meta Pay.

التأهيل

قبل أن تتمكن من البدء في استخدام واجهات Meta Pay API، يجب إكمال ما يلي:

• إكمال خطوات التأهيل العامة
• مراجعة معالجة عملية الدفع في Meta Pay

استدعاء واجهات Meta Pay API

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

يتطلب كل استدعاء تقوم به إلى واجهة Meta Pay API رمز وصول تطبيق مشتق من معرف التطبيق والمفتاح السري للتطبيق. أرسل رمز وصول التطبيق باستخدام العنوان Authorization وليس معلمة الاستعلام access_token. ترفض واجهات Meta Pay API الاستدعاءات التي تحتوي على رموز المستخدم.

على سبيل المثال، استخدم الرمز التالي:

Authorization: OAuth <APP_ACCESS_TOKEN>

التوقيع

يجب أن يتضمن كل طلب HTTP لواجهات Meta Pay API عنوان طلب FBPAY_SIGNATURE. قيمة هذا العنوان هي كائن JSON Web Signature (JWS) بخوارزمية ES256 والتسلسل المدمج وحمولة البيانات المنفصلة (وفقًا لـ https://tools.ietf.org/html/rfc7515#appendix-F). قيمة حمولة البيانات هي نص الطلب HTTP POST. يجب تحديد مفتاح توقيع JWS بعنوان x5c، الذي يجب أن يحتوي على شهادة مرتبطة بجذر الشريك الموثوق به. تتم مشاركة شهادة الجذر الخاصة بالشريك مع Meta كجزء من عملية التأهيل (المشار إليها باسم شهادة توقيع Meta Pay API).

مثال على طلب يتضمن توقيعًا

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY_SIGNATURE: eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCaERDQ0FTcWdBd0lCQWdJQkFUQUtCZ2dxaGtqT1BRUURBakFoTVI4d0hRWURWUVFEREJad1lYSjBibVZ5SUhOcFoyNWhkSFZ5WlNCalpYSjBNQjRYRFRJd01EY3hNekl5TWpVek1Gb1hEVEkwTURNeE1USXlNalV6TUZvd0lURWZNQjBHQTFVRUF3d1djR0Z5ZEc1bGNpQnphV2R1WVhSMWNtVWdZMlZ5ZERCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFuRngwR1NKMklPZGZpcFdiMGMwZytBVThlbDh6QnRVS0kxdWRzT2kzN2thd1JRSFkzV29YaWRvRThIOHM1cVIySmo2ZkFKWVhOTURXY0NiditWMEJ1alV6QlJNQjBHQTFVZERnUVdCQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QVBCZ05WSFJNQkFmOEVCVEFEQVFIXC9NQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJUUNBRE9zZ0pZanRXVm9xNUZOSjc3U2JDeWtON1ZldUlKR2pXb3NBVUFNd1ZRSWdUTlVcL2ttc1wvN0cxVUx5Z01DRWVXemNiYTNrMVo4NEE4RmNlMXQzYUNGbGc9Il19..ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" "https://graph.facebook.com/1001200005002/notify_authorizations" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"notify_authorizations"},"resource":{"partner_auth_id":"1234567890","auth_amount":{"currency":"USD","value":29508},"status":"SUCCEEDED","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

يعمل الطلب السابق على تشفير البيانات التالية:

{
  "notification": {
    "partner_merchant_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x",
    "event_time": 1582230020020,
    "type": "notify_authorizations"
  },
  "resource": {
    "partner_auth_id": "1234567890",
    "auth_amount": {
      "currency": "USD",
      "value": 29508
    },
    "status": "SUCCEEDED",
    "created_time": 1582230019010,
    "metadata": []
  },
  "idempotence_token": "ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"
}

فيما يلي التوقيع من الطلب السابق، تم فك تشفير Base64 وJSON للتوضيح:

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" // Signature

فحص الاستخدام لمرة واحدة

يتم استخدام الحقل idempotence_token لتجنب التنفيذ المتكرر للطلبات عند إعادة محاولة إرسال الطلبات بعد حالات فشل الشبكة أو حالات انتهاء المهلة. رمز idempotence هو قيمة فريدة يتم إنشاؤها من خلال البرنامج ويحدد البرنامج كيفية إنشاء هذا الرمز. على سبيل المثال، يمكنك استخدام V4 UUID لإنشاء رمز idempotence.

عند إكمال الطلب بنجاح، أو عندما يُرجع استدعاء API نتائج صالحة، يتم حفظ بيانات الاستجابة برمز idempotence. عندما تتم إعادة محاولة إرسال طلب ناجح من خلال رمز idempotency تم استخدامه مؤخرًا، يتم عرض الاستجابة المحفوظة مسبقًا دون إعادة تشغيل أي رمز.

عندما يتسبب طلب ما في ظهور خطأ، لا يتم حفظ أي نتائج. يمكنك إعادة محاولة الطلب واستخدام رمز idempotency ذاته.

إذا قمت بإجراء طلبين في الوقت ذاته باستخدام رمز idempotency نفسه، فسيتم إرجاع بيانات الاستجابة لطلب واحد فقط.

تكون رموز Idempotency مؤقتة وتستخدم فقط لإعادة استدعاءات API في حالة الفشل. وإذا حاولت إعادة إرسال طلب ما بعد مرور بعض الوقت، فقد تتلقى استجابة مختلفة عن الاستدعاء السابق.

يتم تجاهل معلمات الطلب. إذا كنت تحاول تغيير محتوى الطلب بأي شكل، فيمكنك إنشاء رمز idempotence جديد للطلب.

التسوية المجمعة

عند معالجة عمليات الدفع، يجب إرسال إشعار إلى Meta بشأن نشاط معاملة الدفع من خلال استخدام أحداث webhooks لـ Meta Pay. من خلال استدعاء أحداث webhooks، يظهر نشاط معاملة الدفع في صفحة نشاط Facebook Pay لحساب العميل على فيسبوك في أقرب وقت ممكن.

يتم تسجيل الإشعارات التي تفشل بواسطة Meta أثناء التسوية المجمعة وتظهر في حساب العميل على فيسبوك لاحقًا.

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

معالجة الأخطاء

تستخدم واجهات Meta Pay API نظامًا قياسيًا في Graph API لمعالجة الأخطاء.

تهيئة بيانات التجار وتحديثها

لتهيئة بيانات التاجر الذي تدعمه أو تحديثها، أرسل طلب POST إلى /metapay_partner/merchant في Graph API لدى التاجر وحدد معلمات التاجر.

https://graph.facebook.com/metapay_partner/merchant

معلمات الطلبات

الاستجابة

بعد إجراء طلب POST إلى API التاجر، ستشير استجابة 200 OK إلى نجاح معالجة طلب POST. يشير نص الاستجابة إلى حالة التاجر، ما إذا كانت ENABLED أو DISABLED. توفر معدّلات الحالة غير الفارغة معلومات إضافية.

تبدو الاستجابة الناجحة الشائعة على النحو التالي:

{
    "status":"ENABLED",
    "status_modifiers":[]
}

تبدو استجابة التاجر الذي يخضع لفحص مؤقت على النحو التالي:

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

فيما يلي معدّلات الحالة المحتملة.

الحصول على التجار

للحصول على قائمة بالتجار المسجلين، أرسل طلب GET إلى /metapay_partner/merchants في Graph API لدى التاجر.

https://graph.facebook.com/metapay_partner/merchants

معلمات الطلبات

يتم دعم معلمات الطلب الاختيارية التالية كمعلمات عنوان URL:

الاستجابة

تكون النتائج الواردة من استجابة GET في API التجار مقسمة إلى صفحات. راجع الصفحة المرتبطة للحصول على تنسيق الاستجابة العامة. سيكون كل عنصر يتم إرجاعه في مصفوفة data بتنسيق معلمات طلب التاجر. مثال:

curl -H "Authorization: OAuth $OAUTH" -X GET "https://graph.facebook.com/metapay_partner/merchants?partner_merchant_id=MERCHANT_TEST_1"
{
    "data": [
        {
            "partner_merchant_id": "MERCHANT_TEST_1",
            "merchant_status": "DISABLED",
            "display_name": "Test merchant 1",
            "business_uri": "https://facebook.com/",
            "icon_uri": "https://facebook.com/favicon.ico",
            "mcc_list": [7311],
            "support_email": "example@facebook.com",
            "support_phone": "+11234567890",
            "valid_origins": [
                "https://facebook.com/"
            ],
            "legal_structure": "COMPANY_TYPE_NOT_SPECIFIED",
            "status_modifiers":["BLOCKED"],
            "effective_merchant_status":"DISABLED"
        }
    ],
    "paging": {
        "cursors": {
            "before": "aaa...",
            "after": "bbb..."
        },
        "next": "https://graph.facebook.com/metapay_partner/merchants?limit=25&after=..."
    }
}

Webhooks

يجب إرسال إشعار إلى Meta بنشاط معاملة الدفع من خلال استدعاء أحداث Webhooks في Meta عند حدوث أي عمليات تصريح أو تسجيل أو نزاع أو دفع أو استرداد أموال.

تشير استجابة 200 OK إلى أنه تمت معالجة حدث webhook بنجاح. سيُرجع نص الاستجابة الناجح container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

إذا فشل استدعاء webhook، فأعد محاولة الاستدعاء ثلاث مرات على الأقل لمدة لا تقل عن اثنتين وسبعين ساعة مع تراجع الفترات تدريجيًا. إذا استمر الاستدعاء في الفشل، فيمكن تسجيل الإشعار لاحقًا أثناء التسوية المجمعة.

فيما يلي رسم تخطيطي لعلاقة الكيان للموارد التي تم تصميمها في أحداث webhooks لواجهة Meta API. تشير الخصائص ذات النقاط السوداء إلى السمات الإلزامية.

الإشعار

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

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

معلمة الإشعار

إرسال إشعار بعمليات التصريح

أرسل طلب POST إلى /<CONTAINER_ID>/notify_authorizations لإرسال إشعار إلى Meta حول نشاط التصريح لمعاملة دفع.

https://graph.facebook.com/<CONTAINER_ID>/notify_authorizations

مصدر التصريح

إرسال إشعار بعمليات التسجيل

أرسل طلب POST إلى /<CONTAINER_ID>/notify_captures لإرسال إشعار إلى Meta حول نشاط التسجيل المرتبط بمعاملة الدفع.

https://graph.facebook.com/<CONTAINER_ID>/notify_captures

مصدر التسجيل

إرسال إشعار بعمليات النزاع

أرسل طلب POST إلى /<CONTAINER_ID>/notify_disputes لإرسال إشعار إلى Meta حول نشاط النزاع المرتبط بمعاملة الدفع.

https://graph.facebook.com/<CONTAINER_ID>/notify_disputes

مصدر النزاع

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

أرسل طلب POST إلى /<CONTAINER_ID>/notify_payments لإرسال إشعار إلى Meta حول نشاط الدفع الذي لا يتعلق بعمليات تحويل الأموال. على سبيل المثال، قد تقرر عدم معالجة مدفوعات المستخدم عندما تفشل في اجتياز عمليات التحقق من المخاطر.

https://graph.facebook.com/<CONTAINER_ID>/notify_payments

مصدر الدفع

إرسال إشعار بعمليات استرداد الأموال

أرسل طلب POST إلى /<CONTAINER_ID>/notify_refunds لإرسال إشعار إلى Meta حول نشاط استرداد الأموال المرتبط بمعاملة الدفع.

https://graph.facebook.com/<CONTAINER_ID>/notify_refunds

مصدر استرداد الأموال

كائن كمية الإشعار

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

كائن الكمية

كائن خطأ الإشعار

إذا حدث خطأ أثناء معالجة عملية تصريح أو تسجيل أو دفع أو استرداد أموال، فقم بتضمين كائن error في resource لتوفير معلومات حول الخطأ.

كائن الخطأ