Cách Sử Dụng API Braintree Hiệu Quả Nhất

Tóm tắt

API của Braintree xử lý thanh toán từ thẻ tín dụng, PayPal, Venmo và ví điện tử. Bạn tích hợp thông qua SDK phía máy chủ (Node, Python, Ruby, v.v.), tạo token client để bảo mật frontend, và xử lý giao dịch, hoàn tiền cũng như đăng ký. Để kiểm thử, hãy sử dụng Apidog để xác thực payload webhook và kiểm tra tích hợp của bạn với dữ liệu sandbox trước khi triển khai chính thức.

Giới thiệu

Braintree xử lý hàng tỷ khoản thanh toán hàng năm. Đây là bộ xử lý thanh toán đứng sau các công ty như Uber, Airbnb và GitHub. Nền tảng này xử lý thẻ tín dụng, PayPal, Venmo, Apple Pay, Google Pay và chuyển khoản ACH.

API thanh toán khác với các API khác. Sai sót với danh mục sản phẩm thì chỉ gây khó chịu. Sai sót với thanh toán sẽ gây tổn thất tiền thật và phá vỡ lòng tin của khách hàng. Bạn cần phải thực hiện đúng.

Braintree cung cấp hai đường dẫn tích hợp: Giao diện người dùng Drop-in (biểu mẫu thanh toán dựng sẵn) và Giao diện người dùng tùy chỉnh (kiểm soát hoàn toàn). Cả hai đều sử dụng cùng một API phía máy chủ để xử lý thanh toán thực tế. Hướng dẫn này bao gồm công việc phía máy chủ xảy ra sau khi khách hàng nhấp vào “Thanh toán.”

💡

Nếu bạn đang xây dựng các tích hợp thanh toán, Apidog giúp bạn kiểm tra các trình xử lý webhook và xác thực phản hồi thanh toán. Bạn có thể mô phỏng các webhook của Braintree tại cục bộ, đảm bảo mã của bạn xử lý thành công, thất bại và các trường hợp biên trước khi xử lý các giao dịch thực.

button

Kiểm tra webhook Braintree với Apidog - miễn phí

Thiết lập Braintree

Tạo tài khoản Braintree

Truy cập braintreepayments.com (Braintree hiện là PayPal Enterprise Payments) và tạo một tài khoản sandbox. Bạn sẽ nhận được:

ID người bán: abc123xyz
Khóa công khai: def456...
Khóa riêng tư: ghi789...

Lưu trữ những thông tin này một cách an toàn. Khóa riêng tư giống như một mật khẩu - không bao giờ cam kết nó vào Git.

Cài đặt SDK

Braintree cung cấp SDK phía máy chủ cho hầu hết các ngôn ngữ:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

Khởi tạo 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
})

Tạo client token

Trước khi hiển thị biểu mẫu thanh toán, hãy tạo một client token. Token này ủy quyền cho frontend giao tiếp với Braintree.

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

Frontend sử dụng token này để khởi tạo giao diện người dùng Drop-in hoặc tích hợp tùy chỉnh.

Xử lý thanh toán

Luồng thanh toán

Frontend gửi nonce phương thức thanh toán đến máy chủ của bạn
Máy chủ tạo giao dịch bằng nonce
Braintree xử lý thanh toán
Máy chủ nhận được phản hồi thành công/thất bại
Bạn hoàn thành đơn hàng hoặc hiển thị lỗi

Tính phí thẻ tín dụng

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

Tính phí bằng phương thức thanh toán đã lưu

Sau giao dịch đầu tiên, bạn có thể lưu phương thức thanh toán để sử dụng sau này:

// Tạo khách hàng với phương thức thanh toán
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// Phương thức thanh toán được lưu
const paymentMethodToken = result.customer.paymentMethods[0].token

// Tính phí phương thức thanh toán đã lưu sau
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

Giao dịch PayPal

Braintree xử lý PayPal tương tự như thẻ. Frontend nhận được một nonce từ PayPal, bạn tính phí:

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

Hoàn tiền và hủy

Hoàn tiền đầy đủ

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

if (result.success) {
  console.log('Đã hoàn tiền:', result.transaction.id)
}

Hoàn tiền một phần

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

if (result.success) {
  console.log('Đã xử lý hoàn tiền một phần')
}

Hủy giao dịch

Hủy dừng một giao dịch trước khi nó được thanh toán. Sử dụng điều này cho các khoản thanh toán đã được ủy quyền nhưng chưa được ghi nhận:

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

