カスタムの決済手段を追加する

支払い Element に Custom の支払い方法を追加する方法をご紹介します。

Payment Element を Payment Intents API とともに使用すると、1 つの導入で 50 種類以上の事前設定済みの支払い方法と Custom 支払い方法を表示できます。ダッシュボードで Custom 支払い方法を作成したら、Stripe 外でこれらの取引が正しく処理され、確定されるように Payment Element を設定します。これらの取引は、レポート作成のために Stripe アカウントに記録できます。

Note

サードパーティーの決済代行業者と連携する場合は、PSP との契約や適用法など、適用される法務要件に従う責任があります。

はじめに

Stripe アカウントを作成するか、既存のアカウントでサインインします。
このガイドに従って、決済の導入を完了します。

Custom 支払い方法を作成する
ダッシュボード

ダッシュボードで設定 > 支払い > Custom 支払い方法に移動して、Custom 支払い方法を作成できます。表示する支払い Element の名前とロゴを指定します。

適切なロゴを選択

背景が透明なロゴの場合は、ページの支払い Element の背景色を考慮して、目立つようにしてください。
背景が塗りつぶされたロゴの場合、必要に応じてファイルに角丸を含めます。
16 x 16 ピクセルに拡大縮小できるロゴのバリアントを選択します。多くの場合、これはブランドのスタンドアロンのロゴマークです。

Custom の決済手段を作成すると、次のステップで必要な Custom の決済手段の ID (``cpmt_` で始まる) がダッシュボードに表示されます。

Custom の決済手段のタイプを追加
クライアント側

次に、Custom の決済手段のタイプを Stripe Elements 設定に追加します。Stripe Elements を初期化する checkout.js ファイルで、Payment Element に追加する customPaymentMethods を指定します。前のステップの Custom 支払い方法 ID、options.type、およびオプションのサブタイトルを指定します。

checkout.js
const elements = stripe.elements({
  // ...
  customPaymentMethods: [
    {
      id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
,
      options: {
        type: 'static',
        subtitle: Optional subtitle,
      }
    }
  ]
});

読み込まれると、支払い Element に Custom の支払い方法が表示されます。

PM Name というカスタムの決済手段を示すStripe Payment Element。

オプション埋め込みカスタムコンテンツを表示する
Preview
クライアント側

embedded タイプを使用して、Payment Element に Custom 支払い方法のコンテンツを表示します。

PM Name というカスタム決済手段を示し、カスタムコンテンツがフォームコンテナーにオーバーレイされた Stripe Payment Element。

次のコールバックを使用して Custom コンテンツを管理します:

handleRender: 支払い方法が選択されたときに呼び出されます。このフックには、コンテンツをレンダリングできるコンテナ DOM ノードへの参照が含まれます。
handleDestroy: 支払い方法の選択が解除されたとき、および Payment Element がマウント解除されたときに呼び出されます。これを使用して、イベントリスナーや Custom SDK の削除などのクリーンアップを実行します。

Security tip

handleEmbed によって提供される container 内の信頼できるコンテンツのみをレンダリングします。特にユーザーやサニタイズされていないソースから、お客様が管理していないマークアップをレンダリングすると、クロスサイトスクリプティングの脆弱性 (XSS) が発生する可能性があります。

React Portals などのツールを使用すると、レンダリングロジックをアプリケーションコードに実装できます。

checkout.js
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

export default function App() {
  const [embedContainer, setEmbedContainer] = useState();

  const options = {
    customPaymentMethods: [
      {
        id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}',
        options: {
          type: 'embedded',
          subtitle: Embedded payment method,
          embedded: {
            handleRender: (container) => {
              setEmbedContainer(container);
            },
            handleDestroy: () => {
              setEmbedContainer(null);
            }
          }
        }
      }
    ]
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutFormWithPaymentElement />
      {embedContainer && createPortal(<EmbeddedCpmContent />, embedContainer)}
    </Elements>
  );
};

決済手段の送信を処理
クライアント側

ユーザーがウェブサイトの支払いボタンをクリックしたときに呼び出される handleSubmit 関数を更新して、Custom の決済手段の取引が Stripe 以外で処理されるようにします。

elements.submit() 関数は、選択された支払い方法タイプを取得します。たとえば、モーダルを表示してから、自社のサーバーで支払いを処理するか、顧客を外部の支払いページにリダイレクトします。

checkout.js
async function handleSubmit(e) {
  const { submitError, selectedPaymentMethod } = await elements.submit();

  if (selectedPaymentMethod === '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
) {
    // Process CPM payment on merchant server and handle redirect
    const res = await fetch("/process-cpm-payment", { method: 'post' });
    ...
  } else {
    // Process Stripe payment methods
    ...
  }
}

オプションカスタムの決済手段の順序を指定
クライアント側

デフォルトでは、Payment Element はカスタムの決済手段を最後に表示します。決済手段の順序を手動で指定するには、Payment Element インスタンスを作成するときに、オプション設定で paymentMethodOrder プロパティを設定します。

checkout.js
const paymentElement = elements.create('payment', {
  // an array of payment method types, including custom payment method types
  paymentMethodOrder: [...]
});

オプションStripe アカウントへの支払いを記録する
サーバー側

Stripe 以外で Custom 支払い方法取引を処理する場合でも、Stripe アカウントに取引の詳細を記録できます。これは、レポートの統合や、領収書の発行やレポートの作成などのバックオフィスワークフローの構築に役立ちます。

server.js
const stripe = new Stripe('sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-10-29.clover; invoice_partial_payments_beta=v3'
});

app.get('/process-cpm-payment', async (req, res) => {
  const paymentResult = processMyCustomPayment(...)

  // Create an instance of a custom payment method
  const paymentMethod = await stripe.paymentMethods.create({
    type: 'custom',
    custom: {
      type: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
,
    }
  });

  // Report successful payment
  const paymentRecord = await stripe.paymentRecords.reportPayment({
    amount_requested: {
      value: paymentResult.amount,
      currency: paymentResult.currency
    },
    payment_method_details: {
      payment_method: paymentMethod.id
    },
    customer_details: {
      customer: paymentResult.customer.id
    },
    processor_details: {
      type: 'custom',
      custom: {
        payment_reference: paymentResult.id
      }
    },
    initiated_at: paymentResult.initiated_at,
    customer_presence: 'on_session',
    outcome: 'guaranteed',
    guaranteed: {
      guaranteed_at: paymentResult.completed_at
    }
  });

  // Respond to frontend to finish buying experience
  return res.json(...)
});

カスタムの決済手段を追加する

支払い Element に Custom の支払い方法を追加する方法をご紹介します。

Note

はじめに

Custom 支払い方法を作成するダッシュボード

適切なロゴを選択

Custom の決済手段のタイプを追加クライアント側

オプション埋め込みカスタムコンテンツを表示するPreviewクライアント側