Forem

Cover image for วิธีใช้ Braintree API
Thanawat Wongchai
Thanawat Wongchai

Posted on • Originally published at apidog.com

วิธีใช้ Braintree API

TL;DR

Braintree APIs ประมวลผลการชำระเงินจากบัตรเครดิต, PayPal, Venmo และกระเป๋าเงินดิจิทัล คุณสามารถรวมระบบผ่าน SDK ฝั่งเซิร์ฟเวอร์ (Node, Python, Ruby ฯลฯ) สร้างโทเค็นไคลเอนต์เพื่อความปลอดภัยของส่วนหน้า และจัดการธุรกรรม การคืนเงิน และการสมัครสมาชิก สำหรับการทดสอบ ให้ใช้ Apidog เพื่อตรวจสอบความถูกต้องของเพย์โหลดเว็บฮุก และทดสอบการรวมระบบของคุณกับข้อมูล Sandbox ก่อนที่จะใช้งานจริง

ทดลองใช้ Apidog วันนี้

บทนำ

Braintree ประมวลผลการชำระเงินหลายพันล้านดอลลาร์ต่อปี เป็นผู้ประมวลผลการชำระเงินเบื้องหลังบริษัทต่างๆ เช่น Uber, Airbnb และ GitHub แพลตฟอร์มนี้รองรับบัตรเครดิต, PayPal, Venmo, Apple Pay, Google Pay และการโอนเงินผ่าน ACH

API การชำระเงินแตกต่างจาก API อื่นๆ ข้อผิดพลาดเกี่ยวกับแคตตาล็อกสินค้าเป็นเรื่องที่น่ารำคาญ ข้อผิดพลาดในการชำระเงินทำให้เสียเงินจริงและทำลายความไว้วางใจของลูกค้า คุณต้องทำให้ถูกต้อง

Braintree เสนอสองเส้นทางในการรวมระบบ: Drop-in UI (ฟอร์มการชำระเงินสำเร็จรูป) และ Custom UI (ควบคุมได้เต็มที่) ทั้งสองวิธีใช้ API ฝั่งเซิร์ฟเวอร์เดียวกันสำหรับการประมวลผลการชำระเงินจริง คู่มือนี้ครอบคลุมงานฝั่งเซิร์ฟเวอร์ที่เกิดขึ้นหลังจากลูกค้าคลิก “ชำระเงิน”

💡 หากคุณกำลังสร้างการรวมระบบการชำระเงิน, Apidog ช่วยให้คุณทดสอบตัวจัดการเว็บฮุกและตรวจสอบการตอบกลับการชำระเงิน คุณสามารถจำลองเว็บฮุกของ Braintree ในเครื่อง เพื่อให้แน่ใจว่าโค้ดของคุณสามารถจัดการกับกรณีสำเร็จ, ล้มเหลว และกรณีขอบต่างๆ ได้ก่อนที่จะประมวลผลธุรกรรมจริง

ทดสอบเว็บฮุก Braintree ด้วย Apidog - ฟรี

การตั้งค่า Braintree

สร้างบัญชี Braintree

ไปที่ braintreepayments.com (Braintree ตอนนี้คือ PayPal Enterprise Payments) และสร้างบัญชี Sandbox คุณจะได้รับ:

  • รหัสร้านค้า: abc123xyz
  • คีย์สาธารณะ: def456...
  • คีย์ส่วนตัว: ghi789...

เก็บข้อมูลเหล่านี้อย่างปลอดภัย คีย์ส่วนตัวเปรียบเสมือนรหัสผ่าน - ห้ามผูกมัดเข้ากับ Git โดยเด็ดขาด

braintree-setup

ติดตั้ง SDK

Braintree มี 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

เริ่มต้น 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

สร้างโทเค็นไคลเอนต์

ก่อนที่จะแสดงแบบฟอร์มการชำระเงิน ให้สร้างโทเค็นไคลเอนต์เพื่อให้ frontend เรียกใช้ได้อย่างปลอดภัย

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 จะใช้ token นี้เพื่อเริ่มต้น 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