if (result.success) {
  console.log('Giao dịch đã bị hủy')
}

Luồng trạng thái giao dịch

được ủy quyền → được gửi để thanh toán → đã thanh toán
                    ↓
                   đã hủy
                    
đã thanh toán → đã hoàn tiền

Đăng ký và thanh toán định kỳ

Braintree xử lý các đăng ký cho các khoản thanh toán định kỳ.

Tạo một gói

Đầu tiên, hãy tạo một gói trong bảng điều khiển Braintree hoặc thông qua API:

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

Tạo một đăng ký

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

if (result.success) {
  console.log('Đã tạo đăng ký:', result.subscription.id)
}

Hủy đăng ký

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

if (result.success) {
  console.log('Đăng ký đã bị hủy')
}

Cập nhật đăng ký

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

Webhooks cho các sự kiện thanh toán

Webhooks thông báo cho máy chủ của bạn về các sự kiện giao dịch. Điều này rất quan trọng đối với các đăng ký và tranh chấp.

Tạo điểm cuối webhook

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

  // Xác minh và phân tích webhook
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('Webhook không hợp lệ')
      }

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

Đăng ký webhook trong Braintree

Trong bảng điều khiển Braintree, đi tới Cài đặt → Webhooks và thêm URL điểm cuối của bạn. Trong quá trình phát triển, hãy sử dụng dịch vụ tunnel như ngrok để nhận webhook tại cục bộ.

Kiểm thử với Apidog

API thanh toán cần được kiểm thử kỹ lưỡng. Bạn không thể dựa vào dữ liệu sản xuất. Apidog giúp bạn kiểm thử mà không gặp rủi ro.

1. Mô phỏng payload webhook

Thay vì chờ Braintree gửi webhook, hãy tạo các payload mô phỏng:

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

Gửi những payload này đến điểm cuối webhook của bạn và xác minh mã của bạn xử lý chúng một cách chính xác.

2. Phân tách môi trường

Tạo các môi trường riêng biệt:

# 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. Xác thực phản hồi webhook

pm.test('Webhook đã xử lý thành công', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('ID giao dịch đã được ghi lại', () => {
  // Kiểm tra nhật ký hoặc cơ sở dữ liệu của bạn
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Kiểm tra webhook Braintree với Apidog - miễn phí

Các lỗi và cách khắc phục thường gặp

Bộ xử lý từ chối

Nguyên nhân: Ngân hàng đã từ chối giao dịch.

Cách khắc phục: Điều này thường do không đủ tiền hoặc bộ lọc gian lận. Hiển thị lỗi chung cho khách hàng và đề xuất thử một thẻ khác. Ghi lại processorResponseCode để gỡ lỗi.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // Ngân hàng từ chối
    return res.status(400).json({
      error: 'Ngân hàng của bạn đã từ chối giao dịch này. Vui lòng thử một thẻ khác.'
    })
  }
}

Gateway từ chối

Nguyên nhân: Các bộ lọc gian lận của Braintree đã chặn giao dịch.

Cách khắc phục: Kiểm tra gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV không khớp
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Xác minh địa chỉ thất bại
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Các công cụ chống gian lận nâng cao đã chặn
}

Lỗi thanh toán

Nguyên nhân: Giao dịch không thể được thanh toán sau khi ủy quyền.

Cách khắc phục: Giám sát các webhook transaction_settlement_declined. Các nguyên nhân phổ biến:

Phương thức thanh toán đã hết hạn giữa lúc ủy quyền và thanh toán
Nhà phát hành đã chặn giao dịch
Không đủ tiền trở nên rõ ràng

Giao dịch trùng lặp

Nguyên nhân: Khách hàng nhấp vào “Thanh toán” hai lần hoặc mã của bạn đã thử lại.

Cách khắc phục: Sử dụng tham số orderId. Braintree sẽ từ chối các giao dịch trùng lặp trong một khoảng thời gian nhất định:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // Ngăn chặn trùng lặp
  options: {
    submitForSettlement: true
  }
})

Các lựa chọn thay thế và so sánh

Tính năng	Braintree	Stripe	PayPal
Giá	2.9% + 30¢	2.9% + 30¢	2.9% + 30¢
Hỗ trợ PayPal	Bản địa	Add-on	Bản địa
Đăng ký	Có	Có	Hạn chế
Quốc tế	46 quốc gia	46 quốc gia	200+ quốc gia
Công cụ chống gian lận	Tích hợp sẵn	Tích hợp sẵn	Cơ bản
Chất lượng SDK	Tuyệt vời	Tuyệt vời	Tốt
Thanh toán	Có	Có	Có

