ウィジェット：Javascript
ウィジェットパラメーター
| Parameters | |
| appId | string (TOKEN) このパラメータでは、ウィジェットが支払いを行うストアで発行したアプリケーショントークンを指定します。 必須: はい 指定可能な値: 有効なアプリケーショントークン |
| checkout | string このパラメータでは、トランザクショントークンを作成するだけ( token)か、トランザクショントークンと課金もしくは定期課金の両方を作成する (payment)か、トランザクショントークンのみ作成しQRコードを表示する(qr)かを指定します。表示されたQRコードの読み取りについては、こちらをご覧ください。必須: はい 指定可能な値: token, payment |
| paymentType | string このパラメータを利用すると、選択ページを経由することによって、支払方法を指定することができます。指定したPaymentTypeが利用不可だった場合、チェックアウトでエラーを返します。 必須: はい 指定可能な値: card, konbini, paidy, online,bank_transfer |
| paymentTypes | string | string[] このパラメータを利用すると、支払方法をフィルタリングさせることができます。 必須: いいえ(デフォルトは 全ての支払い方法)指定可能な値: “,”で区切られた ※各決済手段が利用可能な設定の場合、ブランドで更にフィルタリングすることができます。 下記パラメータを利用する場合、 card, konbiniは指定不要です。クレジット： visa,mastercard,maestro,diners_club,discover,jcb,unionpay,american_expressコンビニ： seven_eleven,family_mart,lawson,mini_stop,seico_mart,pay_easy,circle_k,sunkus,daily_yamazaki,yamazaki_daily_store |
| amount | number このパラメータでは、ワンタイム課金の場合に課金金額を指定します。 回数無制限の定期課金の場合は、１回の支払いで課金する金額を指定します。分割払いおよび回数制限付き定期課金の場合は、すべての支払の合計金額を指定します。補助通貨を使用する通貨の場合、補助通貨を含んだ金額を指定するよう注意してください。 例：9.50 USD の場合は 950 と表記します。必須: はい 指定可能な値: 正の整数 |
| currency | string (currency code) このパラメータでは、課金金額の通貨を指定します。 必須: はい 指定可能な値: 通貨コード |
| tokenType | string このパラメータでは、作成するトランザクショントークンの種類を指定します。 必須: いいえ (デフォルトは one_time)指定可能な値: one_time, recurring, subscription |
| productCodes | string 商品コードの指定を行い、商品に紐づいた情報を基に決済を行います。 都度課金商品は ","で区切ることで複数指定することができます。(定期課金商品は不可)このパラメータを指定する場合は、appId,checkoutを指定する必要があります。 ※商品に含まれる情報をパラメータで別途指定すると商品の情報より優先されますのでご注意ください。 商品に含まれない情報であればその他パラメータで併用可能です。 ex)初回0円の定期課金を作成する際はcvv-authorizeの指定が必要です。 仮売上を行いたい場合はcaptureを併用して指定してください。 必須:いいえ 指定可能な値:事前に作成した商品の商品コード インラインフォームでの利用:可 |
| subscriptionPeriod | string このパラメータでは、定期課金の課金の間隔を指定します。 必須: トークンタイプが subscription の場合指定可能な値: daily（毎日）, weekly（毎週）, biweekly（隔週）, monthly（毎月）, quarterly（3ヶ月）, semiannually（6ヶ月）, annually（毎年）ISO8601 duration text の間隔… P●D(〇日毎),P●W(〇週間毎),P●M(〇か月毎),P●Y(〇年毎) |
| subscriptionId | string このパラメータを使用すると、定期課金の作成ではなく、指定された定期課金に適用可能なトランザクショントークンを作成します。 必須: いいえ 指定可能な値: アプリケーショントークンに紐付いたストアに作成されている定期課金のID |
| installmentPlan | string このパラメータでは、分割払いの定期課金を作成します。固定の回数の支払い( fixed_cycles)か、都度の課金額を固定にする(fixed_cycle_amount)かを指定できます。必須: いいえ 指定可能な値: fixed_cycles, fixed_cycle_amount※5/11に仕様変更があり、このパラメータを指定したすべての定期課金はクレジットカード会社の分割払いになります。 また、 fixed_cycle_amountは利用できなくなります。 |
| installmentQty | number 分割払いプランに fixed_cyclesを指定している場合、このパラメータで支払回数を指定します。必須: 分割払いプランを指定している場合 指定可能な値: 3, 5, 6, 10, 12, 15, 18, 20, 24 |
| installmentInitialAmount | ※5/11に仕様変更がありこのパラメータは利用不可になりました。 クレジットカード分割の定期課金では初回課金金額を指定できません。 回数指定の定期課金を作成する場合はsubscriptionInitialAmountを指定してください。 |
| subscriptionPlan | string このパラメータでは、回数指定の定期課金を作成します。固定の回数の支払い( fixed_cycles)か、都度の課金額を固定にする(fixed_cycle_amount)かを指定できます。必須: いいえ 指定可能な値: fixed_cycles, fixed_cycle_amount |
| subscriptionQty | number 回数指定プランに fixed_cyclesを指定している場合、このパラメータで支払回数を指定します。 fixed_cycle_amount を指定した場合は、課金ごとの金額を指します。必須: 回数指定プランを指定している場合 指定可能な値: 正の整数 |
| subscriptionInitialAmount | number 分割払いプランではない定期課金の場合、このパラメータでは初回の支払いの金額を指定します。 初回カード登録（0円）の定期課金の場合、このパラメータに「0」を指定する必要があります。 必須: いいえ 指定可能な値: 正の整数 ※5/11に仕様変更があり、回数指定の定期課金を作成する場合はこのパラメータで初回金額を指定してください。 |
| 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までの整数 |
| subscriptionPreserveEndOfMonth | boolean periodがmonthlyで、指定された定期課金サイクルの開始日が月末日である場合、trueを指定すると、以降は月の最終日に料金を請求できます。例えば、開始日が2018-06-30の場合、次の請求はtrueの場合は2018-07-31、falseの場合は2018-07-30となります。必須: いいえ(デフォルトはfalse) 指定可能な値:true,false |
| subscriptionRetryInterval | string 定期課金の支払いが失敗したときにリトライを行う間隔を指定します。 必須: いいえ 指定可能な値: ISO 8601 duration 形式の期間 ※指定する間隔は1日以上かつ定期課金のサイクルよりも短い必要があります。 例: P5D…失敗後5日毎にリトライ |
| header | string このパラメータでは、ウィジェットのヘッダのバーに表示されるテキストを指定します。 必須: いいえ (デフォルトは “UnivaPay”) 指定可能な値: 任意の文字列 |
| title | string このパラメータが設定されている場合は、ウィジェット内のストアの名前がこの値に置き換えられます。 必須: いいえ (defaults to the name of the store) 指定可能な値: 任意の文字列 |
| description | string このパラメータが設定されている場合は、ウィジェット内のサブヘーダーでdescriptionの文字列をみせます。 必須: いいえ 指定可能な値: 任意の文字列 |
submitButtonText | string このパラメータが設定されている場合は、ウィジェット内の支払いボタンがこの値に置き換えられます。 必須: いいえ 指定可能な値: 任意の文字列 |
| 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 を指定したうえでこのパラメータを設定した場合、ここで指定した日時に課金が自動的にキャプチャされます。コンビニ、銀行振込の場合は入金の期限日時を指定することができ、 expirationPeriodやデフォルトの振込期間の設定よりも優先します。※「セブンイレブン」「セイコーマート/他支払（サークルK/サンクス/ペイジー）」は時刻指定が利用できないため、時刻は無視されその日までという扱いになります。 クレジット:キャプチャの日時は仮売上から1時間後かつ7日以内である必要があります。 コンビニ:決済申込から入金期限日時は30分後かつ60日以内である必要があります。 必須: いいえ 指定可能な値: ISO8601 形式の日時 |
| expirationPeriod | string このパラメータで期間を指定すると、決済が行われてから振込をするまでの期間を設定できます。 銀行振込/コンビニ決済で有効です。 必須: いいえ(デフォルトは銀行振込：1週間、コンビニ決済：30日) 指定可能な値: ISO8601 duration text。 例：P●D、P●M（P1D、P5D、P0M、P1M） |
| bankTransferExpirationPeriod | string このパラメータで時間を指定すると、銀行振込の振込期限（日にち）を設定できます。 必須: いいえ(デフォルトは1週間) 指定可能な値: ISO8601 duration text 例：P●D、P●M（P1D、P5D、P0M、P1M） |
| convenienceStoreExpirationPeriod | string このパラメータで時間を指定すると、コンビニのお支払い期限（日にち）を設定できます。 必須: いいえ(デフォルトは30日) 指定可能な値: ISO8601 duration text 例：P●D、P●M（P1D、P5D、P0M、P1M） |
| expirationTimeShift | string このパラメータで時間を指定すると、振込期限の時間を設定できます。 銀行振込/コンビニ決済で有効です。 ※このパラメータで時間を指定する場合、expirationPeriodは1日以上を指定してください ※「セブンイレブン」「セイコーマート/他支払（サークルK/サンクス/ペイジー）」は時刻指定が利用できないため、このパラメータは無視されます。 必須: いいえ(デフォルトは銀行振込：23:59:59、コンビニ決済：決済が行われた時間) 指定可能な値: ISO8601 例：12:00:00+12:00 |
| bankTransferExpirationTimeShift | string このパラメータで時間を指定すると、銀行振込の振込期限（時間）を設定できます。 ※このパラメータで時間を指定する場合、expirationPeriodは1日以上を指定してください。 ※「セブンイレブン」「セイコーマート/他支払（サークルK/サンクス/ペイジー）」は時刻指定が利用できないため、本パラメータは無視されます。 必須: いいえ(デフォルトは23:59:59) 指定可能な値: ISO8601（例：12:00:00+09:00） |
| convenienceStoreExpirationTimeShift | string このパラメータで時間を指定すると、コンビニのお支払い期限（時間）を設定できます。 ※このパラメータで時間を指定する場合、expirationPeriodは1日以上を指定してください。 ※「セブンイレブン」「セイコーマート/他支払（サークルK/サンクス/ペイジー）」は時刻指定が利用できないため、本パラメータは無視されます。 必須: いいえ(デフォルトは決済が行われた時間) 指定可能な値: ISO8601（例：12:00:00+09:00） |
| string このパラメータにメールアドレスを指定すると、ウィジェットのフォームのメールアドレスフィールドに初期値として入力されます。 必須: いいえ 指定可能な値: メールアドレス | |
| address | boolean このパラメータを true に設定すると、エンドユーザーに住所を入力するフォームが表示されます。必須: いいえ (デフォルトは false)指定可能な値: true, false |
| requireName | boolean このパラメータを trueに設定すると、エンドユーザーに名前を入力するフォームが表示されます。Paidyとコンビニ払い、銀行振込には適用されませ Required: いいえ (デフォルトは false)指定可能な値: true, false |
| requireEmail | boolean このパラメータを trueに設定すると、エンドユーザーにメールアドレスを入力するフォームが表示されます。カードとコンビニ払いには適用されません。 必須: いいえ (デフォルトは false)指定可能な値: true, false |
| requirePhoneNumber | boolean このパラメータを trueに設定すると、エンドユーザーに電話番号を入力するフォームが表示されます。4桁以上の電話番号を入力可能です。 必須: いいえ (デフォルトは false)指定可能な値: true, false |
| requireBillingAddress | boolean このパラメータを trueに設定すると、エンドユーザーに請求先住所を入力するフォームが表示されます。オンライン決済とコンビニ払いには適用されません。 必須: いいえ (デフォルトは false)指定可能な値: true, false |
| showCvv | boolean CVVなしを許可されているストアで、このパラメータを false に設定すると、ウィジェットのフォームでCVV 入力フィールドが表示されなくなります。必須: いいえ (デフォルトは true)指定可能な値: true, false |
| locale | string このパラメータでは、ウィジェットを表示する際に使用する言語を指定します。 auto に設定すると、ブラウザの言語設定が使用されます。必須: いいえ (デフォルトは auto)指定可能な値: auto（ブラウザの言語に依存）,zh-tw（簡体字）, zh-cn（繁体字）, en（英語）, ja（日本語）, ko（韓国語）,th（タイ語）,ru（ロシア語） |
| univapayCustomerId | string (UUID) このパラメータを指定すると、エンドユーザーはクレジットカード情報を保存するかどうかの選択肢が表示されます。ユーザーが保存を選択すると、作成されたトランザクショントークンは、指定されたカスタマーIDと関連付けられます。これによって、次回に同じカスタマーIDを指定してウィジェットを表示した時、エンドユーザーは保存されたトランザクショントークンから選択して、トラザクションを完了することができます。 token type パラメータに one_time を指定するか、指定を省略した場合、ユーザーがカード情報を保存することを選択すると、 recurring トークンが代わりに作成されます。tokenType パラメータを recurring に指定すると、エンドユーザーがカード情報の保存を選択しない場合に、トランザクショントークンが作成されなくなります。注: このパラメータを使用するには、無制限( infinite)のリカーリングトークンの作成権限が必要です。必須: いいえ 指定可能な値: 任意のUUID |
| cvvAuthorize | boolean このパラメータで true を指定した場合、 クレジットカードの認証リクエストを行います。認証リクエストが失敗した場合は、リカーリングトークンは作成されません。 カード情報の登録のみ行う場合：Checkout は token、token type は recurring を指定してください。初回0円の定期課金を作成する場合：このパラメータでカード情報の認証のみ行います。checkoutは payment、token typeはsubscriptionを指定してください。必須: いいえ (デフォルト値は false ) 指定可能な値: true, false |
| allowCardInstallments | boolean このパラメータで true を指定した場合、分割払いのプルダウンセレクトを表示します。Checkout が recurring である場合のみ有効です。カード会社の分割払いが可能な接続先である場合のみ有効です。必須: いいえ (デフォルト値は false )指定可能な値: true, false |
| cardInstallmentOptions | string このパラメータでは、allowCardInstallmentsがtrue の時、フォームに表示する分割回数を指定することができます。 必須: いいえ 指定可能な値: 1, 3, 5, 6, 10, 12, 15, 18, 20, 24, revolving |
| 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 |
| hideRecurringCheckbox | boolean このパラメータでtrueを指定した場合、リカリングトークンを追加する時に「個人情報の同意」のチェックボックスを非表示にします。 必須：いいえ（デフォルトはfalse） 指定可能な値：true, false |
| customFields | string boolean このパラメータでは、ユーザーの入力欄もしくは選択肢をカスタマイズすることができます。下記パラメータで各項目の指定を行ってください。 label :ウィジェットに表示させる入力欄/選択肢のタイトルを指定できます。 type : selectもしくはstring で、そのカスタムフィールドが選択肢か入力欄かを指定します。required :: trueもしくはfalseでそのカスタムフィールドが必須かどうかを指定します。options :カスタムフィールドが選択肢の場合、”,”で区切ることで次の選択肢の内容を指定します。 必須: いいえ |
| metadata | 作成されるトランザクショントークンに設定するメタデータを指定します。UnivapayCheckout.create を呼び出す際に、 metadata パラメータにオブジェクトを指定します。例： UnivapayCheckout.create({ ... metadata: { foo: "bar" } })このJSONの値の有効な型は、配列、文字列、数値、 null のいずれかです。CSV課金で利用可能なunivapay-reference-id（フリーフォーマット）を追加すれば作成されるトランザクショントークンにリファレンスIDを関連付けられます 例：metadata:{ “univapay-reference-id”: “1234” } 必須: いいえ 指定可能な値: ネストしていない Javascript オブジェクト |
コールバック
ウィジェットからは、下記のイベントをウィンドウおよびコールバックのパラメータとして渡します。
- Opened (univapay:opened/opened): 決済フォームを開くことで発生するイベントです。その他の情報は含まれていません。
- Closed (univapay:closed/closed): 決済フォームを閉じることで発生するイベントです。その他の情報は含まれていません。
- Before closing (univapay:before-closing/beforeClosing): 決済フォームが終了すると発生するイベントです。その他の情報は含まれていません。falseを返すと、フォームが閉じることを防ぐことができます。
- Success (univapay:success/onSuccess): 決済が成功すると発生するイベントです。生成されたリソースのIDと処理の詳細情報が含まれています。
- Error (univapay:error/onError): いずれかの段階で決済処理が失敗することで発生するイベントです。生成されたリソースのIDが含まれています。
- Token created (univapay:token-created/onTokenCreated): トランザクショントークンが作成されたときに発生するイベントで、トークンの詳細情報が含まれています。定期課金やリカーリング課金のように作成済のトランザクショントークンを利用して決済をする場合は発生しません。
- Charge created (univapay:charge-created/onChargeCreated): 課金が作成されたときに発生するイベントで、課金の詳細情報が含まれています。成功したかどうかに関わらず発生します。
- Subscription created (univapay:subscription-created/onSubscriptionCreated): 定期課金が作成されたときに発生するイベントで、定期課金の詳細情報が含まれています。成功したかどうかに関わらず発生します。
- Validation error (univapay:validation-error/onValidationError):このイベントには各フィールドにエラーがある場合に発生します。エラーがない場合、または各フィールドがまだ選択されていない場合、オブジェクトにはオブジェクトは空白になります。
<script>
window.addEventListener("univapay:opened", (e) => { console.info("The widget was opened") }, false);
window.addEventListener("univapay:closed", (e) => { console.info("The widget was closed", e) }, false);
window.addEventListener("univapay:before-closing", (e) => { console.info("The widget will close", e) }, false);
window.addEventListener("univapay:success", (e) => { console.info("Success event ", e) }, false);
window.addEventListener("univapay:error", (e) => { console.error("Error event ", e) }, false);
window.addEventListener("univapay:token-created", (e) => { console.info("Token event ", e) }, false);
window.addEventListener("univapay:charge-created", (e) => { console.info("Charge event", e) }, false);
window.addEventListener("univapay:subscription-created", (e) => { console.info("Subscription event", e) }, false);
window.addEventListener("univapay:validation-error", (e) => { console.error("Validation error event", e) }, false);
</script>UnivapayCheckout.create({
...
opened: function () { console.log("Widget Opened") },
closed: function () { console.log("Widget Closed") },
beforeClosing: function () { return confirm("終了してもよろしいでしょうか？") },
onSuccess: function (result) { console.log(result) },
onError: function (error) { console.log(error) },
onTokenCreated: function (result) { console.log(result) },
onChargeCreated: function (result) { console.log(result) },
onSubscriptionCreated: function (result) { console.log(result) },
onValidationError: function (errors) { console.error(errors) },
callback: function (result) { console.log(result) } // 非推奨
})メタデータはフラットなJSONオブジェクトとして格納され、配列、文字列、数値、NULLが有効な型となります。
エラー
ウィジェットを使う際には、3種類のエラーが発生します。
1つ目は、例えば amountパラメータにマイナスの数値を指定したり、文字列を指定したりするなど、不正なパラメータ値を指定した場合です。この時エラーメッセージがボタンの代わりに表示されます（HTMLタグでウィジェットをセットアップした場合）。
2つ目は、例えばリカーリングトークンの作成権限がない状態で token type に recurring を指定した場合のように、チェックアウト情報とパラメータに矛盾がある場合に発生します。この場合、ウィジェットが表示された時にエラーメッセージが表示されます。
3つ目は、ウィジェットからのリクエストに対してAPIがエラーを返す場合です。最大課金額を超過した課金を作成しようとした時など、複数の要因からなります。このエラーはウィジェットの結果画面に表示されます。