كيفية استخدام واجهات برمجة تطبيقات Braintree؟

تلخيص

تعالج واجهات برمجة تطبيقات Braintree المدفوعات من بطاقات الائتمان، PayPal، Venmo، والمحافظ الرقمية. يمكنك التكامل عبر حزم SDKs من جانب الخادم (Node, Python, Ruby, إلخ)، وإنشاء رموز عميل لأمان الواجهة الأمامية، والتعامل مع المعاملات، والمبالغ المستردة، والاشتراكات. للاختبار، استخدم Apidog للتحقق من حمولات webhook واختبار التكامل الخاص بك مقابل بيانات البيئة التجريبية قبل الإطلاق الفعلي.

مقدمة

تعالج Braintree مليارات الدولارات من المدفوعات سنويًا. إنها معالج الدفع الذي يقف وراء شركات مثل Uber و Airbnb و GitHub. تدعم المنصة بطاقات الائتمان، PayPal، Venmo، Apple Pay، Google Pay، وتحويلات ACH.

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

تقدم Braintree مسارين للتكامل: واجهة المستخدم الجاهزة (Drop-in UI) (نموذج دفع مُجهز مسبقًا) وواجهة المستخدم المخصصة (Custom UI) (تحكم كامل). يستخدم كلاهما نفس واجهات برمجة تطبيقات جانب الخادم لمعالجة الدفع الفعلية. يغطي هذا الدليل العمل الذي يتم على جانب الخادم بعد أن ينقر العميل على "ادفع".

اختبر ويب هوك Braintree باستخدام Apidog - مجانًا

إعداد Braintree

إنشاء حساب Braintree

اذهب إلى braintreepayments.com (Braintree هي الآن PayPal Enterprise Payments) وأنشئ حسابًا تجريبيًا (sandbox account). ستحصل على:

• معرف التاجر (Merchant ID): abc123xyz
• المفتاح العام (Public Key): def456...
• المفتاح الخاص (Private Key): ghi789...

خزّن هذه المعلومات بأمان. المفتاح الخاص يشبه كلمة المرور - لا تقم أبدًا بإضافته إلى Git.

تثبيت حزمة SDK

توفر Braintree حزم SDKs من جانب الخادم لمعظم اللغات:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

تهيئة البوابة:

const braintree = require('braintree')

const gateway = new braintree.BraintreeGateway({
  environment: braintree.Environment.Sandbox,
  merchantId: process.env.BRAINTREE_MERCHANT_ID,
  publicKey: process.env.BRAINTREE_PUBLIC_KEY,
  privateKey: process.env.BRAINTREE_PRIVATE_KEY
})

إنشاء رمز مميز للعميل (Client Token)

قبل عرض نموذج الدفع، قم بإنشاء رمز مميز للعميل. هذا يسمح للواجهة الأمامية بالتواصل مع Braintree.

app.get('/checkout/token', async (req, res) => {
  const clientToken = await gateway.clientToken.generate()
  res.json({ clientToken: clientToken.clientToken })
})

تستخدم الواجهة الأمامية هذا الرمز المميز لتهيئة واجهة المستخدم الجاهزة (Drop-in UI) أو التكامل المخصص.

معالجة المدفوعات

سير عملية الدفع

1. الواجهة الأمامية ترسل رمز الدفع (payment method nonce) إلى الخادم الخاص بك
2. الخادم ينشئ معاملة باستخدام الرمز (nonce)
3. Braintree تعالج الدفع
4. الخادم يستقبل استجابة النجاح/الفشل
5. تقوم بتنفيذ الطلب أو عرض خطأ

خصم من بطاقة ائتمان

app.post('/checkout', async (req, res) => {
  const { paymentMethodNonce, amount, orderId } = req.body

  const result = await gateway.transaction.sale({
    amount: amount,
    paymentMethodNonce: paymentMethodNonce,
    orderId: orderId,
    options: {
      submitForSettlement: true
    }
  })

  if (result.success) {
    res.json({
      success: true,
      transactionId: result.transaction.id
    })
  } else {
    res.status(400).json({
      success: false,
      message: result.message
    })
  }
})

