ウィジェット:Javascript


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

Parameters
appIdstring (TOKEN)
このパラメータでは、ウィジェットが支払いを行うストアで発行したアプリケーショントークンを指定します。
必須: はい
指定可能な値: 有効なアプリケーショントークン
checkoutstring
このパラメータでは、トランザクショントークンを作成するだけ(token)か、トランザクショントークンと課金もしくは定期課金の両方を作成する (payment)か、トランザクショントークンのみ作成しQRコードを表示する(qr)かを指定します。表示されたQRコードの読み取りについては、こちらをご覧ください。
必須: はい
指定可能な値:
token, payment
paymentTypestring
このパラメータを利用すると、選択ページを経由することによって、支払方法を指定することができます。指定したPaymentTypeが利用不可だった場合、チェックアウトでエラーを返します。
必須: はい
指定可能な値: card, konbini, paidy, online
paymentTypesstring
このパラメータを利用すると、支払方法をフィルタリングさせることができます。

必須: いいえ(デフォルトは 全ての支払い方法)
指定可能な値: “,”で区切られたcard, konbini, paidy, online, pay_pay_online, we_chat_online, alipay_online, alipay_plus_online
amountnumber
このパラメータでは、ワンタイム課金の場合に課金金額を指定します。定期課金の場合は、1回の支払いで課金する金額を指定します。分割払いの定期課金の場合は、すべての支払の合計金額を指定します。補助通貨を使用する通貨の場合、補助通貨を含んだ金額を指定するよう注意してください。
例:9.50 USD の場合は 950 と表記します。
必須: はい
指定可能な値:
正の整数
currencystring (currency code)
このパラメータでは、課金金額の通貨を指定します。
必須: はい
指定可能な値: 通貨コード
tokenTypestring
このパラメータでは、作成するトランザクショントークンの種類を指定します。
必須: いいえ (デフォルトは one_time)
指定可能な値: one_time, recurring, subscription
subscriptionPeriodstring
このパラメータでは、定期課金の課金の間隔を指定します。
必須: トークンタイプが subscription の場合
指定可能な値: daily(毎日), weekly(毎週), biweekly(隔週), monthly(毎月), quarterly(3ヶ月), semiannually(6ヶ月), annually(毎年)
subscriptionIdstring
このパラメータを使用すると、定期課金の作成ではなく、指定された定期課金に適用可能なトランザクショントークンを作成します。
必須: いいえ
指定可能な値: アプリケーショントークンに紐付いたストアに作成されている定期課金のID
installmentPlanstring
このパラメータでは、分割払いの定期課金を作成します。固定の回数の支払い(fixed_cycles)か、都度の課金額を固定にする(fixed_cycle_amount)かを指定できます。
必須: いいえ
指定可能な値: fixed_cycles, fixed_cycle_amount
installmentQtynumber
分割払いプランに fixed_cyclesを指定している場合、このパラメータで支払回数を指定します。 fixed_cycle_amount を指定した場合は、課金ごとの金額を指します。
必須: 分割払いプランを指定している場合
指定可能な値: 正の整数
installmentInitialAmountnumber
定期課金が分割払いプランの場合、このパラメータでは初回の支払いの金額を指定します。
必須: いいえ
指定可能な値: 正の整数
subscriptionInitialAmountnumber
分割払いプランではない定期課金の場合、このパラメータでは初回の支払いの金額を指定します。
必須: いいえ
指定可能な値:
正の整数
subscriptionStartstring
このパラメータでは、作成された定期課金の2回目の課金を行う日付を指定します(初回の課金は定期課金作成時に行われます)。
必須: いいえ
指定可能な値: ISO8601
形式の日付
headerstring
このパラメータでは、ウィジェットのヘッダのバーに表示されるテキストを指定します。
必須: いいえ (デフォルトは “UnivaPay”)
指定可能な値: 任意の文字列
titlestring
このパラメータが設定されている場合は、ウィジェット内のストアの名前がこの値に置き換えられます。
必須: いいえ (defaults to the name of the store)
指定可能な値: 任意の文字列
namestring
このパラメータでは、チェックアウトが正常に完了した際に挿入される、 input 要素の name 属性値を指定できます。この input 要素は、チェックアウトによって作成されたリソースのIDを保持します。なお、この指定は “メイン” のリソースにのみ適用される事に注意してください。
トランザクショントークンのみが作成される場合、input 要素の name 属性はこのパラメータで指定された値になります。省略した場合、 値はunivapayTokenId になります。
リカーリングトークンによって課金もしくは定期課金が作成される場合、input 要素の name 属性は、このパラメータで指定された値になります。省略した場合、値はunivapaySubscriptionId もしくは univapayChargeId になります。この時、トランザクショントークンを保持する input 要素の name 属性値は常に univapayTokenId となります。
必須: いいえ
指定可能な値: 任意の文字列
captureboolean
課金が作成される場合、このパラメータを false に指定することで、キャプチャを行わずオーソリのみを行うようにします。その際、課金は手動でキャプチャするか、capture at パラメータを指定することで自動的にキャプチャすることができます。
必須: いいえ (デフォルトは true)
指定可能な値: true, false
captureAtstring
capture パラメータを false を指定したうえでこのパラメータを設定した場合、ここで指定した日時に課金が自動的にキャプチャされます。
必須: いいえ
指定可能な値: ISO8601 形式の日時
emailstring
このパラメータにメールアドレスを指定すると、ウィジェットのフォームのメールアドレスフィールドに初期値として入力されます。
必須: いいえ
指定可能な値: メールアドレス
addressboolean
このパラメータをtrue に設定すると、エンドユーザーに住所を入力するフォームが表示されます。
必須: いいえ (デフォルトは false)
指定可能な値: true, false
requireEmailboolean
このパラメータをtrueに設定すると、エンドユーザーにメールアドレスを入力するフォームが表示されます。
カードとコンビニ払いには適用されません。
必須: いいえ (デフォルトは false)
指定可能な値: true, false
requirePhoneNumberboolean
このパラメータをtrueに設定すると、エンドユーザーに電話番号を入力するフォームが表示されます。