Braintree จัดการ PayPal ในลักษณะเดียวกับบัตร ส่วนหน้าจะได้รับ nonce จาก 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

ยกเลิกธุรกรรม

ยกเลิกธุรกรรมที่ยังไม่ได้ชำระ:

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 จัดการการสมัครสมาชิกสำหรับการชำระเงินแบบประจำ

สร้างแผน

สร้างแผนในแผงควบคุม 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

เว็บฮุกสำหรับเหตุการณ์การชำระเงิน

เว็บฮุกแจ้งเซิร์ฟเวอร์ของคุณเกี่ยวกับเหตุการณ์ธุรกรรม เช่น การชำระเงินสำเร็จ/ล้มเหลว, ข้อพิพาท ฯลฯ

สร้าง Webhook Endpoint 

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

  // ตรวจสอบและแยกวิเคราะห์ webhook
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('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

ลงทะเบียน Webhook ใน Braintree

ในแผงควบคุม Braintree ไปที่ Settings → Webhooks และเพิ่ม URL ของ endpoint ของคุณ ในการพัฒนา ให้ใช้บริการ tunneling เช่น ngrok เพื่อรับ webhooks ในเครื่อง

การทดสอบด้วย Apidog

API การชำระเงินจำเป็นต้องมีการทดสอบอย่างละเอียด คุณไม่สามารถพึ่งพาข้อมูลการผลิตได้ Apidog ช่วยให้คุณทดสอบได้โดยไม่มีความเสี่ยง

apidog-test

1. จำลองเพย์โหลดเว็บฮุก

สร้างเพย์โหลดจำลองและส่งไปยัง webhook endpoint ของคุณ:

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

2. การแยกสภาพแวดล้อม

ตั้งค่า Environment แยกระหว่าง Sandbox และ Production:

# 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 สำเร็จแล้ว', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('บันทึกรหัสธุรกรรมแล้ว', () => {
  // ตรวจสอบบันทึกหรือฐานข้อมูลของคุณ
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})
Enter fullscreen mode Exit fullscreen mode

ทดสอบเว็บฮุก Braintree ด้วย Apidog - ฟรี

ข้อผิดพลาดทั่วไปและการแก้ไข

ถูกปฏิเสธโดยผู้ประมวลผล

สาเหตุ: ธนาคารปฏิเสธธุรกรรม