الخصم باستخدام طريقة دفع محفوظة

بعد المعاملة الأولى، يمكنك حفظ طريقة الدفع لاستخدامها مستقبلاً:

// إنشاء عميل بطريقة الدفع
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// تم حفظ طريقة الدفع
const paymentMethodToken = result.customer.paymentMethods[0].token

// خصم من طريقة الدفع المحفوظة لاحقاً
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

معاملات PayPal

تتعامل Braintree مع PayPal بنفس طريقة البطاقات. تحصل الواجهة الأمامية على رمز مميز (nonce) من PayPal، ثم تقوم بالخصم منه:

const result = await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: paypalNonce,
  orderId: 'ORDER-123',
  options: {
    submitForSettlement: true
  }
})

استرداد الأموال والإلغاءات

استرداد كامل للمبلغ

const result = await gateway.transaction.refund('transaction_id')

if (result.success) {
  console.log('تم الاسترداد:', result.transaction.id)
}

استرداد جزئي للمبلغ

const result = await gateway.transaction.refund('transaction_id', '50.00')

if (result.success) {
  console.log('تم معالجة استرداد جزئي')
}

إلغاء معاملة

الإلغاء (Void) يوقف المعاملة قبل تسويتها. استخدم هذا للمدفوعات المصرح بها ولكن لم يتم تحصيلها بعد:

const result = await gateway.transaction.void('transaction_id')

if (result.success) {
  console.log('تم إلغاء المعاملة')
}

سير حالة المعاملة

مُصرح بها ← مُقدمة للتسوية ← مُسواة
                    ↓
                   مُلغاة
                    
                  مُسواة ← مُستردة

الاشتراكات والفوترة المتكررة

تتولى Braintree معالجة الاشتراكات للمدفوعات المتكررة.

إنشاء خطة

أولاً، قم بإنشاء خطة في لوحة تحكم Braintree أو عبر API:

const result = await gateway.plan.create({
  id: 'monthly-premium',
  name: 'Monthly Premium',
  billingFrequency: 1,
  currencyIsoCode: 'USD',
  price: '29.99'
})

إنشاء اشتراك

const result = await gateway.subscription.create({
  paymentMethodToken: paymentMethodToken,
  planId: 'monthly-premium',
  firstBillingDate: new Date()
})

if (result.success) {
  console.log('تم إنشاء الاشتراك:', result.subscription.id)
}

إلغاء اشتراك

const result = await gateway.subscription.cancel('subscription_id')

if (result.success) {
  console.log('تم إلغاء الاشتراك')
}

تحديث الاشتراك

const result = await gateway.subscription.update('subscription_id', {
  planId: 'annual-premium',
  price: '299.99'
})

الويب هوك لأحداث الدفع

تقوم الويب هوك (webhooks) بإعلام الخادم الخاص بك بأحداث المعاملات. هذا أمر بالغ الأهمية للاشتراكات والنزاعات.

إنشاء نقطة نهاية للويب هوك

app.post('/webhooks/braintree', (req, res) => {
  const signature = req.body.bt_signature
  const payload = req.body.bt_payload

  // التحقق من الويب هوك وتحليله
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('ويب هوك غير صالح')
      }

      switch (webhookNotification.kind) {
        case 'subscription_charged_successfully':
          handleSuccessfulCharge(webhookNotification.subscription)
          break
        case 'subscription_charged_unsuccessfully':
          handleFailedCharge(webhookNotification.subscription)
          break
        case 'dispute_opened':
          handleDispute(webhookNotification.dispute)
          break
        case 'transaction_settled':
          handleSettledTransaction(webhookNotification.transaction)
          break
      }

      res.status(200).send('OK')
    }
  )
})

