ウィジェット:Javascript
ウィジェットパラメーター
Parameters | |
appId | string (TOKEN) このパラメータでは、ウィジェットが支払いを行うストアで発行したアプリケーショントークンを指定します。 必須: はい 指定可能な値: 有効なアプリケーショントークン |
checkout | string このパラメータでは、トランザクショントークンを作成するだけ( token )か、トランザクショントークンと課金もしくは定期課金の両方を作成する (payment )か、トランザクショントークンのみ作成しQRコードを表示する(qr )かを指定します。表示されたQRコードの読み取りについては、こちらをご覧ください。必須: はい 指定可能な値: token , payment |
paymentType | string このパラメータを利用すると、選択ページを経由することによって、支払方法を指定することができます。指定したPaymentTypeが利用不可だった場合、チェックアウトでエラーを返します。 必須: はい 指定可能な値: card , konbini, paidy, online |
paymentTypes | string このパラメータを利用すると、支払方法をフィルタリングさせることができます。 必須: いいえ(デフォルトは 全ての支払い方法 )指定可能な値: “,”で区切られた
|
amount | number このパラメータでは、ワンタイム課金の場合に課金金額を指定します。定期課金の場合は、1回の支払いで課金する金額を指定します。分割払いの定期課金の場合は、すべての支払の合計金額を指定します。補助通貨を使用する通貨の場合、補助通貨を含んだ金額を指定するよう注意してください。 例: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 このパラメータでは、作成された定期課金の2回目の課金を行う日付を指定します(初回の課金は定期課金作成時に行われます)。 必須: いいえ 指定可能な値: 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 | stringcapture パラメータを false を指定したうえでこのパラメータを設定した場合、ここで指定した日時に課金が自動的にキャプチャされます。必須: いいえ 指定可能な値: ISO8601 形式の日時 |
expirationPeriod | string このパラメータで期間を指定すると、決済が行われてから振込をするまでの期間を設定できます。 銀行振込/コンビニ決済で有効です。 必須: いいえ(デフォルトは30日) 指定可能な値: ISO8601 duration text。 例:P●D、P●M(P1D、P5D、P0M、P1M) |
expirationTimeShift | string このパラメータで時間を指定すると、振込期限の時間を設定できます。 銀行振込/コンビニ決済で有効です。 必須: いいえ(デフォルトは決済が行われた時間) 指定可能な値: ISO8601 例:12:00:00+12:00 |
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 が かつ 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 )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()
を実行してください。