JavaScript

概要

JavaScript SDK は、Web ページに elepay の決済画面を表示し、決済完了までの処理を行います。

連携の流れ：

1. サーバー側で API を呼び出して Charge（または Source）を作成し、ID を取得します。
2. フロントエンドで elepay.handle(id) を呼び出すと、SDK が決済画面を表示し、ユーザーが決済を完了します。
3. サーバー側で Webhook により決済結果を受け取り、注文を確定します。

カード情報の入力、決済アプリへの遷移、3D セキュア認証、エラー表示は SDK が行います。フロントエンドでの実装も、エラーコードごとの表示も不要です。

導入

script タグを追加すると、グローバルオブジェクト elepay が使えるようになります。

<script src="https://pay.elepay.io/v2/elepay.js"></script>

elepay.handle()

elepay.handle(id, options?) は決済画面を表示し、決済完了までの処理を行います。

await elepay.handle('ch_xxx');

引数

id: string | Promise<string>

Charge（ch_*）または Source（src_*）の ID。サーバー側で API を呼び出して作成します（例：Charge 作成）。

Promise<string> も渡せます。決済画面はすぐに表示され、Promise が ID を返すのを待ちます。クリック時にサーバー側で Charge を作成する場合でも、画面の表示は遅れません。Promise が reject すると画面は閉じ、handle() も同じエラーで reject します。このとき SDK はユーザーに何も表示しないため、Promise 側で処理してください（例：Charge 作成の失敗を表示する）。

id が空、または ch_ / src_ で始まらない場合、ユーザーには汎用のエラーのみが表示され、詳しい原因はブラウザの console に出力されます：[elepay] configuration error: …。

options.locale?: Locale

決済画面の表示言語。指定できる値は 'ja'、'en'、'zh_CN'、'zh_TW'、'ko'、'vi'、'th' です。省略した場合はブラウザの言語で表示し、ブラウザの言語がいずれにも該当しない場合は日本語で表示します。

options.presetData?: CreditCardPresetData

クレジットカード情報を事前に渡すと、カード情報の入力フォームを表示せずにそのまま決済を実行します。カード情報の入力フォームを加盟店が自前で用意する場合に使います。

await elepay.handle('ch_xxx', {
  presetData: {
    cardNumber: '4242424242424242',
    expiryMonth: 12,
    expiryYear: 2028,
    cvv: '123',
    cardHolderName: 'TARO YAMADA',
    repaymentType: '1', // 一括払い
  },
});

repaymentType は支払い回数です。指定できる値は、加盟店の決済事業者の設定によって異なります。

• '1'：一括払い
• '2'、'3' などその他の数字：分割払いの回数
• 'revolving'：リボ払い
• 'bonus_one_time'：ボーナス一括払い

presetData はクレジットカード決済でのみ使えます。Apple Pay、Google Pay では presetData は無視され、通常どおり決済画面が表示されます。その他の決済方法ではエラーになります。クレジットカードの決済事業者が Stripe または楽天カードの場合もエラーになります。

presetData を使う場合、カード番号などの情報は加盟店のページで直接扱うことになるため、加盟店のシステムは相応の PCI DSS 要件を満たす必要があります。

戻り値

Promise<void> を返します。決済完了時にのみ resolve するため、await の後には完了時の処理だけを書けば済みます。

キャンセルや失敗の場合は reject します。渡した Promise 自体の失敗を除き、理由は SDK がすでにユーザーに表示しているため、catch で改めて表示する必要はありません。reject の値は参照せず、catch (e) ではなく catch と書いてください。詳しい理由やエラーコードは管理画面または API で確認できます。

注文確定など決済完了を前提とする処理は、Webhook の通知で判断してください。

try {
  await elepay.handle('ch_xxx');
  // 決済完了。完了後の処理を行う（例：サンクスページへ遷移）
  // location.href = '/thanks';
} catch {
  // キャンセル、失敗など。理由は SDK が表示済みのため、改めて表示する必要はない
}

型定義

SDK は npm パッケージと型定義ファイルを提供していません。TypeScript を使う場合は、以下の宣言をプロジェクトの .d.ts ファイルにコピーしてください。

type CreditCardPresetData = {
  cardNumber: string;
  expiryMonth: number;
  expiryYear: number;
  cvv: string;
  cardHolderName: string;
  repaymentType?: string; // '1' | '2' | '3' | ... | 'revolving' | 'bonus_one_time'
};

type Locale = 'ja' | 'en' | 'zh_CN' | 'zh_TW' | 'ko' | 'vi' | 'th';

type HandleOptions = {
  locale?: Locale;
  presetData?: CreditCardPresetData;
};

declare global {
  var elepay: {
    handle: (id: string | Promise<string>, options?: HandleOptions) => Promise<void>;
  };
}

export {};

旧 JavaScript SDK（非推奨）

旧版の説明は 旧 JavaScript SDK をご参照ください。