Lợi thế chính của Braintree là hỗ trợ PayPal và Venmo gốc. Nếu bạn cần cả xử lý thẻ và PayPal, nó thường đơn giản hơn so với Stripe + PayPal riêng biệt.

Các trường hợp sử dụng thực tế

Nền tảng đăng ký SaaS. Một công cụ quản lý dự án sử dụng Braintree cho các đăng ký hàng tháng. Webhooks xử lý các khoản thanh toán thất bại (thẻ hết hạn, không đủ tiền) bằng cách gửi thông báo email. Người dùng cập nhật phương thức thanh toán mà không cần liên hệ hỗ trợ.

Thanh toán cho thị trường. Một nền tảng làm việc tự do chia khoản thanh toán giữa phí nền tảng và người làm tự do. Thiết lập tài khoản người bán và tài khoản người bán phụ của Braintree xử lý sự phức tạp này.

Thương mại điện tử với PayPal. Một cửa hàng trực tuyến cung cấp thẻ tín dụng và PayPal. API hợp nhất của Braintree có nghĩa là một tích hợp xử lý cả hai. Cùng một đối tượng khách hàng hoạt động trên các phương thức thanh toán.

Kết luận

Đây là những gì bạn đã học:

SDK của Braintree xử lý thanh toán phía máy chủ
Client token ủy quyền giao tiếp frontend
Giao dịch bán hàng tính phí thẻ tín dụng và PayPal
Đăng ký xử lý thanh toán định kỳ
Webhooks thông báo cho bạn về các sự kiện thanh toán
Kiểm thử kỹ lưỡng với Apidog trước khi triển khai chính thức

button

Câu hỏi thường gặp

Nonce phương thức thanh toán là gì?

Nonce là một token dùng một lần đại diện cho một phương thức thanh toán. Frontend tạo nó sau khi khách hàng nhập chi tiết thẻ. Máy chủ của bạn sử dụng nonce để tính phí thẻ. Nonce hết hạn sau 3 giờ.

Sự khác biệt giữa ủy quyền và thanh toán là gì?

Ủy quyền dự trữ tiền trên thẻ. Thanh toán thực sự tính phí thẻ. Theo mặc định, Braintree tự động thanh toán. Đối với các đơn đặt hàng trước, trước tiên hãy ủy quyền, sau đó thanh toán khi vận chuyển:

// Chỉ ủy quyền
await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: nonce,
  options: {
    submitForSettlement: false // Chỉ ủy quyền
  }
})

// Thanh toán sau
await gateway.transaction.submitForSettlement('transaction_id')

Làm cách nào để xử lý tiền tệ?

Mỗi tài khoản người bán Braintree có một loại tiền tệ mặc định. Đa tiền tệ yêu cầu nhiều tài khoản người bán. Kiểm tra với bộ phận hỗ trợ của Braintree để thiết lập đa tiền tệ.

Tôi nên sử dụng số thẻ kiểm thử nào?

Braintree cung cấp thẻ kiểm thử trong sandbox:

4111111111111111 - Visa (thành công)
4000111111111115 - Visa (từ chối)
5555555555554444 - Mastercard (thành công)
378282246310005 - Amex (thành công)

Làm cách nào để xử lý tranh chấp/hoàn trả?

Lắng nghe các webhook dispute_opened, dispute_won và dispute_lost. Cung cấp bằng chứng thông qua bảng điều khiển Braintree. Ghi lại mọi thứ - giao tiếp với khách hàng, xác nhận giao hàng, điều khoản dịch vụ.

Tôi có thể lưu trữ số thẻ tín dụng không?

Không. Tuân thủ PCI nghiêm cấm lưu trữ số thẻ thô. Thay vào đó, hãy lưu trữ các token phương thức thanh toán. Braintree xử lý phạm vi PCI.

3D Secure là gì?

3D Secure thêm một bước xác minh bổ sung cho các giao dịch không có thẻ. Braintree hỗ trợ nó. Bật trong bảng điều khiển và xử lý các phản hồi authentication_required:

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

Việc hoàn tiền mất bao lâu?

Hoàn tiền thường được xử lý trong 3-5 ngày làm việc. Thời gian phụ thuộc vào ngân hàng của khách hàng. Bạn sẽ nhận được webhook transaction_refunded khi hoàn tất.