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

外部のアカウント所有者から金融口座から引き出された資金を取り戻す方法をご覧ください。

[ReceivedDebit](https://docs.stripe.com/api/treasury/received_debits.md) から資金を返金すると、[DebitReversal](https://docs.stripe.com/api/treasury/debit_reversals.md) が作成されます。`ReceivedDebit` から資金を返金できるのは、一部のケース (以下の表で説明) に限られます。`ReceivedDebit` の資金を返金できるかどうかは、ネットワークとソースフローによって異なります。

`ReceivedDebit` リソースの `reversal_details` サブハッシュには以下の値の組み合わせを使用できます。これによって、`ReceivedDebit` の資金を返金できるかどうかが決まります。

| 制限理由                     | 期限 (Epoch タイムスタンプ) | シナリオ例                                                                                                                                            |
| ------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `null`                   | 7940828047         | `deadline` のタイムスタンプまでであれば資金を返金できる `ReceivedDebit`。ACH `ReceivedDebits` には、返金可能な期間を決定する期限が設定されています。                                               |
| `deadline_passed`        | 1629480538         | `deadline` のタイムスタンプ以前であれば返金可能であったが、`deadline` を過ぎたために API を使用して返金できなくなった `ReceivedDebit`。ACH `ReceivedDebits` では、作成後に API を使用して返金できる時間が制限されています。 |
| `already_reversed`       | null               | すでに返金されている `ReceivedDebit`。null 以外の `deadline` 値があることがあります。                                                                                      |
| `source_flow_restricted` | null               | `source_flow` が差戻し可能でないため、返金できない `ReceivedDebit`。                                                                                                |

## 返金の期限

ACH デビットでは、受領からおおよそ 1 営業日以内であれば API を使用して返金できます。それ以降は、ACH デビットの資金を引き続き返金できる可能性はありますが、資金の返金は保証されません。返金の期限が経過した場合に資金の返金をリクエストするには、サポートにお問い合わせください。

`Issuing` カードでのアクティビティーによって生成された `ReceivedDebit` の資金の返金を作成するには、[Issuing の不審請求の申請](https://docs.stripe.com/issuing/purchases/disputes.md)ガイドをご覧ください。

## DebitReversal を作成する

`POST /v1/treasury/debit_reversals` を使用して `DebitReversal` を作成します。リクエストの本文で、`received_debit` パラメーターを使用し、差戻し対象の `ReceivedDebit` の ID を指定します。

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

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

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

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

```json
{
  "id": "{{DEBIT_REVERSAL_ID}}",
  "object": "debit_reversal",
  "amount": 1000,
  "currency": "usd",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{URL_ID}}",
  "linked_flows": null,
  "livemode": false,
  "metadata": {},
  "network": "ach",
  "received_debit": "{{RECEIVED_DEBIT_ID}}",
  "resolution": null,
  "status": "processing",
  "status_transitions": {
    "completed_at": null
  },
  "transaction": "{{TRANSACTION_ID}}"
}
```

## DebitReversal を取得する

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

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

成功するとレスポンスで、特定された `DebitReversal` が返されます。

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

```json
{
  "id": "{{DEBIT_REVERSAL_ID}}",
  "object": "debit_reversal",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  // the ReceivedDebit being returned
  "received_debit": "{{RECEIVED_DEBIT_ID}}",
  // whether funds have been returned depending on the DebitReversal outcome
  "resolution": null | "won",
  "status": "processing" | "canceled" | "completed",
  "status_transitions": {
    "processing_at": "{{Timestamp}}",
    "canceled_at": null | "{{Timestamp}}",
    "completed_at": null | "{{Timestamp}}"
  },
  // Transaction representing balance impact of the DebitReversal
  "transaction": "{{TRANSACTION_ID}}",
  // A unique, Stripe-hosted direct link to the regulatory receipt for the DebitReversal
  "hosted_regulatory_receipt_url": "{{Url}}",
  // A map of String-String intended for users to use custom data
  "metadata": {}
}
```

## DebitReversal を一覧表示する

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

```
{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by financial account (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // Filter by `status`
  "status": "processing" | "canceled" | "completed"
  // Filter by ReceivedDebit
  "received_debit": "{{RECEIVED_DEBIT_ID}}",
}
```

以下のリクエストは、特定された金融口座の、最新の 3 件の [DebitReversal オブジェクト](https://docs.stripe.com/api/treasury/debit_reversals/object.md)を取得します。

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

## DebitReversal をテストする

`DebitReversals` をテストするには、まず [test ReceivedDebit](https://docs.stripe.com/treasury/connect/moving-money/out-of/debit-reversals.md#testdebrev) を作成する必要があります。その後、`POST /v1/treasury/debit_reversals` を使用し、`ReceivedDebit` ID を `received_debit` パラメーターに指定して、test `DebitReversal` を作成します。

## DebitReversal Webhook

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

- `DebitReversal` 作成時の `treasury.debit_reversal.created`。
- `DebitReversal` 完了時の `treasury.debit_reversal.completed`。