決済方法ハンドラー実装¶

概要¶

Vendureに複数の決済方法（Payment Method Handler）を実装し、B2B ECサイトで必要な決済手段を提供します。

実装済みの決済方法：

売掛決済 (CREDIT_SALE) - 掛売り決済、月次請求対応
代引き決済 (CASH_ON_DELIVERY) - 手数料自動計算機能付き
銀行振込/前入金 (BANK_TRANSFER) - 請求書PDF発行対応
SB Paymentクレジットカード (sb-payment-link) - 既存実装、詳細はこちら

実装場所¶

すべての決済ハンドラーは packages/plugins/src/payment-handlers/ に実装されています：

credit-sale-handler.ts - 売掛決済ハンドラー
cash-on-delivery-handler.ts - 代引き決済ハンドラー
bank-transfer-handler.ts - 銀行振込/前入金ハンドラー

売掛決済ハンドラー（Credit Sale）¶

機能¶

SMILEシステムとの連携確認（将来実装予定）
与信限度額チェック（将来実装予定）
月次請求への自動登録（将来実装予定）
即座にAuthorized状態にする（実際の決済は月次請求時に処理）

コード¶

ハンドラーコード: CREDIT_SALE
表示名: 売掛決済（掛売り）

設定¶

現在、追加設定パラメータはありません（args: {}）。

使用方法¶

Vendure Dashboard → Settings → Payment Methods
新しい決済方法を作成
Handler で CREDIT_SALE を選択
有効化して保存

実装詳細¶

export const CreditSaleHandler = new PaymentMethodHandler({
  code: PAYMENT_METHODS.CREDIT_SALE,
  description: [
    { languageCode: LanguageCode.ja, value: '売掛決済（掛売り）' },
    { languageCode: LanguageCode.en, value: 'Credit Sale' },
  ],
  args: {},
  // ...
});

将来実装予定¶

SMILEシステムとの連携確認
与信限度額チェック
月次請求への自動登録

代引き決済ハンドラー（Cash on Delivery）¶

機能¶

代引き手数料の自動計算・加算
率ベース手数料計算（デフォルト5%）
固定手数料の追加
最小・最大手数料の適用
直送モード時の自動非表示（既存のdirectShippingPaymentEligibilityCheckerで制御）

コード¶

ハンドラーコード: CASH_ON_DELIVERY
表示名: 代引き決済

設定パラメータ¶

Vendure Dashboard上で以下のパラメータを設定できます：

パラメータ	型	デフォルト値	説明
`feeRate`	float	0.05	注文金額に対する手数料率（例: 0.05 = 5%）
`fixedFee`	int	0	固定で加算される手数料（円）
`minFee`	int	300	最小手数料（円）
`maxFee`	int	-	最大手数料（円、未設定の場合は上限なし）

手数料計算ロジック¶

手数料 = 固定手数料 + (注文金額 × 手数料率)
手数料 = max(手数料, 最小手数料)  // 最小手数料の適用
手数料 = min(手数料, 最大手数料)  // 最大手数料の適用（設定されている場合）

使用例¶

例1: 基本設定（デフォルト）

注文金額: 10,000円
手数料率: 5%
最小手数料: 300円
計算結果: max(10,000 × 0.05, 300) = 500円

例2: 小額注文（最小手数料適用）

注文金額: 3,000円
手数料率: 5%
最小手数料: 300円
計算結果: max(3,000 × 0.05, 300) = 300円

例3: 高額注文（最大手数料適用）

注文金額: 100,000円
手数料率: 5%
最大手数料: 5,000円
計算結果: min(100,000 × 0.05, 5,000) = 5,000円

使用方法¶

Vendure Dashboard → Settings → Payment Methods
新しい決済方法を作成
Handler で CASH_ON_DELIVERY を選択
手数料設定を入力：
手数料率: 0.05（5%）
固定手数料: 0円
最小手数料: 300円
最大手数料: 5000円（任意）
有効化して保存

注意事項¶

