Braintree API'leri Nasıl Kullanılır?

TL;DR

Braintree API'leri kredi kartları, PayPal, Venmo ve dijital cüzdanlardan ödemeleri işler. Sunucu tarafı SDK'lar (Node, Python, Ruby vb.) aracılığıyla entegre olursunuz, ön uç güvenliği için istemci belirteçleri oluşturursunuz ve işlemleri, iadeleri ve abonelikleri yönetirsiniz. Test için, canlıya geçmeden önce webhook yüklerini doğrulamak ve sandbox verilerine karşı entegrasyonunuzu test etmek için Apidog'u kullanın.

Giriş

Braintree, yılda milyarlarca dolar değerinde ödeme işler. Uber, Airbnb ve GitHub gibi şirketlerin arkasındaki ödeme işlemcisidir. Platform, kredi kartları, PayPal, Venmo, Apple Pay, Google Pay ve ACH transferlerini yönetir.

Ödeme API'leri diğer API'lerden farklıdır. Bir ürün kataloğundaki bir hata rahatsız edicidir. Ödemelerdeki bir hata gerçek paraya mal olur ve müşteri güvenini zedeler. Doğru yapmanız gerekir.

Braintree iki entegrasyon yolu sunar: Drop-in UI (önceden oluşturulmuş ödeme formu) ve Özel UI (tam kontrol). Her ikisi de gerçek ödeme işleme için aynı sunucu tarafı API'lerini kullanır. Bu kılavuz, bir müşteri "Öde"ye tıkladıktan sonra gerçekleşen sunucu tarafı çalışmayı kapsar.

💡

Ödeme entegrasyonları oluşturuyorsanız, Apidog webhook işleyicilerini test etmenize ve ödeme yanıtlarını doğrulamanıza yardımcı olur. Braintree'nin webhook'larını yerel olarak taklit edebilir, kodunuzun gerçek işlemleri işlemeden önce başarı, başarısızlık ve uç durumları ele aldığından emin olabilirsiniz.

button

Apidog ile Braintree webhook'larını test edin - ücretsiz

Braintree Kurulumu

Braintree hesabı oluşturma

braintreepayments.com adresine gidin (Braintree artık PayPal Enterprise Payments'tır) ve bir sandbox hesabı oluşturun. Şunları alacaksınız:

Satıcı Kimliği: abc123xyz
Herkese Açık Anahtar: def456...
Gizli Anahtar: ghi789...

Bunları güvenli bir şekilde saklayın. Gizli anahtar bir parola gibidir - asla Git'e göndermeyin.

SDK'yı Kurma

Braintree çoğu dil için sunucu tarafı SDK'lar sağlar:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

Ağ geçidini başlatma:

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
})

İstemci belirteci oluşturma

Ödeme formunu göstermeden önce bir istemci belirteci oluşturun. Bu, ön ucun Braintree ile iletişim kurmasını yetkilendirir.

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

Ön uç, Drop-in UI'yi veya özel entegrasyonu başlatmak için bu belirteci kullanır.

Ödeme İşleme

Ödeme akışı

Ön uç, ödeme yöntemi nonce'unu sunucunuza gönderir
Sunucu, nonce'u kullanarak bir işlem oluşturur
Braintree ödemeyi işler
Sunucu, başarı/başarısızlık yanıtını alır
Siparişi yerine getirirsiniz veya bir hata gösterirsiniz

Kredi kartından tahsilat yapma

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
    })
  }
})

Kayıtlı ödeme yöntemiyle tahsilat yapma

İlk işlemden sonra, gelecekte kullanmak üzere ödeme yöntemini kaydedebilirsiniz:

// Ödeme yöntemiyle müşteri oluşturma
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// Ödeme yöntemi kaydedildi
const paymentMethodToken = result.customer.paymentMethods[0].token

// Kaydedilen ödeme yönteminden daha sonra tahsilat yapma
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

PayPal işlemleri

Braintree, PayPal'ı kartlarla aynı şekilde işler. Ön uç, PayPal'dan bir nonce alır, siz de bunu tahsil edersiniz:

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

İadeler ve İptaller

Tam iade

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

if (result.success) {
  console.log('İade edildi:', result.transaction.id)
}

Kısmi iade

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

if (result.success) {
  console.log('Kısmi iade işlendi')
}

Bir işlemi iptal etme

İptal, bir işlem tamamlanmadan önce durdurur. Bunu, yetkilendirilmiş ancak henüz tahsil edilmemiş ödemeler için kullanın:

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

if (result.success) {
  console.log('İşlem iptal edildi')
}

İşlem durumu akışı

yetkilendirildi → ödeme için gönderildi → ödendi
                    ↓
                   iptal edildi
                    
ödendi → iade edildi

Abonelikler ve yinelenen faturalandırma

Braintree, yinelenen ödemeler için abonelikleri yönetir.

Bir plan oluşturma

İlk olarak, Braintree kontrol panelinde veya API aracılığıyla bir plan oluşturun:

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

Bir abonelik oluşturma

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

if (result.success) {
  console.log('Abonelik oluşturuldu:', result.subscription.id)
}

Bir aboneliği iptal etme

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

if (result.success) {
  console.log('Abonelik iptal edildi')
}

Aboneliği güncelleme

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

Ödeme olayları için Webhook'lar

Webhook'lar, işlem olayları hakkında sunucunuzu bilgilendirir. Bu, abonelikler ve anlaşmazlıklar için kritiktir.

Bir webhook uç noktası oluşturma

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

  // Webhook'u doğrulama ve ayrıştırma
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('Geçersiz webhook')
      }

      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'de webhook kaydetme

Braintree kontrol panelinde, Ayarlar → Webhook'lar'a gidin ve uç nokta URL'nizi ekleyin. Geliştirme aşamasında, webhook'ları yerel olarak almak için ngrok gibi bir tünelleme hizmeti kullanın.

Apidog ile Test Etme

Ödeme API'lerinin kapsamlı teste ihtiyacı vardır. Üretim verilerine güvenemezsiniz. Apidog, risksiz test yapmanıza yardımcı olur.

1. Webhook yüklerini taklit etme

Braintree'nin webhook göndermesini beklemek yerine, taklit yükler oluşturun:

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

Bunları webhook uç noktanıza gönderin ve kodunuzun bunları doğru şekilde işlediğini doğrulayın.

2. Ortam ayrımı

Ayrı ortamlar oluşturun:

# Sandbox
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# Üretim
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production

3. Webhook yanıtlarını doğrulama

pm.test('Webhook başarıyla işlendi', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('İşlem Kimliği kaydedildi', () => {
  // Günlüklerinizi veya veritabanınızı kontrol edin
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Apidog ile Braintree webhook'larını test edin - ücretsiz

Sıkça Karşılaşılan Hatalar ve Düzeltmeler

İşlemci Reddedildi

Neden: Banka işlemi reddetti.

Düzeltme: Bu genellikle yetersiz bakiye veya sahtekarlık filtrelerinden kaynaklanır. Müşteriye genel bir hata gösterin ve farklı bir kart denemesini önerin. Hata ayıklama için processorResponseCode'u günlüğe kaydedin.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // Banka reddetti
    return res.status(400).json({
      error: 'Bankanız bu işlemi reddetti. Lütfen farklı bir kart deneyin.'
    })
  }
}

Ağ Geçidi Reddedildi

Neden: Braintree'nin sahtekarlık filtreleri işlemi engelledi.

Düzeltme: gatewayRejectionReason'ı kontrol edin:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV uyuşmazlığı
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Adres doğrulama başarısız oldu
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Gelişmiş sahtekarlık araçları engelledi
}

Ödeme başarısızlıkları

Neden: Yetkilendirmeden sonra işlem tahsil edilemedi.

Düzeltme: transaction_settlement_declined webhook'larını izleyin. Yaygın nedenler:

Ödeme yöntemi yetkilendirme ile ödeme arasında süresi doldu
İhraççı işlemi engelledi
Yetersiz bakiye ortaya çıktı

Tekrar eden işlemler

Neden: Müşteri "Öde"ye iki kez tıkladı veya kodunuz yeniden denedi.

Düzeltme: orderId parametresini kullanın. Braintree, belirli bir zaman aralığındaki tekrar edenleri reddedecektir:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // Tekrarları önler
  options: {
    submitForSettlement: true
  }
})

Alternatifler ve Karşılaştırmalar

Özellik	Braintree	Stripe	PayPal
Fiyatlandırma	%2,9 + 30¢	%2,9 + 30¢	%2,9 + 30¢
PayPal desteği	Yerel	Eklenti	Yerel
Abonelikler	Evet	Evet	Sınırlı
Uluslararası	46 ülke	46 ülke	200+ ülke
Sahtekarlık araçları	Yerleşik	Yerleşik	Temel
SDK kalitesi	Mükemmel	Mükemmel	İyi
Ödemeler	Evet	Evet	Evet

