ウィジェット：Javascript

ウィジェットパラメーター

Parameters	
appId	string (TOKEN) このパラメータでは、ウィジェットが支払いを行うストアで発行したアプリケーショントークンを指定します。 必須: はい 指定可能な値: 有効なアプリケーショントークン
checkout	string このパラメータでは、トランザクショントークンを作成するだけ(token)か、トランザクショントークンと課金もしくは定期課金の両方を作成する (payment)か、トランザクショントークンのみ作成しQRコードを表示する(qr)かを指定します。表示されたQRコードの読み取りについては、こちらをご覧ください。 必須: はい 指定可能な値: token, payment
paymentType	string このパラメータを利用すると、選択ページを経由することによって、支払方法を指定することができます。指定したPaymentTypeが利用不可だった場合、チェックアウトでエラーを返します。 必須: はい 指定可能な値: card, konbini, paidy, online
paymentTypes	string このパラメータを利用すると、支払方法をフィルタリングさせることができます。 必須: いいえ(デフォルトは 全ての支払い方法) 指定可能な値: “,”で区切られたcard, konbini, paidy, online, pay_pay_online, we_chat_online, alipay_online, alipay_plus_online
amount	number このパラメータでは、ワンタイム課金の場合に課金金額を指定します。定期課金の場合は、１回の支払いで課金する金額を指定します。分割払いの定期課金の場合は、すべての支払の合計金額を指定します。補助通貨を使用する通貨の場合、補助通貨を含んだ金額を指定するよう注意してください。 例：9.50 USD の場合は 950 と表記します。 必須: はい 指定可能な値: 正の整数
currency	string (currency code) このパラメータでは、課金金額の通貨を指定します。 必須: はい 指定可能な値: 通貨コード
tokenType	string このパラメータでは、作成するトランザクショントークンの種類を指定します。 必須: いいえ (デフォルトは one_time) 指定可能な値: one_time, recurring, subscription
subscriptionPeriod	string このパラメータでは、定期課金の課金の間隔を指定します。 必須: トークンタイプが subscription の場合 指定可能な値: daily（毎日）, weekly（毎週）, biweekly（隔週）, monthly（毎月）, quarterly（3ヶ月）, semiannually（6ヶ月）, annually（毎年）
subscriptionId	string このパラメータを使用すると、定期課金の作成ではなく、指定された定期課金に適用可能なトランザクショントークンを作成します。 必須: いいえ 指定可能な値: アプリケーショントークンに紐付いたストアに作成されている定期課金のID
installmentPlan	string このパラメータでは、分割払いの定期課金を作成します。固定の回数の支払い(fixed_cycles)か、都度の課金額を固定にする(fixed_cycle_amount)かを指定できます。 必須: いいえ 指定可能な値: fixed_cycles, fixed_cycle_amount
installmentQty	number 分割払いプランに fixed_cyclesを指定している場合、このパラメータで支払回数を指定します。 fixed_cycle_amount を指定した場合は、課金ごとの金額を指します。 必須: 分割払いプランを指定している場合 指定可能な値: 正の整数
installmentInitialAmount	number 定期課金が分割払いプランの場合、このパラメータでは初回の支払いの金額を指定します。 必須: いいえ 指定可能な値: 正の整数
subscriptionInitialAmount	number 分割払いプランではない定期課金の場合、このパラメータでは初回の支払いの金額を指定します。 必須: いいえ 指定可能な値: 正の整数
subscriptionStart	string このパラメータでは、作成された定期課金の２回目の課金を行う日付を指定します（初回の課金は定期課金作成時に行われます）。 必須: いいえ 指定可能な値: ISO8601 形式の日付
subscriptionStartIn	string 定期課金の2回目の課金が行われるまでの期間。（初回課金は定期課金の作成時に行われます。） このパラメータはsubscriptionStartが設定されていない場合のみ動作します。 必須: いいえ 指定可能な値: ISO8601 duration text。 例：P●D、P●M（P1D、P5D、P0M、P1M）
subscriptionStartDayOfMonth	number 定期課金の2回目の課金が行われる日付。（初回課金は定期課金の作成時に行われます。） subscriptionStartInと組み合わせることも可能です。 例えば、 subscriptionStartDayOfMonth: 20 subscriptionStartIn: “P1M” と設定した場合、2回目の課金は翌月の20日に行われます。 日付が月内で既に過ぎていて、subscriptionStartInが設定されていない場合、翌月の設定した日付（もしくは末日）に定期課金が開始されます。（例：2022/10/13にsubscriptionStartDayOfMonth=5を設定した場合、2022/11/5に定期課金が開始されます。） このパラメータはsubscriptionStartが設定されていない場合のみ動作します。 必須: いいえ 指定可能な値:1から31までの整数
header	string このパラメータでは、ウィジェットのヘッダのバーに表示されるテキストを指定します。 必須: いいえ (デフォルトは “UnivaPay”) 指定可能な値: 任意の文字列
title	string このパラメータが設定されている場合は、ウィジェット内のストアの名前がこの値に置き換えられます。 必須: いいえ (defaults to the name of the store) 指定可能な値: 任意の文字列
description	string このパラメータが設定されている場合は、ウィジェット内のサブヘーダーでdescriptionの文字列をみせます。 必須: いいえ 指定可能な値: 任意の文字列
name	string このパラメータでは、チェックアウトが正常に完了した際に挿入される、 input 要素の name 属性値を指定できます。この input 要素は、チェックアウトによって作成されたリソースのIDを保持します。なお、この指定は “メイン” のリソースにのみ適用される事に注意してください。 トランザクショントークンのみが作成される場合、input 要素の name 属性はこのパラメータで指定された値になります。省略した場合、 値はunivapayTokenId になります。 リカーリングトークンによって課金もしくは定期課金が作成される場合、input 要素の name 属性は、このパラメータで指定された値になります。省略した場合、値はunivapaySubscriptionId もしくは univapayChargeId になります。この時、トランザクショントークンを保持する input 要素の name 属性値は常に univapayTokenId となります。 必須: いいえ 指定可能な値: 任意の文字列
capture	boolean 課金が作成される場合、このパラメータを false に指定することで、キャプチャを行わずオーソリのみを行うようにします。その際、課金は手動でキャプチャするか、capture at パラメータを指定することで自動的にキャプチャすることができます。 必須: いいえ (デフォルトは true) 指定可能な値: true, false
captureAt	string capture パラメータを false を指定したうえでこのパラメータを設定した場合、ここで指定した日時に課金が自動的にキャプチャされます。 必須: いいえ 指定可能な値: ISO8601 形式の日時
expirationPeriod	string このパラメータで期間を指定すると、決済が行われてから振込をするまでの期間を設定できます。 銀行振込/コンビニ決済で有効です。 必須: いいえ(デフォルトは30日) 指定可能な値: ISO8601 duration text。 例：P●D、P●M（P1D、P5D、P0M、P1M）
expirationTimeShift	string このパラメータで時間を指定すると、振込期限の時間を設定できます。 銀行振込/コンビニ決済で有効です。 必須: いいえ(デフォルトは決済が行われた時間) 指定可能な値: ISO8601 例：12:00:00+12:00
email	string このパラメータにメールアドレスを指定すると、ウィジェットのフォームのメールアドレスフィールドに初期値として入力されます。 必須: いいえ 指定可能な値: メールアドレス
address	boolean このパラメータをtrue に設定すると、エンドユーザーに住所を入力するフォームが表示されます。 必須: いいえ (デフォルトは false) 指定可能な値: true, false
requireEmail	boolean このパラメータをtrueに設定すると、エンドユーザーにメールアドレスを入力するフォームが表示されます。 カードとコンビニ払いには適用されません。 必須: いいえ (デフォルトは false) 指定可能な値: true, false
requirePhoneNumber	boolean このパラメータをtrueに設定すると、エンドユーザーに電話番号を入力するフォームが表示されます。 Required: いいえ (デフォルトは false) 指定可能な値: true, false
requireBillingAddress	boolean このパラメータをtrueに設定すると、エンドユーザーに請求先住所を入力するフォームが表示されます。 オンライン決済とコンビニ払いには適用されません。 必須: いいえ (デフォルトは false) 指定可能な値: true, false
showCvv	boolean CVVなしを許可されているストアで、このパラメータを false に設定すると、ウィジェットのフォームでCVV 入力フィールドが表示されなくなります。 必須: いいえ (デフォルトは true) 指定可能な値: true, false
locale	string このパラメータでは、ウィジェットを表示する際に使用する言語を指定します。auto に設定すると、ブラウザの言語設定が使用されます。 必須: いいえ (デフォルトは auto) 指定可能な値: auto, en-us, ja-jp, zh-tw, zh-cn, en, ja, zh
univapayCustomerId	string (UUID) このパラメータを指定すると、エンドユーザーはクレジットカード情報を保存するかどうかの選択肢が表示されます。ユーザーが保存を選択すると、作成されたトランザクショントークンは、指定されたカスタマーIDと関連付けられます。これによって、次回に同じカスタマーIDを指定してウィジェットを表示した時、エンドユーザーは保存されたトランザクショントークンから選択して、トラザクションを完了することができます。 token type パラメータに one_time を指定するか、指定を省略した場合、ユーザーがカード情報を保存することを選択すると、 recurring トークンが代わりに作成されます。tokenType パラメータを recurring に指定すると、エンドユーザーがカード情報の保存を選択しない場合に、トランザクショントークンが作成されなくなります。 注: このパラメータを使用するには、無制限(infinite)のリカーリングトークンの作成権限が必要です。 必須: いいえ 指定可能な値: 任意のUUID
cvvAuthorize	boolean このパラメータでtrue を指定した場合、 認証リクエストを行います。認証リクエストが失敗した場合は、トークンは戻されません。checkout が token かつ tokenType が recurring である場合のみ有効です。 必須: いいえ (デフォルト値は false ) 指定可能な値: true, false
allowCardInstallments	boolean このパラメータでtrue を指定した場合、分割払いのプルダウンセレクトを表示します。 Checkout が payment かつ token type がone_timeか recurring である場合のみ有効です。カード会社の分割払いが可能な接続先である場合のみ有効です。 必須: いいえ (デフォルト値は false ) 指定可能な値: true, false
autoSubmit	boolean このパラメータでtrue を指定した場合、トランザクションが完了すると、ウィジェットは呼び出し元の form 要素を自動的に送信します。 必須: いいえ (デフォルトは false) 指定可能な値: true, false
autoClose	boolean このパラメータでtrue を指定した場合、トランザクションが完了すると、ウィジェットが自動的に閉じます。 必須: いいえ (デフォルトは false) 指定可能な値: true, false
usageLimit	string このパラメータでは、リカーリングトークンの利用制限を指定します。指定した期間で、1つの課金のみを作成できます。 必須: 制限付きのリカーリングトークン作成権限でリカーリングトークンを作成する場合 指定可能な値: daily, weekly, monthly, annually
qrColor	string (HexColor) チェックアウトにqrを指定している場合、QRコードの色がこのパラメータで指定したカラーコードの色に変更されます。 必須: いいえ 指定可能な値: 16進カラーコード
qrLogoType	string チェックアウトにqrを指定している場合、このパラメータを利用して、QRコードの指定位置にストアのロゴ(未設定の場合は加盟店のロゴ)を埋め込みます。 必須: いいえ (デフォルトはNone) 指定可能な値: Background, Centered, None
horizontalInlineLayout	boolean このパラメータでは、ラベルをフィールドの左側に配置にすることができます。 Required: No (defaults to false) Allowed values: true/false
metadata	作成されるトランザクショントークンに設定するメタデータを指定します。 メタデータを指定する方式は、ウィジェットをHTMLタグでセットアップするか、Javascriptでセットアップするかによって異なります。 HTMLタグを使用する場合、他のパラメータで使われていない任意の data 属性を指定することができます。 例：data-foo="bar" と指定すると、キーが foo で値が bar のメタデータを指定することになります。 Javascriptを使用する場合、UnivapayCheckout.create を呼び出す際に、 metadata パラメータにオブジェクトを指定します。 例：UnivapayCheckout.create({ ... metadata: { foo: "bar" } }) このJSONの値の有効な型は、配列、文字列、数値、null のいずれかです。 CSV課金で利用可能なunivapay-reference-id（フリーフォーマット）を追加すれば作成されるトランザクショントークンにリファレンスIDを関連付けられます 例：metadata:{ “univapay-reference-id”: “1234” } 必須: いいえ 指定可能な値: HTMLの場合、任意の文字列。Javascriptの場合、ネストしていない Javascript オブジェクト



