Omise.js

Topics covered on this page

Omise.js is our JavaScript library for collecting payment details on a user's browser and securely transmitting them to our servers. You are required to use Omise.js when accepting payment details on your website.

This document provides an overview of how Omise.js works and guides you through several methods of adding it to your checkout page.

Requirements

It is mandatory that you also enable HTTPS on your entire site. Do not collect or store any card details on your server. See Security Best Practices for Merchants for more information.

How It Works

Omise.js provides a secure method of collecting credit card, debit card, and other payment method details on a user's browser.

Omise.js sends these details to designated servers that return a one-time-use value: a token or a source. This value can be safely used on your server to create charges.

Image

Examples

The following GitHub repositories contain examples of using Omise.js.

Pre-built Payment Form

You can use Omise.js to request tokens and sources directly, or you can use our pre-built payment form. This form securely handles collecting, validating, and sending user data to our servers. It also collects additional data from the user's browser to help protect against fraud.

By default, Omise.js will render a Pay with Opn Payments button. Click the following button to see an example. You should see a payment form pop up.


On the payment form, the user enters their payment details. Clicking the Pay 123.45 THB button requests a one-time use token or source directly from our servers.

You can integrate the form with your checkout page using either HTML data attributes or JavaScript.

Integrate Using HTML Data Attributes

This method is deprecated. Use Javascript for greater customization of your payment form.

Using data attributes, no custom JavaScript is required. You can integrate your payment form with a simple addition of HTML to your checkout page.

Usage

On your checkout page, add the following:

<form id="checkoutForm" method="POST" action="/charge">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="OMISE_PUBLIC_KEY"
          data-amount="12345"
          data-currency="THB"
          data-default-payment-method="credit_card">
  </script>
</form>

Notes:

  • The action path is a location on your backend server that will accept a POST request containing the token or source.
  • The <script> element must be placed within the <form> element.
  • The data-key attribute specifies your public key.
  • The data-amount attribute specifies the amount you want displayed on the form in the smallest unit for a given currency.
  • The data-default-payment-method attribute specifies the default payment method.
  • See Form Parameters in Customize the Form for additional supported parameters.

See Configure Charge Path to configure the charge path.

Integrate Using JavaScript

Alternatively, you can integrate the payment form using JavaScript. Omise.js provides an OmiseCard object for this purpose.

Usage

On your checkout page, add the following:

<form id="checkoutForm" method="POST" action="/charge">
  <input type="hidden" name="omiseToken">
  <input type="hidden" name="omiseSource">
  <button type="submit" id="checkoutButton">Checkout</button>
</form>

<script type="text/javascript" src="https://cdn.omise.co/omise.js">
</script>

<script>
  OmiseCard.configure({
    publicKey: "OMISE_PUBLIC_KEY"
  });

  var button = document.querySelector("#checkoutButton");
  var form = document.querySelector("#checkoutForm");

  button.addEventListener("click", (event) => {
    event.preventDefault();
    OmiseCard.open({
      amount: 12345,
      currency: "THB",
      defaultPaymentMethod: "credit_card",
      onCreateTokenSuccess: (nonce) => {
          if (nonce.startsWith("tokn_")) {
              form.omiseToken.value = nonce;
          } else {
              form.omiseSource.value = nonce;
          };
        form.submit();
      }
    });
  });
</script>

Notes:

  • The action path is a location on your backend server that will accept a POST request containing the token or source.
  • See Form Parameters in Customize the Form for additional supported parameters.

See Configure Charge Path to configure the charge path.

Configure Charge Path

Configure the /charge path on your server (or wherever action points to) to accept and process the parameters omiseToken and omiseSource.

If details for a credit or debit card were submitted, the omiseToken parameter will be set to the generated token identifier and omiseSource will be null.

If details for another payment method were submitted, the omiseSource parameter will be set to the generated source identifier and omiseToken will be null.

You can now Process Tokens and Sources.

Customize the Form

Use the following methods and parameters to customize the appearance and behavior of your form.

OmiseCard Methods

configure

Set default configuration for form. This is a good place to set your public key. Buttons configured via the configureButton method will inherit this configuration. The form opened via the open method will also inherit this configuration.

You must call this method before calling the open method.

Parameter Type Default Description
config object {} Default configuration for button(s).
OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY',
});
configureButton

Set button-specific configuration for form. If button is located outside of form, include the configuration object key submitFormTarget to point to your form.

Parameter Type Default Description
selector string - Selector for button.
config object {} Configuration for button.
OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY'
});

OmiseCard.configureButton('#checkout-button', {
  amount: 3000,
  currency: 'USD',
  buttonLabel: 'Pay 30 USD'
});