تسجيل الويب هوك في Braintree

في لوحة تحكم Braintree، اذهب إلى الإعدادات (Settings) ← الويب هوك (Webhooks) وأضف عنوان URL لنقطة النهاية الخاصة بك. في مرحلة التطوير، استخدم خدمة نفق (tunneling service) مثل ngrok لاستقبال الويب هوك محليًا.

الاختبار باستخدام Apidog

تحتاج واجهات برمجة تطبيقات الدفع إلى اختبار شامل. لا يمكنك الاعتماد على بيانات الإنتاج. يساعدك Apidog على الاختبار بدون مخاطر.

1. محاكاة حمولات الويب هوك

بدلاً من انتظار Braintree لإرسال الويب هوك، قم بإنشاء حمولات وهمية:

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}

أرسل هذه إلى نقطة نهاية الويب هوك الخاصة بك وتحقق من أن رمزك يتعامل معها بشكل صحيح.

2. فصل البيئات

أنشئ بيئات منفصلة:

# البيئة التجريبية (Sandbox)
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# الإنتاج (Production)
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production

3. التحقق من استجابات الويب هوك

pm.test('Webhook processed successfully', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('Transaction ID logged', () => {
  // تحقق من سجلاتك أو قاعدة بياناتك
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

اختبر ويب هوك Braintree باستخدام Apidog - مجانًا

الأخطاء الشائعة والإصلاحات

رفض المعالج

السبب: البنك رفض المعاملة.

الإصلاح: غالبًا ما يكون هذا بسبب عدم كفاية الأموال أو مرشحات الاحتيال. اعرض خطأً عامًا للعميل واقترح محاولة بطاقة مختلفة. سجل processorResponseCode لأغراض تصحيح الأخطاء.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // رفض البنك
    return res.status(400).json({
      error: 'رفض البنك هذه المعاملة. يرجى محاولة استخدام بطاقة مختلفة.'
    })
  }
}

رفض البوابة

السبب: مرشحات الاحتيال الخاصة بـ Braintree حظرت المعاملة.

الإصلاح: تحقق من gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // عدم تطابق CVV
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // فشل التحقق من العنوان
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // أدوات الاحتيال المتقدمة حظرتها
}

فشل التسوية

السبب: لم تتمكن المعاملة من التسوية بعد التفويض.

الإصلاح: راقب ويب هوك transaction_settlement_declined. الأسباب الشائعة:

• طريقة الدفع انتهت صلاحيتها بين التفويض والتسوية
• الجهة المصدرة للبطاقة حظرت المعاملة
• ظهر عدم كفاية الأموال

المعاملات المكررة

السبب: نقر العميل على "ادفع" مرتين أو قام رمزك بالمحاولة مرة أخرى.

الإصلاح: استخدم المعامل orderId. سترفض Braintree المعاملات المكررة ضمن فترة زمنية معينة:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // يمنع التكرارات
  options: {
    submitForSettlement: true
  }
})

بدائل ومقارنات

الميزة الرئيسية لـ Braintree هي الدعم الأصلي لـ PayPal و Venmo. إذا كنت بحاجة إلى معالجة البطاقات و PayPal معًا، فغالبًا ما يكون ذلك أبسط من استخدام Stripe + PayPal بشكل منفصل.

حالات استخدام واقعية

منصة اشتراكات SaaS. تستخدم أداة لإدارة المشاريع Braintree للاشتراكات الشهرية. تعالج الويب هوك المدفوعات الفاشلة (انتهاء صلاحية البطاقة، عدم كفاية الأموال) عن طريق إرسال إشعارات عبر البريد الإلكتروني. يقوم المستخدمون بتحديث طرق الدفع دون الحاجة إلى الاتصال بالدعم.

مدفوعات السوق (Marketplace). تقوم منصة للعمل الحر بتقسيم المدفوعات بين رسوم المنصة والمستقل. تتولى حسابات التجار وإعدادات التجار الفرعيين في Braintree التعامل مع التعقيد.