コールバック

ウィジェットの特定のアクションに応じて呼び出されるコールバック関数をセットアップするには、いくつかの方法があります。
ひとつは、3種類のカスタムイベントに対するイベントリスナーを追加する方法です。このカスタムイベントは、ウィジェットが表示された時・閉じられた時・支払い処理が正常に完了した時に配信されます。ウィジェットが表示された時・閉じられた時のイベント名はそれぞれ univapay:opened、univapay:closed です。これらのイベントではそれ以外の情報はありません。
支払い処理が完了した際には univapay:success という名前のイベントが配信されます。このイベントには、作成されたリソースに関する情報が detail という名前のオブジェクトとして含まれます。detail.resourceType は charge, subscription, transactionToken のいずれかで、作成されたリソースの種類を特定します。detail.response はリソースを作成した際のAPIからの結果のJSONが格納されます。

これらのイベントに対するコールバック関数をセットアップする他の方法では、Javascriptでウィジェットをセットアップする必要があります。この場合、UnivapayCheckout.create を呼び出す際に、以下のようにパラメータとしてコールバックを指定します:<JavaScript>

UnivapayCheckout.create({
  ...
  opened: function () { console.log("Widget Opened") },
  closed: function () { console.log("Widget Closed") },
  onSuccess: function (result) { console.log(result) },
  onError: function (error) { console.log(error) },

  callback: function (result) { console.log(result) } // deprecated
})


