# CreditReversal オブジェクトを使用した資金移動

金融口座に入金されたクレジットの資金を返金する方法をご覧ください。

[ReceivedCredit](https://docs.stripe.com/api/treasury/received_credits.md) を差戻すと、[CreditReversal](https://docs.stripe.com/api/treasury/credit_reversals.md) が作成されます。`ReceivedCredits` は、一部のケース (以下の表で説明) でのみ差戻しできます。`ReceivedCredit` を差戻しできるかどうかは、ネットワークとソースフローによって決まります。

`ReceivedCredit` オブジェクトの `reversal_details` サブハッシュには以下の値の組み合わせを使用できます。これによって、`ReceivedCredit` を差戻せるかどうかが決まります。

| 制限理由                     | 期限 (Epoch タイムスタンプ) | シナリオ例                                                                                                                            |
| ------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `source_flow_restricted` | `null`             | `OutboundPayment` 以外のフローから発生した Stripe ネットワークの `ReceivedCredit`。Stripe ではユーザーによるこのような `ReceivedCredits` の差戻しを制限しています。             |
| `network_restricted`     | `null`             | ネットワークの制約により、Stripe は電信送金からの `ReceivedCredit` など、一部の `ReceivedCredits` を差戻すことができません。                                             |
| `null`                   | `{{TIMESTAMP}}`    | `deadline` のタイムスタンプまでであれば差戻すことができる `ReceivedCredit`。ACH `ReceivedCredits` には、差戻し可能な期間を決定する期限が設定されています。                           |
| `deadline_passed`        | `{{TIMESTAMP}}`    | `deadline` のタイムスタンプ以前であれば差戻し可能であったが、`deadline` を過ぎたために差戻しできなくなった `ReceivedCredit`。ACH `ReceivedCredits` は、作成後に差戻し可能な時間が制限されています。 |
| `already_reversed`       | `null`             | すでに差戻しされている `ReceivedCredit` には、この `restricted_reason` が設定されます。null 以外の `deadline` 値があることがあります。                                  |
| `null`                   | `null`             | `restricted_reason` と `deadline` の両方に `null` が設定されている場合は、いつでも `ReceivedCredits` を差戻すことができます。                                     |

## CreditReversal を作成する

`POST /v1/treasury/credit_reversals` を使用して `CreditReversal` を作成します。リクエストの本文で、`received_credit` パラメーターを差戻し対象の `ReceivedCredit` の ID に設定します。

> `CreditReversals` を更新できないため、作成時にオプションの[メタデータ](https://docs.stripe.com/api/treasury/credit_reversals/create.md#create_credit_reversal-metadata)を設定する必要があります。

以下のリクエストは、必須の `received_credit` パラメーターの `ReceivedCredit` ID 値に基づいて `CreditReversal` を作成します。このリクエストは、オプションのメタデータ値も設定します。

```curl
curl https://api.stripe.com/v1/treasury/credit_reversals \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d received_credit={{RECEIVED_CREDIT_ID}} \
  -d "metadata[reason]=Because"
```

成功するとレスポンスで、新しい `CreditReversal` オブジェクトが返されます。

```json
{
    "id": "{{CREDIT_REVERSAL_ID}}",
    "object": "credit_reversal",
    "amount": 1000,
    "currency": "usd",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{URL_ID}}",
    "livemode": false,
    "metadata": {
        "csr_id": "CSR-12"
    },
    "network": "ach",
    "received_credit": "{{RECEIVED_CREDIT_ID}}",
    "status": "processing",
    "status_transitions": {
        "posted_at": null
    },
    "transaction": "{{TRANSACTION_ID}}"
}
```

## CreditReversal を取得する

`GET /v1/treasury/credit_reversals/{{CREDIT_REVERSAL_ID}}` を使用して、関連付けられた ID の `CreditReversal` を取得します。

```curl
curl https://api.stripe.com/v1/treasury/credit_reversals/{{CREDIT_REVERSAL_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

レスポンスで、特定の `CreditReversal` オブジェクトが返されます。

#### JSON (コメント付き)

```json
{
  "id": "{{CREDIT_REVERSAL_ID}}",
  "object": "credit_reversal",
  "livemode": "{{Boolean}}",
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  // The ReceivedCredit that was reversed
  "received_credit": "{{RECEIVED_CREDIT_ID}}",
  // The rails used to reversed. Always the same as that of the ReceivedCredit
  "network": "ach",
  "status": "processing" | "posted",
  "status_transitions": {
    "posted_at": null | "{{Timestamp}}"
  },
  // Transaction representing balance impact of the CreditReversal
  "transaction": "{{TRANSACTION_ID}}",
  // A unique, Stripe-hosted direct link to the regulatory receipt for the CreditReversal
  "hosted_regulatory_receipt_url": "{{Url}}",
  // A map of String-String intended for users to use custom data
  "metadata": {}
}
```

## CreditReversal を一覧表示する

`GET /v1/treasury/credit_reversals` を使用して、必須の `financial_account` パラメーターで指定された ID の金融口座について、`CreditReversals` のリストを取得します。標準のリストパラメーター、`status`、または `received_credit` パラメーターを使用する `ReceivedCredit` ID でリストをフィルタリングできます。

```
{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "posted",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // Filter by ReceivedCredit
  "received_credit": "{{RECEIVED_CREDIT_ID}}"
}
```

以下のリクエストは、指定された金融口座についてステータスが `posted` の、最新の 3 件のクレジット差戻しを返します。

```curl
curl -G https://api.stripe.com/v1/treasury/credit_reversals \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d limit=3 \
  -d status=posted \
  -d "financial_account={{TREASURYFINANCIALACCOUNT_ID}}"
```

成功すると、該当する [CreditReversal オブジェクト](https://docs.stripe.com/api/treasury/credit_reversals.md)のリストがレスポンスで返されます。

## CreditReversal をテストする

CreditReversal をテストするには、まず[テスト用の ReceivedCredits](https://docs.stripe.com/treasury/connect/moving-money/into/credit-reversals.md#testcr) を作成する必要があります。次に、`POST /v1/treasury/credit_reversals` を使用し、`received_credit` パラメーターでテスト用の `ReceivedCredit` ID を指定して、テスト用の `CreditReversal` を作成します。

## CreditReversal の Webhook

Stripe は、[Webhook](https://docs.stripe.com/webhooks.md) エンドポイントに以下の `CreditReversal` イベントを送信します。

- `CreditReversal` 作成時の `treasury.credit_reversal.created`。
- `CreditReversal` 転記時の `treasury.credit_reversal.posted`。