Blog

Braintree API の使い方

Ashley Innocent

Ashley Innocent

24 3月 2026

Braintree API の使い方

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

要約

Braintree API は、クレジットカード、PayPal、Venmo、およびデジタルウォレットからの支払いを処理します。サーバーサイドSDK（Node、Python、Rubyなど）を介して統合し、フロントエンドのセキュリティのためにクライアントトークンを作成し、トランザクション、返金、サブスクリプションを処理します。テストには、Apidog を使用してWebhookペイロードを検証し、本番環境に移行する前にサンドボックスデータに対して統合をテストします。

はじめに

Braintree は、年間数十億ドルもの支払いを処理しています。Uber、Airbnb、GitHub などの企業の決済処理を担当しています。このプラットフォームは、クレジットカード、PayPal、Venmo、Apple Pay、Google Pay、ACH 送金を処理します。

決済APIは、他のAPIとは異なります。製品カタログでの間違いは、迷惑なだけです。決済での間違いは、実際のお金がかかり、顧客の信頼を損ないます。正しく処理する必要があります。

Braintree は、Drop-in UI（構築済み決済フォーム）とCustom UI（完全な制御）の2つの統合パスを提供します。どちらも、実際の決済処理には同じサーバーサイドAPIを使用します。このガイドでは、顧客が「支払う」をクリックした後に発生するサーバーサイドの作業について説明します。

💡
決済統合を構築している場合、Apidog はWebhookハンドラーのテストと決済応答の検証に役立ちます。Apidog を使用すると、Braintree のWebhookをローカルでモックできるため、実際のトランザクションを処理する前に、コードが成功、失敗、およびエッジケースを正しく処理することを確認できます。
button

Apidog で Braintree のWebhookを無料でテスト

Braintree のセットアップ

Braintree アカウントの作成

braintreepayments.com（Braintree は現在 PayPal Enterprise Payments です）にアクセスし、サンドボックスアカウントを作成します。次のものが得られます。

これらを安全に保管してください。秘密鍵はパスワードのようなものです。Git にコミットしないでください。

APIキーがハイライト表示された Braintree のダッシュボード。

SDKのインストール

Braintree は、ほとんどの言語向けにサーバーサイドSDKを提供しています。

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

ゲートウェイの初期化:

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 またはカスタム統合を初期化します。

支払いの処理

支払いフロー

  1. フロントエンドが支払い方法ノンスをサーバーに送信する
  2. サーバーがノンスを使用してトランザクションを作成する
  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
    })
  }
})

保存された支払い方法での請求

最初のトランザクションの後、支払い方法を将来の使用のために保存できます。

// 支払い方法で顧客を作成
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 を処理します。フロントエンドが 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: '月額プレミアム',
  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

Webhook は、トランザクションイベントについてサーバーに通知します。これは、サブスクリプションや紛争にとって非常に重要です。

Webhookエンドポイントの作成

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

Braintree でWebhookを登録

Braintree コントロールパネルで、「設定」→「Webhook」に移動し、エンドポイントURLを追加します。開発中は、ngrokのようなトンネリングサービスを使用して、ローカルでWebhookを受信します。

Apidog でのテスト

決済APIは徹底的なテストが必要です。本番データに頼ることはできません。Apidog はリスクなしでテストするのに役立ちます。

Webhookをテストしている Apidog のスクリーンショット。

1. Webhookペイロードのモック

Braintree が Webhook を送信するのを待つ代わりに、モックペイロードを作成します。

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

これらを Webhook エンドポイントに送信し、コードがそれらを正しく処理することを確認します。

2. 環境の分離

別々の環境を作成します。

# サンドボックス
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# 本番環境
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production

3. Webhook応答の検証

pm.test('Webhook は正常に処理されました', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('トランザクションIDがログに記録されました', () => {
  // ログまたはデータベースを確認してください
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Apidog で Braintree のWebhookを無料でテスト

一般的なエラーと修正

プロセッサが拒否しました

原因: 銀行がトランザクションを拒否しました。

修正: これは、資金不足や不正防止フィルターが原因であることがよくあります。顧客に一般的なエラーを表示し、別のカードを試すように提案してください。デバッグのために processorResponseCode をログに記録してください。

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // 銀行が拒否しました
    return res.status(400).json({
      error: '銀行がこの取引を拒否しました。別のカードをお試しください。'
    })
  }
}

ゲートウェイが拒否しました

原因: Braintree の不正防止フィルターがトランザクションをブロックしました。

修正: gatewayRejectionReason を確認してください。

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV不一致
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // 住所確認に失敗しました
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // 高度な不正防止ツールがブロックしました
}

決済の失敗

原因: 承認後にトランザクションを決済できませんでした。

修正: transaction_settlement_declined Webhook を監視します。一般的な原因:

重複トランザクション

原因: 顧客が「支払う」を2回クリックしたか、コードが再試行しました。

修正: 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 の両方が必要な場合、Stripe + PayPal を個別に統合するよりも Braintree の方が簡単なことがよくあります。

実世界でのユースケース

SaaS サブスクリプションプラットフォーム。 プロジェクト管理ツールは、月額サブスクリプションに Braintree を使用しています。Webhook は、支払い失敗（カードの有効期限切れ、資金不足）をメール通知で処理します。ユーザーは、サポートに連絡することなく支払い方法を更新できます。

マーケットプレイス決済。 フリーランスプラットフォームは、プラットフォーム手数料とフリーランサーの間で支払いを分割します。Braintree のマーチャントアカウントとサブマーチャント設定が複雑さを処理します。

PayPal を使用した Eコマース。 オンラインストアでは、クレジットカードと PayPal を提供しています。Braintree の統合APIは、1つの統合で両方を処理できることを意味します。同じ顧客オブジェクトが支払い方法全体で機能します。

まとめ

ここで学んだこと:

button

よくある質問

支払い方法ノンスとは何ですか？

ノンスは、支払い方法を表す使い捨てのトークンです。顧客がカード情報を入力した後、フロントエンドがこれを生成します。サーバーはノンスを使用してカードに請求します。ノンスは3時間後に期限切れになります。

認証と決済の違いは何ですか？

認証は、カード上の資金を確保します。決済は実際にカードに請求します。デフォルトでは、Braintree は自動決済します。予約注文の場合、まず認証し、発送時に決済します。

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

// 後で決済
await gateway.transaction.submitForSettlement('transaction_id')

通貨の扱い方は？

各 Braintree マーチャントアカウントにはデフォルトの通貨があります。多通貨に対応するには、複数のマーチャントアカウントが必要です。多通貨設定については Braintree サポートにご確認ください。

どのテストカード番号を使えばよいですか？

Braintree はサンドボックスでテストカードを提供しています。

紛争/チャージバックはどのように処理すればよいですか？

dispute_opened、dispute_won、および dispute_lost の各Webhookをリッスンしてください。Braintree コントロールパネルを通じて証拠を提出します。顧客とのやり取り、配送確認、利用規約など、すべてを文書化してください。

クレジットカード番号を保存できますか？

いいえ。PCI DSS への準拠により、生のカード番号の保存は禁止されています。代わりに支払い方法トークンを保存してください。Braintree が PCI 範囲を処理します。

3Dセキュアとは何ですか？

3Dセキュアは、カード非提示取引に対する追加の認証手順を追加します。Braintree はこれをサポートしています。コントロールパネルで有効にし、authentication_required 応答を処理します。

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

返金にはどのくらいかかりますか？

返金は通常、3〜5営業日で処理されます。タイミングは顧客の銀行によって異なります。完了すると transaction_refunded Webhook を受信します。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード