Forem

Cover image for Cara Menggunakan API Braintree
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menggunakan API Braintree

TL;DR

API Braintree memproses pembayaran dari kartu kredit, PayPal, Venmo, dan dompet digital. Anda berintegrasi melalui SDK sisi server (Node, Python, Ruby, dll.), membuat token klien untuk keamanan frontend, dan menangani transaksi, pengembalian dana, serta langganan. Untuk pengujian, gunakan Apidog untuk memvalidasi payload webhook dan menguji integrasi Anda terhadap data sandbox sebelum tayang langsung.

Coba Apidog hari ini

Pendahuluan

Braintree memproses miliaran pembayaran setiap tahun. Ini adalah pemroses pembayaran di balik perusahaan seperti Uber, Airbnb, dan GitHub. Platform ini menangani kartu kredit, PayPal, Venmo, Apple Pay, Google Pay, dan transfer ACH.

API pembayaran berbeda dengan API lainnya. Kesalahan pada katalog produk itu menjengkelkan. Kesalahan pada pembayaran merugikan uang sungguhan dan merusak kepercayaan pelanggan. Anda harus melakukannya dengan benar.

Braintree menawarkan dua jalur integrasi: Drop-in UI (formulir pembayaran siap pakai) dan Custom UI (kontrol penuh). Keduanya menggunakan API sisi server yang sama untuk pemrosesan pembayaran aktual. Berikut langkah implementasi sisi server setelah pelanggan mengeklik “Bayar”.

💡 Tips: Saat membangun integrasi pembayaran, gunakan Apidog untuk menguji penanganan webhook dan validasi respons pembayaran. Anda bisa membuat mock webhook Braintree secara lokal, memastikan kode Anda menangani skenario sukses, gagal, dan edge-case sebelum transaksi nyata.

Uji webhook Braintree dengan Apidog - gratis

Menyiapkan Braintree

Buat akun Braintree

  1. Kunjungi braintreepayments.com dan buat akun sandbox.
  2. Catat kredensial berikut:
    • ID Merchant: abc123xyz
    • Kunci Publik: def456...
    • Kunci Privat: ghi789...
  3. Simpan rahasia ini dengan aman. Jangan pernah mengunggah kunci privat ke Git.

Braintree Dashboard

Instal SDK

Braintree menyediakan SDK sisi server untuk berbagai bahasa.

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

Inisialisasi gateway:

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

Buat token klien

Buat endpoint untuk menghasilkan token klien yang akan digunakan frontend saat render form pembayaran.

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

Frontend akan menggunakan token ini untuk inisialisasi Drop-in UI atau integrasi custom.

Memproses Pembayaran

Alur pembayaran

  1. Frontend mengirimkan nonce metode pembayaran ke server.
  2. Server membuat transaksi menggunakan nonce.
  3. Braintree memproses pembayaran.
  4. Server menerima respons sukses/gagal.
  5. Lakukan pemenuhan pesanan atau tampilkan error.

Mendebit kartu kredit 

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

Mendebit dengan metode pembayaran tersimpan

Simpan metode pembayaran saat transaksi pertama, lalu gunakan untuk transaksi berikutnya.

// Buat pelanggan dengan metode pembayaran
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// Ambil token metode pembayaran
const paymentMethodToken = result.customer.paymentMethods[0].token

// Debet metode pembayaran tersimpan
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Transaksi PayPal

Frontend mendapatkan nonce PayPal, backend mendebit dengan cara yang sama.

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

Pengembalian Dana dan Pembatalan

Pengembalian dana penuh 

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

if (result.success) {
  console.log('Refunded:', result.transaction.id)
}
Enter fullscreen mode Exit fullscreen mode

Pengembalian dana sebagian 

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

if (result.success) {
  console.log('Partial refund processed')
}
Enter fullscreen mode Exit fullscreen mode

Batalkan transaksi (void) 

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

if (result.success) {
  console.log('Transaction voided')
}
Enter fullscreen mode Exit fullscreen mode

Alur status transaksi 

authorized → submitted_for_settlement → settled
                    ↓
                  voided

settled → refunded
Enter fullscreen mode Exit fullscreen mode

Langganan dan Penagihan Berulang

Braintree menangani pembayaran berulang dengan langganan.

Buat paket

Buat di panel kontrol atau lewat 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

Buat langganan 

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

if (result.success) {
  console.log('Subscription created:', result.subscription.id)
}
Enter fullscreen mode Exit fullscreen mode

Batalkan langganan 

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

if (result.success) {
  console.log('Subscription cancelled')
}
Enter fullscreen mode Exit fullscreen mode

Perbarui langganan 

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

Webhook untuk Peristiwa Pembayaran

Webhook memberitahu server Anda tentang update transaksi. Wajib untuk langganan dan sengketa.

Buat endpoint webhook 

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

Daftarkan webhook di Braintree

Masuk ke Braintree, buka Pengaturan → Webhooks, dan tambahkan endpoint URL Anda. Untuk development, gunakan ngrok agar webhook bisa diakses secara lokal.

Pengujian dengan Apidog

API pembayaran harus diuji menyeluruh sebelum produksi. Apidog membuatnya lebih mudah dan aman.

Apidog Testing

1. Mock payload webhook

