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

1回限りの支払い

PaymentKitは、商品やサービスに対する1回限りの請求を処理するための、いくつかの柔軟な方法を提供しています。このガイドでは、Node.js SDKで利用可能な3つの主要な方法を説明し、特定のニーズに最適なアプローチを選択するお手伝いをします。

各方法は、完全にホストされた支払いページから、深く統合されたカスタム支払いフローまで、さまざまなユースケースに対応しています。

チェックアウトセッション

最も早く始められる方法です。ユーザーをPaymentKitがホストする安全な構築済み支払いページにリダイレクトします。

支払いリンク

支払いページへの共有可能で再利用可能なリンクを作成します。ソーシャルメディア、メール、または簡単な購入ボタンに最適です。

支払いインテント

支払いのための基本的なオブジェクトです。カスタム支払いUIの構築や請求ライフサイクルの管理に使用します。

チェックアウトセッション

チェックアウトセッションは、支払いを受け入れる最も簡単な方法です。これにより、チェックアウトプロセス全体を処理する、安全でホストされた支払いページが作成されます。セッションを作成し、提供されたURLにお客様をリダイレクトするだけで、残りはPaymentKitが処理します。

このアプローチは、標準的なeコマースフロー、寄付ボタン、またはUIを自分で構築することなく、高速で安全、かつ全機能を備えたチェックアウト体験を求めるあらゆるシナリオに最適です。

仕組み

  1. セッションの作成

    サーバーがSDKを使用してセッションを作成し、品目、成功時およびキャンセル時のURL、その他の詳細を指定します。

  2. 顧客のリダイレクト

    APIはurlを含むセッションオブジェクトを返します。このURLにお客様をリダイレクトします。

  3. 顧客の支払い

    顧客はホストされたページで支払いを完了します。

  4. リダイレクトバック

    PaymentKitは顧客をあなたのsuccess_urlまたはcancel_urlにリダイレクトします。

例：チェックアウトセッションの作成

以下は、1回限りの支払いのためのセッションを作成する方法です。

Create Checkout Session

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

async function createCheckoutSession() {
  try {
    const session = await payment.checkout.sessions.create({
      mode: 'payment', // 1回限りの支払いを指定
      success_url: 'https://your-site.com/payment-success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://your-site.com/payment-cancelled',
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // あなたのPrice IDに置き換えてください
          quantity: 1,
        },
      ],
      expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // セッションは30分で期限切れになります
    });

    console.log('Checkout Session URL:', session.url);
    // ここで、ユーザーをsession.urlにリダイレクトします
  } catch (error) {
    console.error('Error creating session:', error.message);
  }
}

createCheckoutSession();

セッションを作成した後、session.urlを使用して顧客を支払いページにリダイレクトする必要があります。パラメータとオプションの完全なリストについては、チェックアウトセッションAPIリファレンスを参照してください。

支払いリンク

支払いリンクは、特定の商品に対するチェックアウトページへの再利用可能なリンクを作成する方法を提供します。一度作成すると、このリンクをメールやソーシャルメディアなどの複数のチャネルで共有したり、ウェブサイトの簡単な「今すぐ購入」ボタンに埋め込んだりすることができます。完全なショッピングカート統合を必要とせずに、単一のアイテムやサービスを販売するのに最適です。

仕組み

  1. リンクの作成

    SDKを使用して支払いリンクを作成し、1つ以上の品目を指定します。

  2. URLの共有

    APIはリンクの永続的なurlを返します。

  3. 顧客の支払い

    URLにアクセスしたどの顧客でも支払いを完了できます。

例：支払いリンクの作成

Create Payment Link

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

async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // あなたのPrice IDに置き換えてください
          quantity: 1,
        },
      ],
      metadata: {
        campaign: 'summer_sale_2024'
      }
    });

    console.log('Shareable Payment Link:', paymentLink.url);
  } catch (error) {
    console.error('Error creating payment link:', error.message);
  }
}

createPaymentLink();

支払いリンクは更新することもでき、例えば、不要になった場合にpayment.paymentLinks.archive(id)を使用してアーカイブすることができます。詳細については、支払いリンクAPIリファレンスをご覧ください。

支払いインテント

支払いインテントオブジェクトは、PaymentKitにおけるあらゆるトランザクションの基盤です。作成から完了までの支払いのライフサイクルを追跡し、その過程でさまざまな認証ステップやステータスの変更を処理します。チェックアウトセッションや支払いリンクは自動的に支払いインテントを作成・管理しますが、カスタム支払いフォームの構築や支払い後のアクションの処理など、より高度なユースケースでは直接操作することができます。

支払いインテントとの直接的なやり取りは、通常、返金の発行など、既存の支払いを管理するために行われます。

例：支払いの返金

支払い（例：チェックアウトセッション経由）が成功した後、関連する支払いインテントIDを取得し、それを使用して返金を処理できます。

Refund a Payment

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

// 支払いインテントIDは通常、完了したチェックアウトセッションから取得されます
// またはWebhookイベントを通じて取得されます。
const paymentIntentId = 'pi_xxxxxxxxxxxxxx';

async function refundPayment(pi_id) {
  try {
    const refund = await payment.paymentIntents.refund(pi_id, {
      amount: '10.00', // 返金額
      reason: 'requested_by_customer', // 顧客からのリクエスト
      description: '顧客が製品に満足しなかったため。',
    });

    console.log('Refund processed successfully:', refund.id);
  } catch (error) {
    console.error(`Error refunding payment ${pi_id}:`, error.message);
  }
}

refundPayment(paymentIntentId);

これにより、最初の請求が行われた後の支払いライフサイクルを細かく制御できます。管理機能の完全なリストについては、支払いインテントAPIリファレンスを参照してください。

1回限りの請求を作成する方法を理解したところで、次は定期的な請求のためのサブスクリプションの実装方法や、支払いイベントに関するリアルタイム通知を受け取るためのWebhookの設定方法について学ぶとよいでしょう。