エラー

ウィジェットを使う際には、3種類のエラーが発生します。
1つ目は、例えば amountパラメータにマイナスの数値を指定したり、文字列を指定したりするなど、不正なパラメータ値を指定した場合です。この時エラーメッセージがボタンの代わりに表示されます（HTMLタグでウィジェットをセットアップした場合）。
2つ目は、例えばリカーリングトークンの作成権限がない状態で token type に recurring を指定した場合のように、チェックアウト情報とパラメータに矛盾がある場合に発生します。この場合、ウィジェットが表示された時にエラーメッセージが表示されます。
3つ目は、ウィジェットからのリクエストに対してAPIがエラーを返す場合です。最大課金額を超過した課金を作成しようとした時など、複数の要因からなります。このエラーはウィジェットの結果画面に表示されます。

ウィジェットのセットアップ

Javascriptでウィジェットをセットアップする。ウィジェットを表示するページに以下の行を含める必要があります:<HTML>

<script src="https://widget.univapay.com/client/checkout.js"></script>

Javascript でウィジェットをセットアップするには、UnivapayCheckout.create を呼び出すコードを挿入してください。
例:<JavaScript>

var checkout = UnivapayCheckout.create({
  appId: "<TOKEN>",
  checkout: "payment",
  amount: 1000,
  currency: "jpy",
});

これは 1000 円を支払うウィジェットオブジェクトを作成します。この方法は、HTMLタグによるセットアップとは異なり、ページ上に自動でボタンを作成するわけではありません。そのため、代わりにウィジェットを表示するためのボタンや、その他のUI要素を実装する必要があります。
ウィジェットを表示するには、UnivapayCheckout.create で返されるオブジェクトに対して open 関数を呼び出してください。上記の例を活用する場合は、checkout.open() を実行してください。