Required: いいえ (デフォルトは false)
指定可能な値: true, false
requireBillingAddressboolean
このパラメータをtrueに設定すると、エンドユーザーに請求先住所を入力するフォームが表示されます。
オンライン決済とコンビニ払いには適用されません。
必須: いいえ (デフォルトは false)
指定可能な値: true, false
showCvvboolean
CVVなしを許可されているストアで、このパラメータを false に設定すると、ウィジェットのフォームでCVV 入力フィールドが表示されなくなります。
必須: いいえ (デフォルトは true)
指定可能な値: true, false
localestring
このパラメータでは、ウィジェットを表示する際に使用する言語を指定します。auto に設定すると、ブラウザの言語設定が使用されます。
必須: いいえ (デフォルトは auto)
指定可能な値: auto, en-us, ja-jp, zh-tw, en, ja, zh
univapayCustomerIdstring (UUID)
このパラメータを指定すると、エンドユーザーはクレジットカード情報を保存するかどうかの選択肢が表示されます。ユーザーが保存を選択すると、作成されたトランザクショントークンは、指定されたカスタマーIDと関連付けられます。これによって、次回に同じカスタマーIDを指定してウィジェットを表示した時、エンドユーザーは保存されたトランザクショントークンから選択して、トラザクションを完了することができます。
token type パラメータに one_time を指定するか、指定を省略した場合、ユーザーがカード情報を保存することを選択すると、 recurring トークンが代わりに作成されます。tokenType パラメータを recurring に指定すると、エンドユーザーがカード情報の保存を選択しない場合に、トランザクショントークンが作成されなくなります。
注: このパラメータを使用するには、無制限(infinite)のリカーリングトークンの作成権限が必要です。
必須: いいえ
指定可能な値: 任意のUUID
cvvAuthorizeboolean
このパラメータでtrue を指定した場合、 認証リクエストを行います。認証リクエストが失敗した場合は、トークンは戻されません。checkouttoken かつ tokenTyperecurring である場合のみ有効です。
必須: いいえ (デフォルト値は false )
指定可能な値: true, false
allowCardInstallmentsboolean
このパラメータでtrue を指定した場合、分割払いのプルダウンセレクトを表示します。

