Widget: Javascript

Setting up the widget

To set up the widget via Javascript., first you need include this line on the page that will contain the widget:

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

Then place a call to UnivapayCheckout.create. For example,

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

will create a widget object that will process a payment of 1000 JPY. Unlike the HTML setup, this will not automatically create a button on the page. Instead, you must create your own button or other UI element that will trigger the opening of the widget, which you can do by calling the open function on the object returned by UnivapayCheckout.create (in the above example, you would then call checkout.open().

Widget parameters

Parameters
appId	string (TOKEN) The application token that is linked to the store for which the widget will process the payment. Required: Yes Allowed values: a Authentication Token
checkout	string Determines which the widget will be used to create just a transaction token (token), both a transaction token and charge/subscription (payment), or both a transaction token and a QR code (qr). Required: Yes Allowed values: `token`, `payment`
paymentType	string Force the payment type to the given type, bypassing the selection page. The checkout will result in an error if the payment type is not available. Required: No Allowed values: `card`, konbini, paidy, `online`
paymentTypes	string \| string[] Filters the payment types to the given types. The checkout will result in an error when none of the payment types are available. Required: No Allowed values: `card, konbini, paidy, online, pay_pay_online, we_chat_online, alipay_online, alipay_plus_online`, konbini Card brands -> Always allow all card brands when `card` payment method is provided：`visa,mastercard,maestro,diners_club,discover,jcb,unionpay,american_express` Convinience stores -> Always allow all konbini brands when `konbini` payment method is provided：`seven_eleven,family_mart,lawson,mini_stop,seico_mart,pay_easy,circle_k,sunkus,daily_yamazaki,yamazaki_daily_store`
amount	number For a one-time charge, the amount that will be charged. For a regular subscription, the amount that will be charged per period. For subscriptions on installment plans, the total amount that will be charged over all cycles. Note that for currencies that use minor units, you must express the amount in terms of minor units. For example, an amount of 9.50 USD would be expressed as `950`. Required: Yes Allowed values: Positive integers
currency	string (currency code) The currency for that charge(s) that will be made. Required: Yes Allowed values: currency code
tokenType	string The type of the transaction token that will be created. Required: No (defaults to `one_time` if not set) Allowed values: `one_time`, `recurring`, `subscription`
productCodes	string When a product code is specified, payment is made based on the information associated with that product. Multiple items can be specified by separating each item with “,” (not available for recurring billing items). When specifying this parameter, `appId` and `checkout` must be specified. Please note that if information included in the product is specified separately as a parameter, it will take precedence over the product information. 　If the information is not included in the product, it can be used with other parameters. ex) `cvv-authorize` must be specified when creating a recurring charge of 0 yen for the first time. If you want to make a provisional sale, please specify it in combination with `capture`. Required: No Allowed values:Product codes for pre-made products Inline forms:Available
subscriptionPeriod	string The period that will be set on the created subscription. Required: Only if the token type is `subscription` Allowed values: `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `semiannually`, `annually`, Datetime string in ISO8601 format
subscriptionId	string Setting this parameter will cause the created transaction token to be patched onto the provided subscription, rather than creating a new subscription. Required: No Allowed values: An ID for a subscription on the store that is linked to the application token set on the widget
installmentPlan	string Setting this parameter will cause the created subscription to use installments, either with a fixed number of cycles (`fixed_cycles`) or `revolving` Required: No Allowed values: `fixed_cycles`,`revolving`
installmentQty	number If `installment plan` is set to `fixed_cycles`, represents the number of cycles. Required: Only if `installment plan` is set Allowed values: 3, 5, 6, 10, 12, 15, 18, 20, and 24
installmentInitialAmount	*The specification will be changed on 5/11, and this parameter will no longer be available. The initial amount cannot be specified for credit card installment. To create a Subscription with number of times , specify subscriptionInitialAmount.
subscriptionPlan	string Setting this parameter will cause the created subscription to use Subscription with number of times, either with a fixed number of cycles (`fixed_cycles`), a fixed amount per cycle (`fixed_cycle_amount`). Required: No Allowed values: `fixed_cycles`, `fixed_cycle_amount` Inline forms:Available
subscriptionQty	number If `subscription plan` is set to `fixed_cycles`, represents the number of cycles. If `subscription plan` is set to `fixed_cycle_amount`, represents the amount to charge per cycle. Required: Only if `subscription plan` is set Allowed values: `Positive integers` Inline forms:Available
subscriptionInitialAmount	number For subscriptions that do not use installment plans, this parameter represents the amount to be charged for the first charge. Required: No Allowed values: `Positive integers` *The specification was changed on 5/11, and when creating a subscription with number of times , please specify the initial amount in this parameter.
subscriptionStart	string A created subscription’s second charge will occur at this time (the first charge will occur when the subscription is created). Required: No Allowed values: `Datetime string in ISO8601 format`
subscriptionStartIn	string A created subscription’s second charge will occur after this duration (the first charge will occur when the subscription is created). If subscriptionStart is provided, this parameter will be ignored. Required: No Allowed values: ISO 8601 duration text
subscriptionStartDayOfMonth	number A created subscription’s second charge will occur on this specific day of the month (the first charge will occur when the subscription is created). Can be use in combination with `subscriptionStartIn` to start on a later month. When the da of month is in the past and no `subscriptionStartIn` was provided, the subscription will start on the same day during the next month (or last day if the month number of days is too low). If subscriptionStart is provided, this parameter will be ignored. Required: No Allowed values: Number from 1 to 31.
subscriptionRetryInterval	string Interval of time before retrying a charge on a failed payment created using this subscription. Required: No Allowed values: ISO 8601 duration text without time unit
header	string Sets the text displayed in the header bar of the widget. Required: No (defaults to “UnivaPay”) Allowed values: `Any string`
title	string If set, the name of the store in the widget will be replaced by this value. Required: No (defaults to the name of the store) Allowed values: `Any string`
description	string If set, the description text will be added in the widget sub-header Required: No Allowed values: `Any string`
`submitButtonText`	string If set, the transaction button will be set with this text. The `next` button prior to the payment button will remain unchanged Required: No Allowed values: `Any string`
name	string If this is set, then the name of the injected input element that holds the created resource ID upon successfully completing the checkout will be changed to this value. Note that this only applies to the “main” resource created — if only a transaction token was created, the name of the input element will be as specified in the `name` parameter, or `univapayTokenId` if not specified. If a subscription or a charge based on a recurring token was created, then the name of the input element will be as specified in the `name` parameter, or `univapaySubscriptionId` / `univapayChargeId` respectively if not specified. The injected element that holds the transaction token ID will always be `univapayTokenId` in this case. Required: No Allowed values: `Any string`
capture	boolean If a single charge is to be created, you can set this parameter to `false` in order to only authorize the charge without capturing it. The charge can then be captured manually, or automatically if the `capture at` parameter is set. Required: No (defaults to `true`) Allowed values: `true, false`
captureAt	string If `capture` is set to `false` and this parameter is set, the authorized charge will be automatically captured at the specified time. For convenience store and bank transfers, the date and time of the deposit deadline can be specified, and takes precedence over the `expirationPeriod` and default transfer period settings. For “7-Eleven” and “Seicomart”/Other Payments (“Circle K”/”Sunkus”/”Pay-easy”), the time cannot be specified, so the time will not be applied and the payment will be made only until the day of the payment. Credit: Capture date and time must be within 1 hour and 7 days after the provisional sales. Convenience store: The capture date and time must be 30 minutes after the payment application and within 60 days of the payment due date and time. Required:* No Allowed values`: Datetime string in ISO8601 format`
expirationPeriod	string This parameter allows you to set the time period between when the application is made and when the payment is made. This is valid for bank transfer/convenience store payments. Required: No Allowed values:Datetime string in ISO8601 format
expirationTimeShift	string This parameter allows you to set the deposit deadline time. This is valid for bank transfer/convenience store payments. If you use this parameter, expirationPeriod must be at least 1 day. This parameter is invalid forFor “7-Eleven” and “Seicomart”/Other Payments (“Circle K”/”Sunkus”/”Pay-easy”) because the time specification is not available. Required: No Allowed values:Datetime string in ISO8601 format
email	string If an email address is set in this parameter, it will be pre-filled into the email field in the widget’s form. Required: No Allowed values: `Any email address`
address	boolean If set to `true`, the end-user will be prompted to enter their email address and billing address. Use requireEmail and requireBillingAddress to enable one or the other only. Required: No (defaults to `false`) Allowed values: `true`, `false`
requireName	boolean If set to `true`, the end-user will be prompted to enter their name. Not applicable for paidy, convenience store payments, and banktransfer. Required: No (defaults to `false`) Allowed values: `true`, `false`
requireEmail	boolean If set to `true`, the end-user will be prompted to enter their email address. Does not applies for card and convenience store payments. Required: No (defaults to `false`) Allowed values: `true`, `false`
requirePhoneNumber	boolean If set to `true`, the end-user will be prompted to enter their phone number. Required: No (defaults to `false`) Allowed values: `true`, `false`
requireBillingAddress	boolean If set to `true`, the end-user will be prompted to enter their billing address. Does not applies for online and convenience store payments. Required: No (defaults to `false`) Allowed values: `true`, `false`
showCvv	boolean If set to `false` for a store that does not require a CVV to make a charge, the CVV input field will be hidden on the widget’s form. Required: No (defaults to `true`) Allowed values: `true`, `false`
locale	string The language that the widget will be displayed in. If set to `auto`, the browser’s language will be used. Required: No (defaults to `auto`) Allowed values: `auto, en-us, ja-jp, zh-tw, zh-cn, en, ja, zh, ko, th, ru`
univapayCustomerId	string (UUID) If this parameter is provided, the end-user will be given an option to save their card data. If they do so, then the transaction token that is created will be associated with the provided customer ID. Then, the next time the widget is opened with the same customer ID, the end-user will be able to select a saved card to complete their transaction. If the `token type` parameter is set to `one_time` (or is not set) and the end user elects to save their card data, a `recurring` token will be created instead. If the `token type` parameter is set to `recurring`, then the end-user must elect to save their payment data, or the transaction token will not be created. Note that you must have an `infinite` recurring token privilege in order to use this parameter. Required: No Allowed values: `Any UUID`
cvvAuthorize	boolean If `true`, an authorization will be automtically made to the gateway to submit the CVV value. If the authorization fails, the token will not be returned. Only valid when checkout is `token` & token type is `recurring`. Required: No (defaults to `false`) Allowed values: `true, false`
allowCardInstallments	boolean If `true`, an authorization will be automatically made to the gateway to submit the CVV value. If the authorization fails, the token will not be returned. Only valid when checkout is `token` & token type is `recurring`. Required: No (defaults to `false`) Allowed values: `true, false`
cardInstallmentOptions	string This parameter allows you to specify the number of installments to display on the form when allowCardInstallments is true. Required: no Allowed values:: 1, 3, 5, 6, 10, 12, 15, 18, 20, 24, revolving Inline forms: Yes
autoSubmit	boolean If `true`, then when the transaction is completed, the widget will automatically submit the form element that it is called from. Required: No (defaults to `false`) Allowed values: `true, false`
autoClose	boolean If `true`, then when the transaction is completed, the widget will automatically close. Required: No (defaults to `false`) Allowed values: `true, false`
usageLimit	string Sets the usage limit on the recurring transaction token that is created. Required: Only if creating a recurring transaction token with `bounded` recurring token privileges Allowed values: `daily, weekly, monthly, annually`
qrColor	string (HexColor) If `checkout` is set to `qr`, the QR code will be colored with this color code. Required: No Allowed values: `Hex color code`
qrLogoType	string If `checkout` is set to `qr`, a logo image of the store (or merchant if it isn’t set) will be embedded to the specified position in the QR code. Required: No (defaults to `None`) Allowed values: `Background, Centered, None`
metadata	json Sets metadata on the created transaction token. The format for specifying metadata is different depending on whether you are setting up the widget with HTML or with Javascript. When using HTML, you can specify any `data` attribute that is not already used by another parameter. For example, setting `data-foo = "bar"` would set the metadata key `foo` equal to the value `bar`. When using Javascript, you must specify a `metadata` parameter in the call to `UnivapayCheckout.create`, like so: `UnivapayCheckout.create({ ... metadata: { foo: "bar" } })` The univapay-reference-id key can also be set here for the CSV charges . Required: No Allowed values: `For HTML, any string. For Javascript, any flat Javascript object`

Callbacks

The widget will deliver to the window and in the parameter callbacks:

Opened (univapay:opened/opened): The event do not contain any other information. Triggered each time the checkout is opened.
Before closing (univapay:before-closing/beforeClosing): The event do not contain any other information. Triggered each time the checkout will closed. Return false in the JS beforeClosing to prevent the checkout from closing. The event will not be triggered when the JS callback is not a parameter and can not prevent closing the widget.
Closed (univapay:closed/closed): The event do not contain any other information. Triggered each time the checkout is closed.
Success (univapay:success/onSuccess): The event contains the ID of generated resources and the transaction details. Triggered on fully successful transaction only.
Error (univapay:error/onError): The event contains the ID of generated resources. Triggered when the transaction failed at any step.
Token created (univapay:token-created/onTokenCreated): The event contains the generated token details. Triggered when a token is generated, does not trigger when re-using a token.
Charge created (univapay:charge-created/onChargeCreated): The event contains the generated charge details. Triggered when a charge is created, successful or not.
Subscription created (univapay:subscription-created/onSubscriptionCreated): The event contains the generated subscription details. Triggered when a subscription is created, successful or not.
Validation error (univapay:validation-error/onValidationError): The event contains a collection of all the validation errors. The object is empty in case there are no error or in case the fields are not touched yet. The validation error callback is triggered every time the form errors change in the widget.

<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("Are you sure?") },
  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) } // deprecated
})

Metadata is stored as a flat JSON object, with arrays, strings, numbers or null being valid value types.

Errors

There are three types of errors that can occur when using the widget. The first is when invalid parameter values are provided — for example, setting amount to a negative number or to a string. This will result in an error message taking the place of the button (when setting up the widget with HTML). The second is when the widget parameters conflict with something in the checkout info — for example, setting token type to recurring when you do not have any recurring token privileges. This will result in an error message being rendered when the widget opens. The third is when the API returns an error in response to a request from the widget. This could have one of multiple causes — for example, trying to create a charge that is larger than the allowed maximum charge amount. These errors will be displayed on the widget’s results screen.