Buat payload mock dan kirim ke endpoint webhook Anda untuk validasi kode.

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

2. Pemisahan lingkungan

Gunakan environment variable berbeda antara sandbox dan produksi.

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

# Produksi
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. Validasi respons webhook

Gunakan test script untuk memastikan endpoint webhook berjalan dengan benar.

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

pm.test('Transaction ID logged', () => {
  // Cek log atau database
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})
Enter fullscreen mode Exit fullscreen mode

Uji webhook Braintree dengan Apidog - gratis

Kesalahan Umum dan Perbaikan

Diproses Ditolak

Penyebab: Bank menolak transaksi.

Solusi: Tampilkan error umum, sarankan coba kartu lain, log processorResponseCode untuk debugging.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    return res.status(400).json({
      error: 'Transaksi Anda ditolak oleh bank. Mohon coba kartu lain.'
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Gateway Ditolak

Penyebab: Filter penipuan Braintree memblokir transaksi.

Solusi: Cek gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV tidak cocok
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Verifikasi alamat gagal
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Alat penipuan canggih memblokirnya
}
Enter fullscreen mode Exit fullscreen mode

Kegagalan penyelesaian

Penyebab: Transaksi tidak dapat diselesaikan setelah otorisasi.

Solusi: Pantau webhook transaction_settlement_declined. Cek:

  • Metode pembayaran expired antara otorisasi & penyelesaian
  • Penerbit memblokir transaksi
  • Dana tidak mencukupi

Transaksi duplikat

Penyebab: Pelanggan klik "Bayar" dua kali / code retry.

Solusi: Gunakan parameter orderId unik.

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

Alternatif dan Perbandingan

Fitur Braintree Stripe PayPal
Harga 2.9% + 30¢ 2.9% + 30¢ 2.9% + 30¢
Dukungan PayPal Natif Add-on Natif
Langganan Ya Ya Terbatas
Internasional 46 negara 46 negara 200+ negara
Alat penipuan Bawaan Bawaan Dasar
Kualitas SDK Sangat Baik Sangat Baik Baik
Pembayaran Ya Ya Ya

Keunggulan utama Braintree adalah dukungan PayPal dan Venmo natif. Untuk kebutuhan kartu + PayPal, integrasi Braintree lebih sederhana daripada Stripe + PayPal terpisah.

Kasus Penggunaan Dunia Nyata

  • Platform langganan SaaS: Manajemen proyek menggunakan Braintree untuk langganan bulanan. Webhook menangani pembayaran gagal (kartu expired, dana tidak cukup) dan notifikasi email.
  • Marketplace: Platform freelancer membagi pembayaran antara biaya platform dan freelancer. Sub-merchant Braintree menangani ini.
  • E-commerce dengan PayPal: Toko online menawarkan kartu kredit dan PayPal. Satu API Braintree cukup untuk keduanya, dan objek pelanggan konsisten lintas metode pembayaran.

Kesimpulan

Rangkuman langkah implementasi:

  • SDK Braintree untuk backend processing pembayaran
  • Token klien otorisasi komunikasi frontend
  • Transaksi untuk debit kartu kredit & PayPal
  • Fitur langganan untuk recurring billing
  • Webhook untuk notifikasi event pembayaran
  • Uji menyeluruh dengan Apidog sebelum produksi

FAQ

Apa itu nonce metode pembayaran?

Nonce adalah token satu kali untuk mewakili metode pembayaran (misal, kartu). Dihasilkan oleh frontend, digunakan backend untuk transaksi. Berlaku selama 3 jam.

Apa perbedaan antara otorisasi dan penyelesaian?

Otorisasi hanya menahan dana di kartu. Penyelesaian mendebit dana. Default: Braintree langsung menyelesaikan. Untuk pre-order, lakukan otorisasi saja, settlement nanti.

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

// Settlement manual
await gateway.transaction.submitForSettlement('transaction_id')
Enter fullscreen mode Exit fullscreen mode

Bagaimana cara menangani mata uang?

Akun merchant Braintree punya mata uang default. Multi-mata uang = beberapa akun merchant. Hubungi support Braintree untuk setup.

Nomor kartu uji apa yang harus saya gunakan?

Braintree menyediakan kartu uji di sandbox:

  • 4111111111111111 - Visa (berhasil)
  • 4000111111111115 - Visa (ditolak)
  • 5555555555554444 - Mastercard (berhasil)
  • 378282246310005 - Amex (berhasil)

Bagaimana cara menangani sengketa/chargeback?

Dengarkan webhook: dispute_opened, dispute_won, dispute_lost. Upload bukti via dashboard Braintree. Dokumentasikan komunikasi pelanggan, konfirmasi pengiriman, syarat layanan.

Bisakah saya menyimpan nomor kartu kredit?

Tidak boleh. PCI compliance melarang simpan nomor kartu mentah. Simpan token metode pembayaran. Braintree mengelola tanggung jawab PCI.

Apa itu 3D Secure?

3D Secure menambah verifikasi ekstra untuk transaksi online. Aktifkan di dashboard, handle respons authentication_required.

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

Berapa lama waktu untuk pengembalian dana?

Umumnya 3-5 hari kerja, tergantung bank pelanggan. Webhook transaction_refunded akan diterima setelah selesai.

Top comments (0)