CreditReversals オブジェクトを使用して Treasury で送金

受領したクレジットから返金して Treasury の金融口座に資金を追加する方法とそのシナリオをご紹介します。

ReceivedCredit を差戻すと、CreditReversal が作成されます。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 を更新できないため、作成時にオプションのメタデータを設定する必要があります。

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

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

{
    "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"

CreditReversal を取得する

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

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

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 件のクレジット差戻しを返します。

成功すると、該当する CreditReversal オブジェクトのリストがレスポンスで返されます。

CreditReversal をテストする

CreditReversal をテストするには、まずテスト環境用の ReceivedCredit を作成する必要があります。その後、POST /v1/treasury/credit_reversals を使用して received_credit パラメーターでテスト環境用の ReceivedCredit ID を指定し、テスト環境用の CreditReversal を作成します。

CreditReversal の Webhook

Stripe は、Webhook エンドポイントに以下の CreditReversal イベントを送信します。

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