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.

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. Panduan ini mencakup pekerjaan sisi server yang terjadi setelah pelanggan mengeklik “Bayar.”

💡

Jika Anda membuat integrasi pembayaran, Apidog membantu Anda menguji penangan webhook dan memvalidasi respons pembayaran. Anda dapat membuat mock webhook Braintree secara lokal, memastikan kode Anda menangani keberhasilan, kegagalan, dan kasus ekstrem sebelum memproses transaksi nyata.

tombol

Uji webhook Braintree dengan Apidog - gratis

Menyiapkan Braintree

Buat akun Braintree

Kunjungi braintreepayments.com (Braintree sekarang adalah PayPal Enterprise Payments) dan buat akun sandbox. Anda akan mendapatkan:

ID Merchant: abc123xyz
Kunci Publik: def456...
Kunci Privat: ghi789...

Simpan ini dengan aman. Kunci privat seperti kata sandi - jangan pernah mengunggahnya ke Git.

Instal SDK

Braintree menyediakan SDK sisi server untuk sebagian besar bahasa:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

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

Buat token klien

Sebelum menampilkan formulir pembayaran, buat token klien. Ini mengotorisasi frontend untuk berkomunikasi dengan Braintree.

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

Frontend menggunakan token ini untuk menginisialisasi Drop-in UI atau integrasi khusus.

Memproses pembayaran

Alur pembayaran

Frontend mengirimkan nonce metode pembayaran ke server Anda
Server membuat transaksi menggunakan nonce
Braintree memproses pembayaran
Server menerima respons keberhasilan/kegagalan
Anda memenuhi pesanan atau menampilkan kesalahan

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

Mendebit dengan metode pembayaran tersimpan

Setelah transaksi pertama, Anda dapat menyimpan metode pembayaran untuk penggunaan di masa mendatang:

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

// Metode pembayaran telah disimpan
const paymentMethodToken = result.customer.paymentMethods[0].token

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

Transaksi PayPal

Braintree menangani PayPal dengan cara yang sama seperti kartu. Frontend mendapatkan nonce dari PayPal, Anda mendebitnya:

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

Pengembalian dana dan pembatalan

Pengembalian dana penuh

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

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

Pengembalian dana sebagian

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

if (result.success) {
  console.log('Partial refund processed')
}

Batalkan transaksi

Pembatalan menghentikan transaksi sebelum diselesaikan. Gunakan ini untuk pembayaran yang diotorisasi tetapi belum ditangkap:

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

if (result.success) {
  console.log('Transaction voided')
}

Alur status transaksi

authorized → submitted_for_settlement → settled
                    ↓
                  voided
                    
settled → refunded

Langganan dan penagihan berulang

Braintree menangani langganan untuk pembayaran berulang.

Buat paket

Pertama, buat paket di panel kontrol Braintree atau melalui API:

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

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

Batalkan langganan

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

if (result.success) {
  console.log('Subscription cancelled')
}

Perbarui langganan

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

Webhook untuk peristiwa pembayaran

Webhook memberitahu server Anda tentang peristiwa transaksi. Ini sangat penting 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

  // Verify and parse the webhook
  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')
    }
  )
})

Daftarkan webhook di Braintree

Di panel kontrol Braintree, buka Pengaturan → Webhooks dan tambahkan URL endpoint Anda. Dalam pengembangan, gunakan layanan tunneling seperti ngrok untuk menerima webhook secara lokal.

Pengujian dengan Apidog

API pembayaran memerlukan pengujian menyeluruh. Anda tidak dapat mengandalkan data produksi. Apidog membantu Anda menguji tanpa risiko.

1. Mock payload webhook

Alih-alih menunggu Braintree mengirim webhook, buat payload mock:

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

Kirim ini ke endpoint webhook Anda dan verifikasi kode Anda menanganinya dengan benar.

2. Pemisahan lingkungan

Buat lingkungan terpisah:

# 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

3. Validasi respons webhook

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