Braintree'nin ana avantajı yerel PayPal ve Venmo desteğidir. Hem kart işlemlerine hem de PayPal'a ihtiyacınız varsa, genellikle Stripe + PayPal'ı ayrı ayrı kullanmaktan daha basittir.

Gerçek Dünya Kullanım Durumları

SaaS abonelik platformu. Bir proje yönetimi aracı, aylık abonelikler için Braintree kullanır. Webhook'lar başarısız ödemeleri (kart süresi doldu, yetersiz bakiye) e-posta bildirimleri göndererek yönetir. Kullanıcılar, destekle iletişime geçmeden ödeme yöntemlerini günceller.

Pazar yeri ödemeleri. Bir serbest çalışan platformu, ödemeleri platform ücreti ile serbest çalışan arasında böler. Braintree'nin satıcı hesapları ve alt satıcı kurulumu karmaşıklığı yönetir.

PayPal ile E-ticaret. Bir çevrimiçi mağaza kredi kartları ve PayPal sunar. Braintree'nin birleşik API'si, tek bir entegrasyonun her ikisini de yönetmesi anlamına gelir. Aynı müşteri nesnesi, ödeme yöntemleri arasında çalışır.

Sonuç

İşte öğrendikleriniz:

Braintree SDK'ları sunucu tarafı ödeme işlemeyi yönetir
İstemci belirteçleri ön uç iletişimini yetkilendirir
İşlem satışları kredi kartlarından ve PayPal'dan tahsilat yapar
Abonelikler yinelenen faturalandırmayı yönetir
Webhook'lar sizi ödeme olayları hakkında bilgilendirir
Canlıya geçmeden önce Apidog ile kapsamlı bir şekilde test edin

button

SSS

Ödeme yöntemi nonce'u nedir?

Bir nonce, bir ödeme yöntemini temsil eden tek kullanımlık bir belirteçtir. Ön uç, müşteri kart bilgilerini girdikten sonra bunu oluşturur. Sunucunuz, karttan tahsilat yapmak için nonce'u kullanır. Nonce'lar 3 saat sonra sona erer.

Yetkilendirme ve ödeme arasındaki fark nedir?

Yetkilendirme, karttaki fonları rezerve eder. Ödeme ise karttan fiilen tahsilat yapar. Varsayılan olarak, Braintree otomatik olarak ödeme yapar. Ön siparişler için önce yetkilendirme yapın, ardından gönderim yaparken ödeme yapın:

// Sadece yetkilendir
await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: nonce,
  options: {
    submitForSettlement: false // Sadece yetkilendir
  }
})

// Daha sonra ödeme yap
await gateway.transaction.submitForSettlement('transaction_id')

Para birimini nasıl yönetirim?

Her Braintree satıcı hesabının varsayılan bir para birimi vardır. Çoklu para birimi için birden fazla satıcı hesabı gerekir. Çoklu para birimi kurulumu için Braintree desteğiyle iletişime geçin.

Hangi test kart numaralarını kullanmalıyım?

Braintree, sandbox'ta test kartları sağlar:

4111111111111111 - Visa (başarılı)
4000111111111115 - Visa (reddedildi)
5555555555554444 - Mastercard (başarılı)
378282246310005 - Amex (başarılı)

Anlaşmazlıkları/geri ödemeleri nasıl yönetirim?

dispute_opened, dispute_won ve dispute_lost webhook'larını dinleyin. Braintree kontrol paneli aracılığıyla kanıt sağlayın. Müşteri iletişimleri, teslimat onayları, hizmet şartları gibi her şeyi belgeleyin.

Kredi kartı numaralarını saklayabilir miyim?

Hayır. PCI uyumluluğu, ham kart numaralarının saklanmasını yasaklar. Bunun yerine ödeme yöntemi belirteçlerini saklayın. Braintree, PCI kapsamını yönetir.

3D Secure nedir?

3D Secure, kartın fiziksel olarak bulunmadığı işlemler için ek bir doğrulama adımı ekler. Braintree bunu destekler. Kontrol panelinden etkinleştirin ve authentication_required yanıtlarını yönetin:

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

İadeler ne kadar sürer?

İadeler genellikle 3-5 iş günü içinde işlenir. Zamanlama, müşterinin bankasına bağlıdır. Tamamlandığında transaction_refunded webhook'unu alacaksınız.