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
appIdstring (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
checkoutstring
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
paymentTypestring
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
paymentTypesstring
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 separated by comas
amountnumber
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
currencystring (currency code)
The currency for that charge(s) that will be made.
Required: Yes
Allowed values: currency code
tokenTypestring
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
subscriptionPeriodstring
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
subscriptionIdstring
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
installmentPlanstring
Setting this parameter will cause the created subscription to use installments, either with a fixed number of cycles (fixed_cycles), or a fixed amount per cycle (fixed_cycle_amount).
Required: No
Allowed values: fixed_cycles, fixed_cycle_amount
installmentQtynumber
If installment plan is set to fixed_cycles, represents the number of cycles. If installment plan is set to fixed_cycle_amount, represents the amount to charge per cycle.
Required: Only if installment plan is set
Allowed values: Positive integers
installmentInitialAmountnumber
If the subscription to be created is using an installment plan, this parameter represents the amount to be charged for the first cycle.
Required: No
Allowed values: Positive integers
subscriptionInitialAmountnumber
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
subscriptionStartstring
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
headerstring
Sets the text displayed in the header bar of the widget.
Required: No (defaults to “UnivaPay”)
Allowed values: Any string
titlestring
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
namestring
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
captureboolean
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
captureAtstring
If capture is set to false and this parameter is set, the authorized charge will be automatically captured at the specified time.
Required: No
Allowed values: Datetime string in ISO8601 format
emailstring
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
addressboolean
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
requireEmailboolean
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
requirePhoneNumberboolean
If set to true, the end-user will be prompted to enter their phone number.

Required: No (defaults to false)
Allowed values: true, false
requireBillingAddressboolean
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
showCvvboolean
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
localestring
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, en, ja, zh
univapayCustomerIdstring (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
cvvAuthorizeboolean
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
allowCardInstallmentsboolean
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
autoSubmitboolean
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
autoCloseboolean
If true, then when the transaction is completed, the widget will automatically close.
Required: No (defaults to false)
Allowed values: true, false
usageLimitstring
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
qrColorstring (HexColor)
If checkout is set to qr, the QR code will be colored with this color code.
Required: No
Allowed values: Hex color code
qrLogoTypestring
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
metadatajson
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

There are several ways to set up callback functions that trigger in response to certain actions in the widget. One method is to add event listeners for three custom events that the widget will deliver to the window upon the widget being opened, closed, or the payment process being completed successfully. The event names for the widget opening and closing are univapay:opened and univapay:closed respectively. These events do not contain any other information. The event name for the payment process being completed successfully is univapay:success. This event will also contain an object named detail that contains information about the resource that was created. detail.resourceType will be one of charge, subscription, or transactionToken and signifies the type of resource that was created. detail.response contains the JSON response from the API that resulted from the request to create the resource.

Another way to set up callback functions for the same events is only available when setting up the widget using Javascript. In this case, you can simply provide parameters to the call to UnivapayCheckout.create, like so:

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
})

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.