OmiseCard.configureButton('#checkout-button-alt', {
  amount: 100000,
  currency: 'THB',
  buttonLabel: 'Pay 1000 THB'
});
attach

Attach set configurations to buttons that have been configured using configureButton. Once the configuration has been attached to all target buttons, clicking the button should trigger the form.

OmiseCard.configureButton('#checkout-button', {
  publicKey: 'OMISE_PUBLIC_KEY',
  amount: 10000,
  frameLabel: 'Merchant Name',
  submitLabel: 'Pay',
});

OmiseCard.attach();
open

Open the payment form.

You must call the configure method before calling this method.

Parameter Type Default Description
config object {} Configuration for target button.
OmiseCard.open({
  amount: 10000,
  submitFormTarget: '#checkout-form',
  onCreateTokenSuccess: (nonce) => {
    /* Handler on token or source creation.  Use this to submit form or send ajax request to server */
  },
  onFormClosed: () => {
    /* Handler on form closure. */
  },
})

Form Parameters

Use the following parameters to customize the payment form.

Data Parameters
Data Attribute Parameter Description
data-amount amount (required) Amount shown on form
data-key publicKey (required) Your public key found on your dashboard
data-button-label buttonLabel Label to be displayed in the button embedded in your form. Default: Pay with Opn Payments
data-currency currency Currency to be displayed in the payment window. Default: THB
data-default-payment-method defaultPaymentMethod Default payment method. Default: credit_card.
data-frame-description frameDescription Description text displayed below header text
data-frame-label frameLabel Header text you want displayed in the popup window. Default: Omise
data-hide-amount hideAmount Whether to hide the amount on the submit button. Default: false
data-image image URI to your logo image. eg. https://example.com/logo.png
data-locale locale Language of form (en, ja, th). Default: en
data-location location Whether to include postal_code and city fields. Default: no
data-other-payment-methods otherPaymentMethods A comma-separated string of alternative payment method identifiers
data-submit-label submitLabel Label to be displayed in the submit button in pop-up window. Default: Pay.
data-submit-form-target submitFormTarget Selector for payment form. Default: form selector for button parent element
- onCreateTokenSuccess Callback for token or source creation event. One parameter is provided to the callback: the token or source identifier
- onFormClosed Callback for form closure event. No parameters are provided to the callback
Situational Parameters

The following parameters are situational and only used by some payment methods.

Google Pay Parameters
Data Attribute Parameter Description
data-googlepay-merchant-id googlepayMerchantId For googlepay. Merchant ID for Google Pay (required when accepting live traffic).
data-googlepay-request-billing-address googlepayRequestBillingAddress For googlepay. Set to true to attach the cardholder's name and billing address to a card token. Supplying this improves your authorization rate for US, UK, and Candian cardholders.
data-googlepay-request-phone-number googlepayRequestPhoneNumber For googlepay. When the cardholder's billing address is requested, set to true to also attach the cardholder’s phone number to a card token.
Atome Parameters

The following parameters are used only by Atome for shipments.

Parameter Description
shipping.street1 Address
shipping.postal_code Postal Code
shipping.country Country
item.sku Item code
item.name Item name
item.amount Total cost to be charged
item.quantity Quantity of that item purchased
User Interface Parameters

The following parameters allow you to customize the user interface of the form.

