Forem

Cover image for كيفية استخدام واجهات برمجة تطبيقات Braintree؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

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

تلخيص

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

جرّب Apidog اليوم

مقدمة

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

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

تقدم Braintree طريقتين للتكامل:

  • واجهة المستخدم الجاهزة (Drop-in UI): نموذج دفع مُعد مسبقًا
  • واجهة المستخدم المخصصة (Custom UI): تحكم كامل

كلا الطريقتين تستخدمان نفس واجهات برمجة تطبيقات جانب الخادم لمعالجة الدفع. هذا الدليل يركّز على العمل الذي يتم على جانب الخادم بعد أن ينقر العميل على "ادفع".

💡 إذا كنت تقوم بإنشاء عمليات تكامل للدفع، Apidog يسهل عليك اختبار معالجات الويب هوك (webhook handlers) والتحقق من استجابات الدفع. تستطيع محاكاة الويب هوك الخاصة بـ Braintree محليًا لضمان أن رمزك يتعامل مع حالات النجاح والفشل والحالات الهامشية قبل معالجة المعاملات الحقيقية.

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

إعداد Braintree

إنشاء حساب Braintree

  1. اذهب إلى braintreepayments.com وأنشئ حسابًا تجريبيًا (sandbox account).
  2. بعد التسجيل ستحصل على:
    • معرف التاجر (Merchant ID): abc123xyz
    • المفتاح العام (Public Key): def456...
    • المفتاح الخاص (Private Key): ghi789...
  3. خزّن هذه البيانات بأمان، ولا تشارك المفتاح الخاص أو تضفه إلى Git.

لوحة تحكم Braintree تعرض مفاتيح API وإعدادات البيئة

تثبيت حزمة SDK

اختر لغة الخادم لديك وثبّت SDK:

Node.js:

npm install braintree
Enter fullscreen mode Exit fullscreen mode

Python:

pip install braintree
Enter fullscreen mode Exit fullscreen mode

Ruby:

gem install braintree
Enter fullscreen mode Exit fullscreen mode

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

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
})
Enter fullscreen mode Exit fullscreen mode

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

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

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

يستخدم هذا الرمز لتهيئة 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
    })
  }
})
Enter fullscreen mode Exit fullscreen mode

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

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

// إنشاء عميل مع طريقة دفع
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
  }
})
Enter fullscreen mode Exit fullscreen mode

معاملات PayPal 

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

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

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

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

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

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

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

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

إلغاء معاملة (Void)

الإلغاء يوقف المعاملة قبل تسويتها:

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

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

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

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

                  مُسواة ← مُستردة
Enter fullscreen mode Exit fullscreen mode

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

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

إنشاء خطة

أنشئ خطة في لوحة التحكم أو عبر API:

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

إنشاء اشتراك 

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

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

إلغاء اشتراك 

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

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

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

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

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

الويب هوك (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')
    }
  )
})
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

واجهة Apidog لاختبار واجهات برمجة التطبيقات، مع التركيز على الويب هوك والتحقق من الاستجابات

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

قم بإنشاء بيانات وهمية وأرسلها لنقطة نهاية الويب هوك:

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
})
Enter fullscreen mode Exit fullscreen mode

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

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

رفض المعالج

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

الإصلاح: عرض رسالة عامة للعميل واقتراح بطاقة مختلفة. سجل processorResponseCode للتصحيح.

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

رفض البوابة

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

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

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

فشل التسوية

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

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

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

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

السبب: نقر العميل مرتين أو أعيدت المحاولة برمجيًا.

الإصلاح: استخدم orderId لمنع التكرار:

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

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

الميزة Braintree Stripe PayPal
التسعير 2.9% + 30¢ 2.9% + 30¢ 2.9% + 30¢
دعم PayPal أصلي إضافة أصلي
الاشتراكات نعم نعم محدود
دولي 46 دولة 46 دولة أكثر من 200 دولة
أدوات الاحتيال مدمج مدمج أساسي
جودة SDK ممتاز ممتاز جيد
المدفوعات نعم نعم نعم

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

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

  • منصة اشتراكات SaaS: تستخدم Braintree للاشتراكات الشهرية. يتم التعامل مع المدفوعات الفاشلة عبر الويب هوك، مع إرسال إشعارات بريدية تلقائية وتمكين تحديث طريقة الدفع ذاتيًا.
  • مدفوعات السوق (Marketplace): تقسيم المدفوعات بين المنصة والمستقلين باستخدام حسابات التجار الفرعية في Braintree لتبسيط التعقيد.
  • التجارة الإلكترونية مع PayPal: واجهة برمجة التطبيقات الموحدة لـ Braintree تتيح دعم البطاقات وPayPal بتكامل واحد، ويعمل نفس كائن العميل عبر جميع طرق الدفع.

الخلاصة

ما يجب تذكره:

  • حزم 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')
Enter fullscreen mode Exit fullscreen mode

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

كل حساب تاجر في Braintree له عملة افتراضية. العملات المتعددة تتطلب حسابات تجارية منفصلة. تواصل مع دعم Braintree لإعداد ذلك.

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

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

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

استمع إلى ويب هوك:

  • dispute_opened
  • dispute_won
  • dispute_lost

قدم الأدلة عبر لوحة تحكم Braintree. وثّق كل شيء (مراسلات العملاء، تأكيدات التسليم، شروط الخدمة).

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

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

ما هو 3D Secure؟

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

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

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

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

Top comments (0)