メインコンテンツへスキップ

返金

返金オブジェクトは、以前の請求に対する顧客への資金の返還を表します。新しい返金を作成したり、既存の返金の詳細を取得したり、会計目的ですべての返金をリストしたりできます。返金が作成されると、最初は「保留中」の状態になり、非同期で処理されます。

返金オブジェクト

典型的な返金オブジェクトには、次の主要な属性が含まれています：

  • id: 返金オブジェクトの一意の識別子。
  • amount: 返金される総額。最小通貨単位（例：セント）で表されます。
  • currency_id: 返金に使用される通貨の識別子。
  • status: 返金の現在のステータス。「pending」（保留中）、「succeeded」（成功）、「failed」（失敗）、または「canceled」（キャンセル済み）のいずれかです。
  • reason: 返金の理由。指定可能な値には、「duplicate」（重複）、「requested_by_customer」（顧客による要求）、「requested_by_admin」（管理者による要求）、「fraudulent」（不正）、または「expired_uncaptured_charge」（期限切れの未キャプチャ請求）が含まれます。
  • payment_intent_id: 返金された Payment Intent の ID。
  • customer_id: 返金が発行された顧客の ID。
  • description: 返金の説明。
  • metadata: 独自の参照用にオブジェクトに添付できるキーと値のペアのセット。
  • created_at: 返金が作成されたときのタイムスタンプ。

返金の作成

Refund オブジェクトを作成し、以前に作成された請求を返金します。これは、請求の全額または一部の金額に対して行うことができます。

返金の作成

javascript
import payment from '@blocklet/payment-js';

async function issueRefund() {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: 'pi_xxxxxxxxxxxx',
      amount: '50.00', // 注：amount は主要単位（例：ドル）での値を表す文字列です
      currency_id: 'usd_xxxxxxxx',
      customer_id: 'cus_xxxxxxxx',
      payment_method_id: 'pm_xxxxxxxx',
      reason: 'requested_by_customer',
      description: '注文番号 #54321 の返金',
      metadata: { order_id: '54321' }
    });
    console.log('返金が開始されました：', refund);
  } catch (error) {
    console.error('返金の作成中にエラーが発生しました：', error.message);
  }
}

issueRefund();

パラメータ

NameTypeDescription
amountstring**必須。**この請求から返金する金額を表す正の文字列。請求の残りの返金可能額を超える返金はできません。
currency_idstring**必須。**返金に使用する通貨の識別子。
customer_idstring**必須。**返金に関連付けられた顧客の識別子。
payment_method_idstring**必須。**元の請求に使用された支払い方法の識別子。
payment_intent_idstring**必須。**返金する PaymentIntent の識別子。
reasonstring**必須。**返金の理由を示す文字列。サポートされている値は「duplicate」、「requested_by_customer」、「requested_by_admin」、「fraudulent」、「expired_uncaptured_charge」です。
descriptionstring**必須。**オブジェクトに添付される任意の文字列。ユーザーに表示するのに役立つことが多いです。最大200文字。
metadataobjectオプション。返金オブジェクトに添付できるキーと値のペアのセット。構造化された形式で追加情報を保存するのに役立ちます。
invoice_idstringオプション。この返金に関連付けられている請求書のID。
subscription_idstringオプション。この返金に関連付けられているサブスクリプションのID。

戻り値

作成された Refund オブジェクトを返します。

レスポンス例

json
{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "pending",
  "description": "注文番号 #54321 の返金",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}

返金の取得

一意のIDで既存の返金の詳細を取得します。

返金の取得

javascript
import payment from '@blocklet/payment-js';

async function getRefundDetails(refundId) {
  try {
    const refund = await payment.refunds.retrieve(refundId);
    console.log('返金の詳細：', refund);
  } catch (error) {
    console.error(`返金 ${refundId} の取得中にエラーが発生しました：`, error.message);
  }
}

getRefundDetails('ref_xxxxxxxxxxxx');

パラメータ

NameTypeDescription
idstring**必須。**取得する返金の一意の識別子。

戻り値

有効なIDが提供された場合、「Refund」オブジェクトを返します。それ以外の場合はエラーをスローします。

レスポンス例

json
{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "description": "注文番号 #54321 の返金",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "customer": { ... },
  "paymentCurrency": { ... },
  "paymentIntent": { ... },
  "paymentMethod": { ... }
}

すべての返金をリスト

すべての返金のページ分割されたリストを返します。さまざまな基準に基づいてリストをフィルタリングできます。

返金のリスト

javascript
import payment from '@blocklet/payment-js';

async function listSuccessfulRefunds() {
  try {
    const response = await payment.refunds.list({
      status: 'succeeded',
      pageSize: 10
    });
    console.log(`${response.count}件の成功した返金が見つかりました。`);
    response.list.forEach(refund => {
      console.log(`- 返金ID: ${refund.id}, 金額: ${refund.amount}`);
    });
  } catch (error) {
    console.error('返金のリスト中にエラーが発生しました：', error.message);
  }
}

listSuccessfulRefunds();

パラメータ

NameTypeDescription
pagenumberオプション。ページネーションのためのページ番号。1から始まります。デフォルトは「1」です。
pageSizenumberオプション。ページごとに返すオブジェクトの数。デフォルトは「20」です。
statusstringオプション。ステータスで返金をフィルタリングするためのカンマ区切りの文字列（例：「'succeeded,pending'」）。
invoice_idstringオプション。指定された請求書の返金のみを返します。
subscription_idstringオプション。指定されたサブスクリプションの返金のみを返します。
currency_idstringオプション。指定された通貨の返金のみを返します。
customer_idstringオプション。指定された顧客の返金のみを返します。

戻り値

返金オブジェクトの「list」、合計「count」、および「paging」情報を含むページ分割されたオブジェクトを返します。

レスポンス例

json
{
  "count": 15,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "status": "succeeded",
      // ... その他の返金フィールド
    }
    // ... その他の返金オブジェクト
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

返金の検索

返金に対して検索クエリを実行します。これは、カスタム検索機能を構築するのに役立ちます。

返金の検索

javascript
import payment from '@blocklet/payment-js';

async function searchForRefund(query) {
  try {
    const response = await payment.refunds.search({ q: query });
    console.log(`'${query}'の検索結果：`);
    response.list.forEach(refund => {
      console.log(`- 返金ID: ${refund.id}`);
    });
  } catch (error) {
    console.error('返金の検索中にエラーが発生しました：', error.message);
  }
}

searchForRefund('customer_id:cus_xxxxxxxx');

パラメータ

NameTypeDescription
qstring**必須。**検索クエリ文字列。キーと値のフィルタリングをサポートします（例：「status」）。
pagenumberオプション。ページネーションのためのページ番号。デフォルトは「1」です。
pageSizenumberオプション。ページごとに返すオブジェクトの数。デフォルトは「20」です。
ostringオプション。結果の順序を指定します。「asc」で昇順、「desc」で降順。デフォルトは「created_at」に基づく「desc」です。

戻り値

一致する返金オブジェクトの「list」、合計「count」、および「paging」情報を含むページ分割されたオブジェクトを返します。

レスポンス例

json
{
  "count": 1,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "customer_id": "cus_xxxxxxxx",
      "status": "succeeded",
      // ... その他の返金フィールド
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}