التجارة الإلكترونية مع PayPal. يقدم متجر عبر الإنترنت بطاقات الائتمان و PayPal. تعني واجهة برمجة التطبيقات الموحدة لـ Braintree أن عملية تكامل واحدة تتعامل مع كليهما. يعمل نفس كائن العميل عبر طرق الدفع المختلفة.

الخلاصة

إليك ما تعلمته:

• حزم SDKs من Braintree تتعامل مع معالجة الدفع من جانب الخادم
• رموز العميل (Client tokens) تصرح بالتواصل مع الواجهة الأمامية
• مبيعات المعاملات تخصم من بطاقات الائتمان و PayPal
• الاشتراكات تتولى الفوترة المتكررة
• الويب هوك (Webhooks) تخبرك بأحداث الدفع
• اختبر بدقة باستخدام Apidog قبل الإطلاق الفعلي

الأسئلة الشائعة

ما هو رمز الدفع (payment method nonce)؟

الرمز (nonce) هو رمز مميز يستخدم لمرة واحدة يمثل طريقة دفع. تنشئه الواجهة الأمامية بعد أن يدخل العميل تفاصيل البطاقة. يستخدم الخادم الخاص بك هذا الرمز لخصم المبلغ من البطاقة. تنتهي صلاحية الرموز بعد 3 ساعات.

ما الفرق بين التفويض والتسوية؟

التفويض يحجز الأموال على البطاقة. التسوية تقوم بخصم المبلغ فعليًا من البطاقة. بشكل افتراضي، تقوم Braintree بالتسوية التلقائية. للطلبات المسبقة، قم بالتفويض أولاً، ثم سوّي المبلغ عند الشحن:

// تفويض فقط
await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: nonce,
  options: {
    submitForSettlement: false // تفويض فقط
  }
})

// تسوية لاحقًا
await gateway.transaction.submitForSettlement('transaction_id')

كيف أتعامل مع العملات؟

لكل حساب تاجر في Braintree عملة افتراضية. تتطلب العملات المتعددة حسابات تجارية متعددة. تحقق مع دعم Braintree لإعداد العملات المتعددة.

ما أرقام بطاقات الاختبار التي يجب أن أستخدمها؟

توفر Braintree بطاقات اختبار في البيئة التجريبية:

• 4111111111111111 - فيزا (نجاح)
• 4000111111111115 - فيزا (رفض)
• 5555555555554444 - ماستركارد (نجاح)
• 378282246310005 - أمريكان إكسبريس (نجاح)

كيف أتعامل مع النزاعات/استرداد المدفوعات؟

استمع إلى ويب هوك dispute_opened و dispute_won و dispute_lost. قدم الأدلة عبر لوحة تحكم Braintree. وثّق كل شيء - مراسلات العملاء، تأكيدات التسليم، شروط الخدمة.

هل يمكنني تخزين أرقام بطاقات الائتمان؟

لا. تمنع الامتثال لمعايير PCI تخزين أرقام البطاقات الخام. بدلاً من ذلك، قم بتخزين رموز طريقة الدفع. تتولى Braintree نطاق PCI.

ما هو 3D Secure؟

يضيف 3D Secure خطوة تحقق إضافية للمعاملات التي لا تتطلب وجود البطاقة فعليًا. تدعمه Braintree. قم بتمكينه في لوحة التحكم وتعامل مع استجابات authentication_required:

const result = await gateway.transaction.sale({
  amount: '100.00',
  paymentMethodNonce: nonce,
  threeDSecure: {
    required: true
  }
})

كم تستغرق عمليات استرداد الأموال؟

تتم معالجة المبالغ المستردة عادةً في غضون 3-5 أيام عمل. يعتمد التوقيت على بنك العميل. ستتلقى ويب هوك transaction_refunded عند اكتمال العملية.