Checkoutpayment かつ token type がone_timeか recurring である場合のみ有効です。カード会社の分割払いが可能な接続先である場合のみ有効です。

必須: いいえ (デフォルト値は false )
指定可能な値:
true, false
autoSubmitboolean
このパラメータでtrue を指定した場合、トランザクションが完了すると、ウィジェットは呼び出し元の form 要素を自動的に送信します。
必須: いいえ (デフォルトは false)
指定可能な値: true, false
autoCloseboolean
このパラメータでtrue を指定した場合、トランザクションが完了すると、ウィジェットが自動的に閉じます。
必須: いいえ (デフォルトは false)
指定可能な値: true, false
usageLimitstring
このパラメータでは、リカーリングトークンの利用制限を指定します。指定した期間で、1つの課金のみを作成できます。
必須: 制限付きのリカーリングトークン作成権限でリカーリングトークンを作成する場合
指定可能な値: daily, weekly, monthly, annually
qrColorstring (HexColor)
チェックアウトにqrを指定している場合、QRコードの色がこのパラメータで指定したカラーコードの色に変更されます。
必須: いいえ
指定可能な値: 16進カラーコード
qrLogoTypestring
チェックアウトにqrを指定している場合、このパラメータを利用して、QRコードの指定位置にストアのロゴ(未設定の場合は加盟店のロゴ)を埋め込みます。
必須: いいえ (デフォルトはNone)
指定可能な値: Background, Centered, None
metadataこのパラメータでは、作成されるトランザクショントークンに設定するメタデータを指定します。メタデータを指定する方式は、ウィジェットをHTMLタグでセットアップするか、Javascriptでセットアップするかによって異なります。
HTMLタグを使用する場合、他のパラメータで使われていない任意の data 属性を指定することができます。
例:data-foo="bar" と指定すると、キーが foo で値が bar のメタデータを指定することになります。
Javascriptを使用する場合、UnivapayCheckout.create を呼び出す際に、以下のように metadata パラメータにオブジェクトを指定します:
UnivapayCheckout.create({ ... metadata: { foo: "bar" } })
このJSONの値の有効な型は、配列、文字列、数値、null のいずれかです。
CSV課金で利用可能なunivapayReferenceId(フリーフォーマット)を追加すれば作成されるトランザクショントークンにリファレンスIDを関連付けられます
必須: いいえ
指定可能な値: HTMLの場合、任意の文字列。Javascriptの場合、ネストしていない Javascript オブジェクト



コールバック

ウィジェットの特定のアクションに応じて呼び出されるコールバック関数をセットアップするには、いくつかの方法があります。
ひとつは、3種類のカスタムイベントに対するイベントリスナーを追加する方法です。このカスタムイベントは、ウィジェットが表示された時・閉じられた時・支払い処理が正常に完了した時に配信されます。ウィジェットが表示された時・閉じられた時のイベント名はそれぞれ univapay:openedunivapay:closed です。これらのイベントではそれ以外の情報はありません。
支払い処理が完了した際には univapay:success という名前のイベントが配信されます。このイベントには、作成されたリソースに関する情報が detail という名前のオブジェクトとして含まれます。detail.resourceTypecharge, 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 typerecurring を指定した場合のように、チェックアウト情報とパラメータに矛盾がある場合に発生します。この場合、ウィジェットが表示された時にエラーメッセージが表示されます。
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() を実行してください。