決済トランザクション
決済・返金・チャージバックなどの取引記録を管理する Payment Transaction について
Payment Transaction (決済トランザクション)APIは、PAY.JP システム内で発生する決済関連のトランザクション（取引記録）を表すリソースです。支払い、返金、チャージバックなど、売上に影響を与えるすべての取引を記録し、Term (集計区間)APIと関連付けて管理します。
契約内容や支払い方法によって手数料率は異なるため、Payment TransactionAPI API を使用して実際に適用された料率と手数料額を取得できます。
決済トランザクションとは
Payment Transaction は以下の役割を担います。
| 役割 | 説明 |
|---|---|
| 支払いの記録 | 支払いが成功した際に決済トランザクションを自動生成します |
| 返金の記録 | 返金が成功した際に返金トランザクションを生成します（マイナス金額） |
| 手数料計算 | 各取引に対する手数料率と手数料額を記録します |
| 集計区間との関連付け | 集計区間（Term）と紐付けて売上集計を可能にします |
| 売上明細の基礎データ | 取引明細（Statement）として最終的な請求・振込処理の元データとなります |
他のオブジェクトとの関係
Payment Transaction は売上集計の流れの中で重要な役割を果たします。
| オブジェクト | 説明 |
|---|---|
| Payment FlowAPI / RefundAPI | 支払い・返金処理の本体。成功すると Payment Transaction が生成される |
| Payment TransactionAPI | 取引の記録。金額と手数料を含む |
| TermAPI | 集計区間（締めサイクル）。Payment Transaction が所属する期間を表す |
| StatementAPI | Term 締め時に生成される取引明細。Payment Transaction を元に作成 |
| BalanceAPI | 最終的な残高。Statement から集計される |
詳しくは 締めサイクルと売上集計 をご覧ください。
トランザクションの種類
Payment Transaction には以下の種類（type）があります。
| type | 説明 | 金額 |
|---|---|---|
payment | 支払い | 正の値 |
refund | 返金 | 負の値 |
chargeback | チャージバック | 負の値 |
chargeback_cancel | チャージバック取消 | 正の値 |
Payment Flow からの生成
支払いが成功（PaymentFlow.status=succeeded）すると、決済トランザクションが自動的に生成されます。
手数料の記録
支払い時の手数料は、支払い方法と契約内容に応じて自動的に計算され、Payment Transaction に記録されます。
決済トランザクションを取得することで、各取引に適用された手数料率（fee_rate）と手数料額（fee）を確認できます。
Refund からの生成
Refund (返金)APIが成功（Refund.status=succeeded）すると、マイナス金額の決済トランザクションが生成されます。
返金時の手数料
PAY.JP では、返金時に手数料の一部が自動的に返金されます。返金額に応じて手数料が再計算され、差額が返金される仕組みです。
返金トランザクションの Payment Transaction には以下のように記録されます。
| フィールド | 説明 | 値 |
|---|---|---|
amount | 返金額 | マイナス値 |
fee | 返金された手数料 | マイナス値 |
type | トランザクション種別 | "refund" |
例: 10,000円の支払いに対して 3,000円を返金した場合、返金トランザクションには返金額と返金された手数料の両方が記録されます。
部分返金について
複数回に分けて部分返金を行う場合も、各返金ごとに Payment Transaction が生成され、それぞれの返金額と返金手数料が記録されます。
よくあるユースケース
売上レポートの作成
特定期間の売上を確認したい場合、該当する Term の Payment Transaction を取得することで詳細なレポートを作成できます。
活用例
- 期間内の支払い総額と返金総額を集計
- 手数料の合計を確認
- 純売上（支払い額 - 返金額 - 手数料）を計算
- 月次・四半期・年次の売上推移を分析
Term ID を指定して Payment Transaction を取得することで、締めサイクルごとの取引詳細を確認できます。
支払い方法別の売上分析
Payment Transaction の payment_method_type フィールドを使用して、支払い方法別の売上を分析できます。
活用例
- クレジットカード、PayPay、Apple Pay など支払い方法ごとの売上比率を把握
- 支払い方法別の支払い件数を確認
- どの支払い方法が顧客に人気かを分析
- 支払い方法別の返金率を算出
API のフィルター機能（payment_method_type）を使用して、特定の支払い方法のトランザクションのみを取得できます。
返金履歴の確認
返金処理を行った際の詳細を確認したい場合、type=refund でフィルターして返金トランザクションを取得できます。
活用例
- 特定期間の返金総額を確認
- 返金時に返金された手数料を確認
- どの Payment Flow に対する返金かを
resource_idで確認 - 返金率の推移を分析
取引明細の詳細確認
Statement（取引明細）や Balance（残高）に含まれる取引の詳細を確認したい場合、Term ID を指定して Payment Transaction を取得することで、売上集計の内訳を詳しく調べることができます。
活用例
- Statement（取引明細）に記載された金額の内訳を確認
- 特定の締めサイクルでどのような取引があったかを把握
- 手数料の内訳を確認
- 振込額の計算根拠を確認
関連リソース
- 締めサイクルと売上集計 - Term、Statement、Balance との関係について
- Payment Flow API の仕組み - Payment Flow について