pm.test('Transaction ID logged', () => {
  // Check your logs or database
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Uji webhook Braintree dengan Apidog - gratis

Kesalahan umum dan perbaikan

Diproses Ditolak

Penyebab: Bank menolak transaksi tersebut.

Perbaikan: Ini sering kali disebabkan oleh dana yang tidak mencukupi atau filter penipuan. Tampilkan kesalahan umum kepada pelanggan dan sarankan untuk mencoba kartu yang berbeda. Catat processorResponseCode untuk debugging.

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

Gateway Ditolak

Penyebab: Filter penipuan Braintree memblokir transaksi tersebut.

Perbaikan: Periksa 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
}

Kegagalan penyelesaian

Penyebab: Transaksi tidak dapat diselesaikan setelah otorisasi.

Perbaikan: Pantau webhook transaction_settlement_declined. Penyebab umum:

Metode pembayaran kedaluwarsa antara otorisasi dan penyelesaian
Penerbit memblokir transaksi
Dana yang tidak mencukupi menjadi jelas

Transaksi duplikat

Penyebab: Pelanggan mengeklik "Bayar" dua kali atau kode Anda mencoba lagi.

Perbaikan: Gunakan parameter orderId. Braintree akan menolak duplikasi dalam jendela waktu tertentu:

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

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. Jika Anda memerlukan pemrosesan kartu dan PayPal, ini seringkali lebih sederhana daripada Stripe + PayPal secara terpisah.

Kasus penggunaan dunia nyata

Platform langganan SaaS. Alat manajemen proyek menggunakan Braintree untuk langganan bulanan. Webhook menangani pembayaran yang gagal (kartu kedaluwarsa, dana tidak mencukupi) dengan mengirimkan notifikasi email. Pengguna memperbarui metode pembayaran tanpa menghubungi dukungan.

Pembayaran marketplace. Platform freelancer membagi pembayaran antara biaya platform dan freelancer. Akun merchant Braintree dan pengaturan sub-merchant menangani kerumitan ini.

E-commerce dengan PayPal. Toko online menawarkan kartu kredit dan PayPal. API terpadu Braintree berarti satu integrasi menangani keduanya. Objek pelanggan yang sama berfungsi di seluruh metode pembayaran.

Kesimpulan

Berikut adalah apa yang telah Anda pelajari:

SDK Braintree menangani pemrosesan pembayaran sisi server
Token klien mengotorisasi komunikasi frontend
Penjualan transaksi mendebit kartu kredit dan PayPal
Langganan menangani penagihan berulang
Webhook memberitahu Anda tentang peristiwa pembayaran
Uji secara menyeluruh dengan Apidog sebelum tayang langsung

tombol

FAQ

Apa itu nonce metode pembayaran?

Nonce adalah token satu kali yang mewakili metode pembayaran. Frontend menghasilkannya setelah pelanggan memasukkan detail kartu. Server Anda menggunakan nonce untuk mendebit kartu. Nonce kedaluwarsa setelah 3 jam.

Apa perbedaan antara otorisasi dan penyelesaian?

Otorisasi memesan dana pada kartu. Penyelesaian benar-benar mendebit kartu. Secara default, Braintree otomatis menyelesaikannya. Untuk pra-pemesanan, otorisasi terlebih dahulu, lalu selesaikan saat pengiriman:

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

// Selesaikan nanti
await gateway.transaction.submitForSettlement('transaction_id')

Bagaimana cara menangani mata uang?

Setiap akun merchant Braintree memiliki mata uang default. Multi-mata uang memerlukan beberapa akun merchant. Periksa dengan dukungan Braintree untuk pengaturan multi-mata uang.

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, dan dispute_lost. Berikan bukti melalui panel kontrol Braintree. Dokumentasikan semuanya - komunikasi pelanggan, konfirmasi pengiriman, syarat layanan.

Bisakah saya menyimpan nomor kartu kredit?

Tidak. Kepatuhan PCI melarang penyimpanan nomor kartu mentah. Simpan token metode pembayaran sebagai gantinya. Braintree menangani cakupan PCI.

Apa itu 3D Secure?

3D Secure menambahkan langkah verifikasi ekstra untuk transaksi tanpa kehadiran kartu. Braintree mendukungnya. Aktifkan di panel kontrol dan tangani respons authentication_required:

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

Berapa lama waktu yang dibutuhkan untuk pengembalian dana?

Pengembalian dana biasanya diproses dalam 3-5 hari kerja. Waktu tergantung pada bank pelanggan. Anda akan menerima webhook transaction_refunded setelah selesai.