# The Payment Records API

Stripe 上でも Stripe 以外でも、決済履歴を統一して管理できます。

[Payment Records](https://docs.stripe.com/api/payment-record.md) API を使用して、すべての支払いの台帳を管理することができます。Stripe を通じて決済処理している場合 (Stripe での支払い) や、サードパーティーの決済代行業者を利用している場合 (Stripe 外での支払い) は、この API を使用することで支払いの履歴をまとめて記録できます。

Payment Records API を使用して、以下の操作が可能です。

- サードパーティーの決済代行業者を通じて支払いを行い、その結果を Stripe に報告することで、サブスクリプションや Radar などのプロダクトの全機能を利用できるようになります。
- キャプチャーごとに追跡できる高度な決済フロー (マルチキャプチャーなど) を作成する。
- サードパーティーおよびパートナーが開始した支払い (Stripe が指示したカード取引を含む) を追跡する。

## PaymentIntents との関係

[Payment Intents](https://docs.stripe.com/api/payment_intents.md) API を使用して、さまざまな決済フローを管理することができます。ただし、高度なユースケースでは、より緻密に記録された支払い履歴を要求されることがほとんどです。

アプリケーションが Stripe で PaymentIntents を使用して支払いを受け付け、さらに Stripe 外でも別の決済代行業者を介して支払いを受け付けている場合、PaymentRecords を完全な記録システムとして使用できます。[Orchestration](https://docs.stripe.com/payments/orchestration.md) を有効にしている場合:

- **Stripe での支払い**:Stripe は、PaymentIntent ごとに PaymentRecord を自動で作成します。
- **Stripe 外での支払い**:Payment Records API を使用して支払いデータを報告することで、PaymentRecords を手動で作成できます。

PaymentRecords を利用すると、Stripe プロダクト間の相互運用が可能になります。[サブスクリプション](https://docs.stripe.com/subscriptions.md) (Smart Retries を使用) などのプロダクトや[外部で支払われた請求書](https://support.stripe.com/questions/marking-an-invoice-paid-out-of-band)では、支払い結果を追跡するためのコアツールとして PaymentRecords を使用します。

Orchestration が有効になっている PaymentIntent に関連付けられている PaymentRecord を取得するには、以下の手順に従います。

```curl
curl https://api.stripe.com/v1/payment_records/{{PAYMENTINTENT_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

## PaymentRecords の作成・管理

PaymentRecord は支払いの記録であり、関連するすべての試行や結果が含まれます。これは、支払いのライフサイクルとステータスを把握するための主要な参照情報として機能します。

各 PaymentRecord は、支払いを処理するための試行情報を示す [PaymentAttemptRecords](https://docs.stripe.com/api/payment-attempt-record.md) を複数持ちます。この構造が、成功、再試行、失敗の追跡を可能にしています。

各 PaymentAttemptRecord には、試行内の 1 つのイベント (開始、認証、オーソリ、キャプチャーなど) の詳細を示す複数の PaymentAttemptRecordEntries を含めることができます。これらをまとめると追記専用のイベントログになり、決済試行のライフサイクル全体を再構築するために使用できます。
PaymentAttemptRecords と PaymentAttemptRecordEntries を使用した PaymentRecord のサンプル (See full diagram at https://docs.stripe.com/payments/payment-records)
### 新しい支払いの報告

Stripe 外での支払いを[報告](https://docs.stripe.com/api/payment-record/report-payment/report.md)するには、金額、決済手段、決済代行業者、関連するタイムスタンプなど、取引に関する詳細情報を用いて PaymentRecord を作成します。Stripe は、提供されたデータを使用して、関連する PaymentAttemptRecord を自動的に作成します。このデータは、レスポンスで `latest_payment_attempt_record` と表示されています。

```curl
curl https://api.stripe.com/v1/payment_records/report_payment \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "amount_requested[currency]=usd" \
  -d "amount_requested[value]=1000" \
  -d initiated_at=1730253453 \
  -d outcome=guaranteed \
  -d "guaranteed[guaranteed_at]=1746572320" \
  -d "payment_method_details[payment_method]={{PAYMENTMETHOD_ID}}" \
  -d "processor_details[type]=custom"
```

### 失敗した支払い試行の報告

失敗した支払い試行を報告することで、Stripe は決済フロー全体を把握し、他のプロダクト ([Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) など) を機能させることができます。支払いが失敗した場合は、既存の PaymentRecord ID を参照し、その失敗時刻を渡すことで[失敗を報告](https://docs.stripe.com/api/payment-record/report-payment-attempt-failed/report.md)します。

```curl
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt_failed \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d failed_at=1730253453
```

### 失敗した支払いの再試行

ユーザーが失敗した支払いを複数回再試行することがあります。その際、同じ PaymentRecord を使用して、[新たな支払い試行を報告](https://docs.stripe.com/api/payment-record/report-payment-attempt/report.md)できます。再試行では、同一または別の決済手段と決済代行業者を利用することが可能です。

```curl
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d initiated_at=1730253825 \
  -d "payment_method_details[payment_method]={{PAYMENTMETHOD_ID}}"
```

### 返金を報告する

決済が正常に処理されたが後で返金された (全額または一部) 場合は、[返金を報告](https://docs.stripe.com/api/payment-record/report-refund/report.md)して、正確な決済記録を維持する必要があります。これにより、Stripe は決済代行業者を通じて処理された返金を含め、決済ライフサイクル全体の把握を確実にします。

```curl
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_refund \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "processor_details[type]=custom" \
  -d "processor_details[custom][refund_reference]=ref_123456" \
  -d outcome=refunded \
  -d "refunded[refunded_at]=1730253825" \
  -d "amount[value]=1000" \
  -d "amount[currency]=usd"
```

`amount` を指定しない場合、保証金額の全額が返金されます。全額が返金されるまで、同じ PaymentRecord で複数の一部返金をレポートできます。

## 支払い状況の把握

PaymentRecord は、ダッシュボードやレポートシステムに使用できます。レコードは 1 つしかないため、他の決済代行業者と Stripe との間でモデルの差異を調整する必要がなくなります。

### PaymentRecord の取得

PaymentRecord は、ID を使用して取得できます。オーケストレーションされた支払いの場合、これは PaymentIntent レスポンスで返されます。過去に行われた支払いについては、PaymentIntent の ID を使用して PaymentRecord を取得することもできます。

最新の PaymentAttemptRecord は PaymentRecord で取得できます。また、[Payment Attempt Records](https://docs.stripe.com/payments/payment-records.md#retrieve-payment-attempt-record) API を使用して取得することも可能です。Charges API を使用する支払い履歴については、Charge ID を使用して PaymentAttemptRecord を取得します。

```curl
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

```json
{
  "processor_details": {
    "type": "processor_a",
  },
  "latest_payment_attempt_record": "{{PAYMENT_ATTEMPT_RECORD_ID}}",
  "amount_guaranteed": {
    "value": 10000,
    "currency": "usd",
  },
  "payment_method_details": {
    "payment_method": "{{PAYMENT_METHOD_ID}}",
    "type": "card",
  },
}
...
```

### PaymentAttemptRecord の取得

複数回支払いを試みた場合 (たとえば、支払いが別の決済代行業者で失敗したものの、Stripe での再試行が成功した場合)、PaymentRecord の `latest_payment_attempt_record` には最新の試行が表示されます。PaymentAttemptRecord をクエリすると、すべての試行を表示できます。

```curl
curl -G https://api.stripe.com/v1/payment_attempt_records \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_record={{PAYMENT_RECORD_ID}}
```

```json
{
  "object": "list",
  "data": [{
    "id": "par_124",
    "amount_requested": 10000,
    "amount_guaranteed": 10000,
    "amount_failed": 0,
  },
  {
    "id": "par_123",
    "amount_requested": 10000,
    "amount_guaranteed": 0,
    "amount_failed": 10000,
  }]
}
...
```

### PaymentAttemptRecordEntry を取得する

> 現在、PaymentAttemptRecordEntries はプレビューユーザーに限定されています。ご利用をご希望の際は、Stripe アカウントの担当者または営業部門にお問い合わせください。

Stripe は、`PaymentAttemptRecordEntry` オブジェクトが作成されるたびに (payment_attempt_record_entry.initiated など)、そのオブジェクトを含む Webhook イベントを送信します。これらのイベントにサブスクライブして、決済ライフサイクルの変更にリアルタイムで対応します。

特定の決済試行内のすべての PaymentAttemptRecordEntries (開始済み、承認済み、保証済みなど) を一度に表示するには、PaymentAttemptRecord の ID を使用して PaymentAttemptRecordEntries を一覧表示します。

```curl
curl -G https://api.stripe.com/v1/payment_attempt_record_entries \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_attempt_record={{PAYMENT_ATTEMPT_RECORD_ID}}
```

```json
{
  "object": "list",
  "data": [{
    "id": "pare_4",
    "type": "guaranteed",
    "guaranteed": {
      "amount": { "value": 1099, "currency": "usd" }
    }
  },
  {
    "id": "pare_3",
    "type": "authorized",
    "authorized": {
      "amount": { "value": 1099, "currency": "usd" }
    }
  },
  {
    "id": "pare_2",
    "type": "authenticated",
    "authenticated": {
      "amount": { "value": 1099, "currency": "usd" }
    }
  },
  {
    "id": "pare_1",
    "type": "initiated",
    "initiated": {
      "amount": { "value": 1099, "currency": "usd" },
      "payment_method_details": { "type": "card" },
      "processor_details": { "type": "processor_a" }
    }
  }]
}
...
```

[ダッシュボード](https://dashboard.stripe.com/payments)でも支払いを確認することが可能です。