Widget: HTML

Setting up the widget

To set up the widget with HTML, 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 <span> element on the page that will contain the widget, with parameters set on the element as data attributes, of the form data-<parameter name>. For example,

<span data-app-id="<TOKEN>"
      data-checkout="payment"
      data-amount="1000"
      data-currency="jpy">
</span>

will set up a widget that will process a payment of 1000 JPY. When the page is opened in a browser, the <span> element will be replaced with a button that will open the widget when clicked.

Widget parameters

Parameters
data-app-idstring (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
Inline forms:Available
data-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, qr
Inline forms:Available(other than qr)
data-payment-typestring
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
Inline forms:Not available
data-payment-typesstring
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 ,bank_transfer separated by comas
Card brands -> Always allow all card brands when `card` payment method is providedvisa,mastercard,maestro,diners_club,discover,jcb,unionpay,american_express
Convinience stores -> Always allow all konbini brands when konbini payment method is providedseven_eleven,family_mart,lawson,mini_stop,seico_mart,pay_easy,circle_k,sunkus,daily_yamazaki,yamazaki_daily_store
Inline forms:Not available
data-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
Inline forms:Available
data-currencystring (currency code)
The currency for that charge(s) that will be made.
Required: Yes
Allowed values: currency code
Inline forms:Available
data-token-typestring
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
Inline forms:Available
data-product-codesstring
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, app-id 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
data-subscription-periodstring
The period that will be set on the created subscription.
Required: Only if the token type is subscription
Allowed values: daily, weekly, biweekly, monthly, bimonthly, quarterly, semiannually, annually,
Datetime string in ISO8601 format
Inline forms:Available
data-subscription-idstring
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
Inline forms:Available
data-installment-planstring
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
data-installment-qtynumber
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.
Inline forms:Available
data-installment-initial-amount*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 data-subscription-initial-amount.
data-subscription-plan
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
data-subscription-qtynumber
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
data-subscription-initial-amountnumber
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
Inline forms:Available
data-subscription-startstring
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
Inline forms:Available
data-subscription-start-instring
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
Inline forms:Available
data-subscription-start-day-of-monthnumber
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.
Inline forms:Available
data-subscription-retry-intervalstring
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
data-textstring
Sets the text on the button that is automatically created when setting up the widget with HTML.
Required: No
Allowed values:
Any string
Inline forms:Not available
data-sizestring
Sets the size of the button that is automatically created when setting up the widget with HTML.
Required: No (defaults to normal)
Allowed values:
small, normal, large
Inline forms:Not available
data-classstring
Sets the class of the button that is automatically created when setting up the widget with HTML. If this parameter is not set, the button will have no class.
Required: No
Allowed values:
Any string
Inline forms:Not available
data-stylestring
Sets the styles of the button that is automatically created when setting up the widget with HTML. If this parameter is not set, the button will have the default styles.
Required: No
Allowed values:
Any string
Inline forms:Not available
data-style-hoverstring
Sets the hover styles of the button that is automatically created when setting up the widget with HTML. If this parameter is not set, the button will have the default hover styles.
Required: No
Allowed values:
Any string
Inline forms:Not available
data-headerstring
Sets the text displayed in the header bar of the widget.
Required: No (defaults to “UnivaPay”)
Allowed values: Any string
Inline forms:Not available
data-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
Inline forms:Not available
data-descriptionstring
If set, the description text will be added in the widget sub-header
Required: No
Allowed values: Any string
Inline forms:Not available
data-submit-button-textstring
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
Inline forms:Not available
data-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
Inline forms:Not available
data-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
Inline forms:Available
data-capture-atstring
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 expiration-period and default transfer period settings.
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.
*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.
Required: No
Allowed values: Datetime string in ISO8601 format
Inline forms:Available
data-expiration-periodstring
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
Inline forms:Available
data-expiration-time-shiftstring
This parameter allows you to set the deposit deadline time.
This is valid for bank transfer/convenience store payments.
*If you use this parameter, data-expiration-period 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
Inline forms:Available
data-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
Inline forms:Available
data-shipping-address-line1string
If an address line 1 is set in this parameter, it will be pre-filled into the address line 1 field in the widget’s form.
Required: No
Allowed values: Any string
Inline forms:Not available
data-shipping-address-line2string
If an address line 2 is set in this parameter, it will be pre-filled into the address line 2 field in the widget’s form.
Required: No
Allowed values: Any string
Inline forms:Not available
data-shipping-address-citystring
If an city is set in this parameter, it will be pre-filled into the city field in the widget’s form.
Required: No
Allowed values: Any string
Inline forms:Not available
data-shipping-address-statestring
If an state is set in this parameter, it will be pre-filled into the state field in the widget’s form.
Required: No
Allowed values: Any string
Inline forms:Not available
data-shipping-address-zipstring
If an zip code is set in this parameter, it will be pre-filled into the Postcode field in the widget’s form.
Required: No
Allowed values: Any string
Inline forms:Not available
data-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
Inline forms:Not available
data-require-nameboolean
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
Inline forms:Not available
data-require-emailboolean
If set to true, the end-user will be prompted to enter their email address.

Required: No (defaults to false)
Allowed values: true, false
Inline forms:Available
data-require-phone-numberboolean
If set to true, the end-user will be prompted to enter their phone number.

Required: No (defaults to false)
Allowed values: true, false
Inline forms:Available
data-require-billing-addressboolean
If set to true, the end-user will be prompted to enter their billing address.

Required: No (defaults to false)
Allowed values: true, false
Inline forms:Not available
data-show-cvvboolean
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
Inline forms:Available
data-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, zh-cn, en, ja, zh
Inline forms:Available
data-univapay-customer-idstring (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
Inline forms:Available
data-cvv-authorizeboolean
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
Inline forms:Available
data-allow-card-installmentsboolean
If true, card one_time or recurring charge will show an installment select for the user to split the payment into several charges using the card company installments.

Only valid when checkout is payment and when token type is "recurring” or “one_time”. Also, the store must only use card processor for this setting to work.

Required: No (defaults to false)
Allowed values: true, false
Inline forms:Available
data-card-installment-optionsstring
This parameter allows you to specify the number of installments to display on the form when data-allow-card-installments is true.
Required: no
Allowed values:: 1, 3, 5, 6, 10, 12, 15, 18, 20, 24, revolving
Inline forms: Yes
data-auto-submitboolean
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
Inline forms:Not available
data-auto-closeboolean
If true, then when the transaction is completed, the widget will automatically close.
Required: No (defaults to false)
Allowed values: true, false
Inline forms:Not available
data-remove-checkout-button-after-chargeboolean
If false, then when the transaction is completed, the widget button will remain visible.
Required: No (defaults to true)
Allowed values: true, false
Inline forms:Not available
data-usage-limitstring
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
Inline forms:Available
data-qr-colorstring (HexColor)
If checkout is set to qr, the QR code will be colored with this color code.
Required: No
Allowed values: Hex color code
Inline forms:Not available
data-qr-logo-typestring
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
Inline forms:Not available
data-custom-field-<>string boolean
This parameter can be used to customize user input fields or options. Use the following parameters to specify each field
data-custom-field-labels :allows you to specify the titles of the input fields/options that will be displayed in the widget.
data-custom-field-types :select or string to specify whether the custom field is a choice or an input field.
data-custom-field-required :true or false to specify if the custom field is required.
data-custom-field-options :If the custom field is a choice, specify the choices separated by “;”, specify the contents of the next choice, separated by “,”.
data-custom-field-keys :Specify metadata keys. The title corresponds to each in the order specified.
Required: No
Inline forms:Not available
data-<key>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" } })

data-univapay-reference-id can also be set here for the CSV charges .

Required: No
Allowed values: For HTML, any string. For Javascript, any flat Javascript object
Inline forms:Available

Callbacks

The widget will deliver to the window:

  • Opened (univapay:opened): The event do not contain any other information. Triggered each time the checkout is opened.
  • Closed (univapay:closed): The event do not contain any other information. Triggered each time the checkout is closed.
  • Success (univapay:success): The event contains the ID of generated resources and the transaction details. Triggered on fully successful transaction only.
  • Error (univapay:error): The event contains the ID of generated resources. Triggered when the transaction failed at any step.
  • Token created (univapay:token-created): 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): The event contains the generated charge details. Triggered when a charge is created, successful or not.
  • Subscription created (univapay:subscription-created): The event contains the generated subscription details. Triggered when a subscription is created, successful or not.
  • Validation error (univapay:validation-error): 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:success", (e) => { console.info("Success 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>