玄関先でのクレジットカード決済（タッチ決済）は配送業者側の機能であり、Vendure側の処理には影響しません
ストア側では通常の代引き決済として扱います（現金決済とカード決済の区別は不要）

銀行振込/前入金ハンドラー（Bank Transfer/Prepayment）¶

機能¶

前入金確認待ち状態の管理
請求書PDF自動発行（将来実装予定）
入金確認後の注文確定
銀行振込と前入金を統合（BANK_TRANSFERで統一）

コード¶

ハンドラーコード: BANK_TRANSFER
表示名: 銀行振込/前入金

設定パラメータ¶

Vendure Dashboard上で以下のパラメータを設定できます：

パラメータ	型	デフォルト値	説明
`requiresInvoice`	boolean	true	前入金の場合、請求書PDFを自動発行する

決済フロー¶

決済作成時 (createPayment)
入金確認待ち状態（PENDING_PAYMENT）で作成
請求書PDF発行が必要な場合は発行（将来実装）
入金確認後 (settlePayment)
管理者が入金確認を行った後に呼ばれる
状態を PAID（入金確認済み）に更新
キャンセル時 (cancelPayment)
状態を CANCELLED に更新

使用方法¶

Vendure Dashboard → Settings → Payment Methods
新しい決済方法を作成
Handler で BANK_TRANSFER を選択
請求書発行設定を選択：
請求書発行が必要: true（前入金の場合）
有効化して保存

将来実装予定¶

請求書PDF自動発行機能

Vendure設定への統合¶

すべてのハンドラーは apps/vendure-server/src/vendure-config.shared.ts に登録されています：

paymentOptions: {
  paymentMethodHandlers: [
    dummyPaymentHandler,
    // SB Payment Link Handler will be registered via plugin DI
    CreditSaleHandler,
    CashOnDeliveryHandler,
    BankTransferHandler,
  ],
  // ...
}

決済方法制御（Eligibility Checker）¶

既存の決済方法制御機能を活用できます：

顧客ステータス制御 (customerStatusPaymentEligibilityChecker)
顧客ステータスに応じた決済方法の表示/非表示制御
直送モード制御 (directShippingPaymentEligibilityChecker)
直送モード時の決済方法制限（代引きは自動非表示）
顧客グループ制御 (paymentGroupEligibilityChecker)
顧客グループに応じた決済方法の制御
注文金額範囲制御 (orderTotalRangePaymentEligibilityChecker)
注文金額の範囲で決済方法の表示/非表示制御

詳細は apps/vendure-server/src/plugins/payment-eligibility/checkers.ts を参照してください。

テスト¶

各決済ハンドラーのテストは packages/plugins/src/payment-handlers/payment-handlers.spec.ts に実装されています。

テスト実行¶

# プラグインのテストを実行
pnpm --filter @ritsubi/plugins test

テスト内容¶

各ハンドラーの createPayment メソッドのテスト
各ハンドラーの settlePayment メソッドのテスト
各ハンドラーの cancelPayment メソッドのテスト
代引き手数料計算のテスト（最小・最大手数料の適用確認を含む）

実装履歴¶

2025-01-XX: 売掛決済、代引き決済、銀行振込/前入金ハンドラーの実装完了
2025-01-XX: PREPAYMENT定数を削除し、BANK_TRANSFERで統一

決済方法ハンドラー実装¶

概要¶

実装場所¶

売掛決済ハンドラー（Credit Sale）¶

機能¶

コード¶

設定¶

使用方法¶

実装詳細¶

将来実装予定¶

代引き決済ハンドラー（Cash on Delivery）¶

機能¶

コード¶

設定パラメータ¶

手数料計算ロジック¶

使用例¶

使用方法¶

注意事項¶

銀行振込/前入金ハンドラー（Bank Transfer/Prepayment）¶

機能¶

コード¶

設定パラメータ¶

決済フロー¶

使用方法¶

将来実装予定¶

Vendure設定への統合¶

決済方法制御（Eligibility Checker）¶

テスト¶

テスト実行¶

テスト内容¶

関連ドキュメント¶

実装履歴¶