วิธีใช้ Braintree API

TL;DR

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

บทนำ

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 โดยเด็ดขาด

ติดตั้ง SDK

Braintree มี SDK ฝั่งเซิร์ฟเวอร์สำหรับภาษาโปรแกรมส่วนใหญ่:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

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

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

ก่อนที่จะแสดงแบบฟอร์มการชำระเงิน ให้สร้างโทเค็นไคลเอนต์ สิ่งนี้จะอนุญาตให้ส่วนหน้าสื่อสารกับ Braintree ได้

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

ส่วนหน้าจะใช้โทเค็นนี้เพื่อเริ่มต้น Drop-in UI หรือการรวมระบบแบบกำหนดเอง

การประมวลผลการชำระเงิน

ขั้นตอนการชำระเงิน

ส่วนหน้าส่ง payment method nonce ไปยังเซิร์ฟเวอร์ของคุณ
เซิร์ฟเวอร์สร้างธุรกรรมโดยใช้ nonce
Braintree ประมวลผลการชำระเงิน
เซิร์ฟเวอร์ได้รับการตอบกลับว่าสำเร็จ/ล้มเหลว
คุณดำเนินการตามคำสั่งซื้อหรือแสดงข้อผิดพลาด

เรียกเก็บเงินจากบัตรเครดิต

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

เรียกเก็บเงินด้วยวิธีการชำระเงินที่บันทึกไว้

หลังจากการทำธุรกรรมครั้งแรก คุณสามารถบันทึกวิธีการชำระเงินไว้ใช้ในอนาคตได้:

// สร้างลูกค้าด้วยวิธีการชำระเงิน
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
  }
})

ธุรกรรม PayPal

Braintree จัดการ PayPal ในลักษณะเดียวกับบัตร ส่วนหน้าจะได้รับ nonce จาก PayPal คุณก็เรียกเก็บเงินได้:

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

การคืนเงินและการยกเลิก

การคืนเงินเต็มจำนวน

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

if (result.success) {
  console.log('คืนเงินแล้ว:', result.transaction.id)
}

การคืนเงินบางส่วน

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

if (result.success) {
  console.log('ดำเนินการคืนเงินบางส่วนแล้ว')
}

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

การยกเลิกจะหยุดธุรกรรมก่อนที่จะมีการชำระ ใช้สำหรับยอดชำระที่ได้รับอนุมัติแต่ยังไม่ได้บันทึก:

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

if (result.success) {
  console.log('ธุรกรรมถูกยกเลิก')
}

ผังสถานะธุรกรรม

ได้รับอนุญาต → ส่งเพื่อชำระ → ชำระแล้ว
                    ↓
                  ยกเลิกแล้ว
                    
ชำระแล้ว → คืนเงินแล้ว

การสมัครสมาชิกและการเรียกเก็บเงินแบบประจำ

Braintree จัดการการสมัครสมาชิกสำหรับการชำระเงินแบบประจำ

สร้างแผน

อันดับแรก ให้สร้างแผนในแผงควบคุม Braintree หรือผ่าน API:

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

สร้างการสมัครสมาชิก

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

if (result.success) {
  console.log('สร้างการสมัครสมาชิกแล้ว:', result.subscription.id)
}

ยกเลิกการสมัครสมาชิก

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

if (result.success) {
  console.log('ยกเลิกการสมัครสมาชิกแล้ว')
}

อัปเดตการสมัครสมาชิก

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

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

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

สร้าง 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')
    }
  )
})

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

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

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

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

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

แทนที่จะรอ Braintree ส่งเว็บฮุก ให้สร้างเพย์โหลดจำลอง:

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

ส่งสิ่งเหล่านี้ไปยัง webhook endpoint ของคุณ และตรวจสอบว่าโค้ดของคุณจัดการได้อย่างถูกต้อง

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

สร้างสภาพแวดล้อมที่แยกจากกัน:

# 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. ตรวจสอบการตอบกลับเว็บฮุก

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

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

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

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

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

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

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

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

สาเหตุ: ระบบป้องกันการฉ้อโกงของ Braintree บล็อกธุรกรรม

วิธีแก้ไข: ตรวจสอบ gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV ไม่ตรงกัน
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // การยืนยันที่อยู่ล้มเหลว
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // เครื่องมือป้องกันการฉ้อโกงขั้นสูงบล็อกไว้
}

ข้อผิดพลาดในการชำระ

สาเหตุ: ธุรกรรมไม่สามารถชำระได้หลังจากได้รับอนุญาต

วิธีแก้ไข: ตรวจสอบ transaction_settlement_declined webhooks สาเหตุทั่วไป:

วิธีการชำระเงินหมดอายุระหว่างการอนุมัติและการชำระ
ผู้ออกบัตรบล็อกธุรกรรม
ยอดเงินไม่พอปรากฏขึ้น

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

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

วิธีแก้ไข: ใช้พารามิเตอร์ orderId Braintree จะปฏิเสธธุรกรรมที่ซ้ำกันภายในกรอบเวลาที่กำหนด:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // ป้องกันการซ้ำกัน
  options: {
    submitForSettlement: true
  }
})

ทางเลือกและการเปรียบเทียบ

คุณสมบัติ	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')

ฉันจะจัดการกับสกุลเงินได้อย่างไร?

บัญชีร้านค้า 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
  }
})

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

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