Parameter Description Default Value
style.defaultSelectPaymentMethods Set to true to display the default payment methods instead of having to enter card details. false
style.alwaysFullScreen Set to true to display the form full screen. false
style.body.width Width of the form (in pixels). For example, 200 px. container.body (400px)
style.body.padding The amount of space (in pixels) around the form within defined borders. container.padding.desktop (48px) and container.padding.mobile (16px) for desktop and mobile screens rescpectively.
style.CloseButton.visible Set to true to display the close button. true
style.submitButton.backgroundColour The background colour of the Payment button. For example, red or #ff7600. color.omise (#1A56F0)
style.submitButton.textColour The colour of the text on the Payment button. color.white (#FFFFFF)
style.link.textColour The colour of the hyperlinks on the form. color.omise (#1A56F0)
stle.logo.width Width (in pixels) of the header logo. header.logo.width (40px)
style.logo.height Height (in pixels) of the header logo. header.logo.height (40px)
style.list.border The style and color of the border for a list of items. For example: 1px solid #D0D6E2 list.border (1px solid #D0D6E2)
style.listItem.fontSize The font size (in pixels) for each entity on a list. listItem.fontSize (14px)
style.listItemContent.minHeight The minimum height (in pixels) for each entity on a list. listItemContent.minHeight (60px)

Supported Payment Methods

While all payment methods are supported by Omise.js, only the following are supported by the pre-built form. Supported payment methods depend on your account settings and the country where your account is registered.

Alternative payment methods form example

Payment Method Documentation Supported Countries
alipay Alipay Thailand
alipay_cn Alipay CN Thailand, Singapore
alipay_hk Alipay HK Singapore
bill_payment_tesco_lotus Bill Payment Thailand
boost Boost Malaysia
convenience_store*, net_banking*, pay_easy* Convenience Store, Pay Easy, Online Banking Japan
credit_card Credit Card Thailand, Singapore, Japan
dana DANA Singapore
duitnow_obw DuitNow Online Banking/Wallets Malaysia
duitnow_qr DuitNow QR Malaysia
fpx FPX Malaysia
gcash GCash Singapore
googlepay Google Pay Thailand, Singapore
grabpay GrabPay Thailand, Singapore, Malaysia
installment Installments Thailand
internet_banking†, internet_banking_bay, internet_banking_bbl Internet Banking Thailand
kakaopay KakaoPay Singapore
maybank_qr Maybank QR Malaysia
mobile_banking_bay Krungsri (KMA) Thailand
mobile_banking_bbl Bangkok Bank (Bualuang mBanking) Thailand
mobile_banking_kbank KBank (K PLUS) Thailand
mobile_banking_ktb Krung Thai (KTB NEXT) Thailand
mobile_banking_ocbc_pao OCBC Pay Anyone Singapore
mobile_banking_scb SCB (SCB Easy) Thailand
paynow PayNow Singapore
points_citi Pay With Points Thailand
promptpay PromptPay Thailand
rabbit_linepay Rabbit Line Pay Thailand
shopeepay ShopeePay Thailand
touch_n_go Touch 'n Go Singapore
truemoney TrueMoney Wallet Thailand

* Created source type will be econtext.
All internet banking sources will be presented for the user to choose.

Contact support@opn.ooo if you would like to enable additional payment methods on your live account.

Create Your Own Form

This approach provides the most flexibility and full support for all payment methods. However, you must request tokens and sources directly, and handle all events.

Do not use name attributes as identifiers for your custom form <input> elements. When provided, the value of these elements is submitted with the form to your server.

Instead, use a data or id attribute as an identifier. This prevents sensitive information (like credit card numbers) from being sent to your server. See Merchant Security Best Practices

To create your own form:

  1. Load Omise.js

  2. Use the Omise Methods to create a one-time use token or source

Load Omise.js

Create a <script> element to load Omise.js into your environment.

<script type="text/javascript" src="https://cdn.omise.co/omise.js"></script>

Create One-time Use Token or Source

You can use the following methods on Opn Payments to create a one-time-use token or source.

setPublicKey

Use your public key to authenticate.

Parameter Type Description
key string (required) Public key found on your dashboard
Omise.setPublicKey("OMISE_PUBLIC_KEY");

createToken

Create the one-time-use token object from the Opn Payments server, which you can then use to create a charge or attach to a customer object as a card.

Parameter Type Description
type string (required) card
tokenParameters object (required) Request parameters for token
callback function (required) A function that will be called when the request with Omise server is completed. Two parameters are provided to the callback: the HTTP status code of the response and the response itself
tokenParameters = {
  "city": "New York",
  "country": "US",
  "expiration_month": 2,
  "expiration_year": 2022,
  "name": "Somchai Prasert",
  "number": "4242424242424242",
  "phone_number": "0123456789",
  "postal_code": 10320,
  "security_code": 123,
  "state": "NY",
  "street1": "476 Fifth Avenue"
};

Omise.createToken("card",
                  tokenParameters,
                  function(statusCode, response) {

  // response["id"] is token identifier

  console.log(response)
});

createSource

Create the one-time-use source object from the Opn Payments server that you can use to create a charge. See Source API for available source types and required parameters.

Parameter Type Description
type string (required) Source type
sourceParameters object (required) Request parameters for source
callback function (required) A function that will be called when the request with Omise server is completed. Two parameters are provided to the callback: the HTTP status code of the response and the response itself
sourceParameters = {
  "amount": 12345,
  "currency": "THB",
  "phone_number": "0123456789"
}

Omise.createSource("truemoney",
                   sourceParameters,
                   function(statusCode, response) {

  // response["id"] is source identifer

  console.log(response)
});

Process Tokens and Sources

For tokens, see our guide to charging cards. For more detail and code examples, see the charge API.

For sources, see the relevant guide in our API documentation under the category Payment Methods.

CDNs

You can load Omise.js from the following location:

  • https://cdn.omise.co/omise.js
Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more