วิธีแก้ไข: แสดงข้อผิดพลาดทั่วไปให้ลูกค้าทราบและแนะนำให้ลองใช้บัตรอื่น บันทึก processorResponseCode เพื่อ debug

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // ธนาคารปฏิเสธ
    return res.status(400).json({
      error: 'ธนาคารของคุณปฏิเสธการทำธุรกรรมนี้ โปรดลองใช้บัตรอื่น'
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

ถูกปฏิเสธโดย Gateway

สาเหตุ: ระบบป้องกันการฉ้อโกงของ 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 webhooks สาเหตุเช่น วิธีการชำระเงินหมดอายุ ผู้ออกบัตรบล็อกธุรกรรม หรือยอดเงินไม่พอ

ธุรกรรมซ้ำซ้อน

สาเหตุ: ลูกค้าคลิก “ชำระเงิน” สองครั้ง หรือโค้ดของคุณพยายามซ้ำ

วิธีแก้ไข: ใช้ 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 การใช้ Braintree มักจะง่ายกว่าการใช้ Stripe + PayPal แยกกัน

กรณีใช้งานจริง

แพลตฟอร์มสมัครสมาชิก SaaS: เครื่องมือจัดการโปรเจกต์ใช้ Braintree สำหรับการสมัครสมาชิกรายเดือน เว็บฮุกจัดการการชำระเงินที่ล้มเหลว (บัตรหมดอายุ, ยอดเงินไม่พอ) โดยการส่งอีเมลแจ้งเตือน ผู้ใช้สามารถอัปเดตวิธีการชำระเงินได้โดยไม่ต้องติดต่อฝ่ายสนับสนุน

การชำระเงินใน Marketplace: แพลตฟอร์มฟรีแลนซ์แบ่งการชำระเงินระหว่างค่าธรรมเนียมแพลตฟอร์มและฟรีแลนซ์ บัญชีร้านค้าและการตั้งค่า sub-merchant ของ Braintree จัดการความซับซ้อนนี้ได้

อีคอมเมิร์ซพร้อม PayPal: ร้านค้าออนไลน์รองรับบัตรเครดิตและ PayPal API แบบรวมของ Braintree หมายถึงการรวมระบบครั้งเดียวก็สามารถจัดการได้ทั้งสองอย่าง ออบเจกต์ลูกค้าเดียวกันสามารถใช้ได้กับวิธีการชำระเงินต่างๆ

บทสรุป

สิ่งที่คุณได้เรียนรู้:

  • SDK ของ Braintree จัดการการประมวลผลการชำระเงินฝั่งเซิร์ฟเวอร์
  • โทเค็นไคลเอนต์อนุญาตการสื่อสารของส่วนหน้า
  • การขายธุรกรรมจะเรียกเก็บเงินจากบัตรเครดิตและ PayPal
  • การสมัครสมาชิกจัดการการเรียกเก็บเงินแบบประจำ
  • เว็บฮุกแจ้งให้คุณทราบเกี่ยวกับเหตุการณ์การชำระเงิน
  • ทดสอบอย่างละเอียดด้วย Apidog ก่อนใช้งานจริง

คำถามที่พบบ่อย

payment method nonce คืออะไร?

Nonce คือโทเค็นแบบใช้ครั้งเดียวที่แสดงถึงวิธีการชำระเงิน ส่วนหน้าจะสร้างขึ้นหลังจากที่ลูกค้าป้อนรายละเอียดบัตร เซิร์ฟเวอร์ของคุณใช้ nonce เพื่อเรียกเก็บเงินจากบัตร Nonces จะหมดอายุภายใน 3 ชั่วโมง

ความแตกต่างระหว่างการอนุมัติ (authorization) และการชำระ (settlement) คืออะไร?

การอนุมัติคือการจองยอดเงินในบัตร การชำระคือการเรียกเก็บเงินจากบัตรจริง โดยปกติแล้ว 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 สำหรับการตั้งค่าหลายสกุลเงิน

ฉันควรใช้หมายเลขบัตรทดสอบใดบ้าง?

Braintree มีบัตรทดสอบใน sandbox:

  • 4111111111111111 - Visa (สำเร็จ)
  • 4000111111111115 - Visa (ปฏิเสธ)
  • 5555555555554444 - Mastercard (สำเร็จ)
  • 378282246310005 - Amex (สำเร็จ)

ฉันจะจัดการกับข้อพิพาท/การเรียกเก็บเงินคืนได้อย่างไร?

รอฟัง webhook สำหรับ dispute_opened, dispute_won และ dispute_lost ให้หลักฐานผ่านแผงควบคุม Braintree บันทึกทุกอย่าง - การสื่อสารกับลูกค้า, การยืนยันการจัดส่ง, ข้อกำหนดและเงื่อนไขการบริการ

ฉันสามารถเก็บหมายเลขบัตรเครดิตได้หรือไม่?

ไม่ได้ การปฏิบัติตาม PCI ห้ามไม่ให้จัดเก็บหมายเลขบัตรดิบ ให้จัดเก็บ payment method tokens แทน Braintree จัดการขอบเขต PCI

3D Secure คืออะไร?

3D Secure เพิ่มขั้นตอนการยืนยันเพิ่มเติมสำหรับธุรกรรมที่ไม่มีบัตรอยู่จริง Braintree รองรับ เปิดใช้งานในแผงควบคุมและจัดการการตอบกลับ authentication_required:

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

การคืนเงินใช้เวลานานเท่าใด?

โดยทั่วไปการคืนเงินจะใช้เวลาดำเนินการ 3-5 วันทำการ ระยะเวลาขึ้นอยู่กับธนาคารของลูกค้า คุณจะได้รับ webhook transaction_refunded เมื่อดำเนินการเสร็จสมบูรณ์

Top comments (0)