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

Payment Intent

Payment Intentは、顧客から支払いを受け取る意図を表し、支払いプロセスのライフサイクルを追跡するオブジェクトです。これはPaymentKit APIの中心的なオブジェクトであり、顧客からあなたへの資金の流れを制御します。Payment Intentは、ユーザー向けの支払いフローのためにC

Payment Intentは、顧客から支払いを受け取る意図を表し、支払いプロセスのライフサイクルを追跡するオブジェクトです。これはPaymentKit APIの中心的なオブジェクトであり、顧客からあなたへの資金の流れを制御します。Payment Intentは、ユーザー向けの支払いフローのためにCheckout Sessionに関連付けることも、サーバーサイドの操作に直接使用することもできます。

このドキュメントでは、SDKを使用してPayment Intentオブジェクトを管理する方法を詳しく説明します。

Payment Intentオブジェクト

Payment Intentオブジェクトには、取引に関する詳細な情報が含まれています。展開すると、関連オブジェクトも含まれる場合があります。

オブジェクトのプロパティ

PropertyTypeDescription
idstringオブジェクトの一意の識別子。
statusstringPayment Intentのステータス。可能な値は requires_payment_method、requires_confirmation、requires_action、processing、requires_capture、canceled、または succeeded です。
amountstring支払いを受ける予定の金額。
amount_receivedstringこれまでに受領した金額。
currency_idstringこの支払いの通貨ID。
customer_idstringこのPayment Intentの対象となる顧客のID（存在する場合）。
invoice_idstringこのPayment Intentの対象となる請求書のID（存在する場合）。
payment_method_idstringこのPayment Intentに使用されたPaymentMethodのID。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。
created_atstringオブジェクトが作成されたときのタイムスタンプ。

展開されるオブジェクト

取得時、Payment Intentオブジェクトには以下の展開されたオブジェクトが含まれる場合があります。

  • customer: 完全なCustomerオブジェクト。
  • paymentCurrency: 完全なPaymentCurrencyオブジェクト。
  • paymentMethod: 完全なPaymentMethodオブジェクト。
  • invoice: 完全なInvoiceオブジェクト（該当する場合）。
  • subscription: 完全なSubscriptionオブジェクト（該当する場合）。
  • checkoutSession: このPayment Intentを作成したCheckoutSession。

Payment Intentの取得

以前に作成されたPayment Intentの詳細を取得します。client_secretが提供されている場合、公開可能キーを使用したクライアントサイドでの取得が許可されます。

Payment Intentの取得

javascript
const paymentIntent = await payment.paymentIntents.retrieve(
  'pi_123456789'
);

console.log(paymentIntent);

パラメータ

NameTypeDescription
idstring必須。 取得するPayment IntentのID。

戻り値

有効なIDが指定された場合はPaymentIntentオブジェクトを返します。それ以外の場合はエラーをスローします。

レスポンスの例

json
{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "amount_received": "1000",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "invoice_id": "in_xxxxxxxx",
  "payment_method_id": "pm_xxxxxxxx",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    /* ... payment currency details ... */
  },
  "paymentMethod": {
    /* ... payment method details ... */
  },
  "customer": {
    /* ... customer details ... */
  },
  "invoice": {
    /* ... invoice details ... */
  },
  "subscription": null,
  "checkoutSession": {
    /* ... checkout session details ... */
  }
}

Payment Intentの更新

渡されたパラメータの値でPayment Intentオブジェクトを更新します。指定されなかったパラメータは変更されません。このメソッドで更新できるのはmetadataのみであることに注意してください。

Payment Intentの更新

javascript
const paymentIntent = await payment.paymentIntents.update(
  'pi_123456789',
  {
    metadata: { order_id: '6735' }
  }
);

console.log(paymentIntent);

パラメータ

NameTypeDescription
idstring必須。 更新するPayment IntentのID。
metadataobjectオブジェクトに保存するキーと値のペアのセット。

戻り値

更新されたPaymentIntentオブジェクトを返します。

レスポンスの例

json
{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "metadata": {
    "order_id": "6735"
  },
  // ... other properties
}

すべてのPayment Intentを一覧表示

Payment Intentのリストを返します。インテントは作成日順にソートされ、最新のものが最初に表示されます。

Payment Intentの一覧表示

javascript
const paymentIntents = await payment.paymentIntents.list({
  limit: 5,
  status: 'succeeded'
});

console.log(paymentIntents);

パラメータ

NameTypeDescription
statusstring任意。フィルタリングするステータスのコンマ区切り文字列（例：'succeeded,processing'）。
invoice_idstring任意。指定された請求書のPayment Intentのみを返します。
customer_idstring任意。指定された顧客IDのPayment Intentのみを返します。
customer_didstring任意。指定された顧客DIDのPayment Intentのみを返します。
metadata.{key}string任意。特定のメタデータのキーと値のペアでフィルタリングします。
pagenumber任意。ページネーション用のページ番号。1から始まります。デフォルトは1です。
pageSizenumber任意。返されるオブジェクト数の上限。1から100の間です。デフォルトは20です。

戻り値

PaymentIntentオブジェクトのlistとページネーションの詳細を含む、ページ分割されたオブジェクト。

レスポンスの例

json
{
  "count": 15,
  "list": [
    {
      "id": "pi_123456789",
      "status": "succeeded",
      // ... other properties
    },
    {
      "id": "pi_987654321",
      "status": "succeeded",
      // ... other properties
    }
    // ... more payment intents
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Payment Intentの検索

特定のクエリに一致するPayment Intentを検索します。

Payment Intentの検索

javascript
const results = await payment.paymentIntents.search({
  query: 'cus_xxxxxxxx'
});

console.log(results);

パラメータ

NameTypeDescription
querystring必須。 検索クエリ文字列。
pagenumber任意。ページネーション用のページ番号。1から始まります。デフォルトは1です。
pageSizenumber任意。1ページあたりの項目数。デフォルトは20です。

戻り値

検索クエリに一致するPaymentIntentオブジェクトのlistを含む、ページ分割されたオブジェクト。

レスポンスの例

json
{
  "count": 1,
  "list": [
    {
      "id": "pi_123456789",
      "customer_id": "cus_xxxxxxxx",
      // ... other properties
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

請求の返金

Payment Intentが成功した場合、その請求に対して返金を作成できます。これによりRefundオブジェクトが作成され、請求の取り消しが試みられます。

請求の返金

javascript
const refund = await payment.paymentIntents.refund(
  'pi_123456789',
  {
    amount: '500',
    reason: 'requested_by_customer',
    description: 'Refund for item not received.'
  }
);

console.log(refund);

パラメータ

NameTypeDescription
idstring必須。 返金対象のPayment IntentのID。
amountstring必須。 この請求のうち返金する金額を表す正の文字列。元の請求の合計額まで返金できます。
reasonstring必須。 返金の理由を示す文字列。有効な値は duplicate、requested_by_customer、requested_by_admin、fraudulent、expired_uncaptured_charge です。
descriptionstring必須。 返金の説明。

戻り値

新しいRefundオブジェクトを返します。

レスポンスの例

json
{
  "id": "re_abcdef123",
  "type": "refund",
  "livemode": false,
  "amount": "500",
  "description": "Refund for item not received.",
  "status": "pending",
  "reason": "requested_by_customer",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_123456789",
  // ... other refund properties
}