Omise.js

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 own 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 highly recommended 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 which 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.

The source code for Omise.js is available on GitHub: https://github.com/omise/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.

Credit Card form example

By default, Omise.js will render a Pay with Omise button. Click the button below 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.

The form can be configured using either HTML data attributes or JavaScript.

Using Data Attributes

Using data attributes, no custom JavaScript is required. You can configure 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 which 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 parameters for additional supported parameters.

Next Steps

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.

See Processing Tokens and Sources.

Using JavaScript

You can also configure the behavior of 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 which will accept a POST request containing the token or source.
  • See parameters for additional supported parameters.

Next Steps

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.

See Processing Tokens and Sources.

OmiseCard Methods

You can use the following methods on OmiseCard to customize the appearance and behavior of your form.

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 on 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. */
  },
})

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 Omise
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-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: Checkout.
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

Supported Payment Methods for Pre-Built Form

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
bill_payment_tesco_lotus Bill Payment Tesco Lotus Thailand
convenience_store*, net_banking*, pay_easy* Convenience Store, Pay Easy, Online Banking Japan
credit_card Credit Card Thailand, Singapore, Japan
installment Installments Thailand
internet_banking†, internet_banking_bay, internet_banking_bbl, internet_banking_ktb, internet_banking_scb Internet Banking Thailand

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

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

Requesting Tokens and Sources Directly

This approach provides the most flexibility and full support for all payment methods. However, you must create your own form 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

Usage

Create a <script> element loading Omise.js.

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

Once loaded, the Omise object should be loaded into your environment.

Omise Methods

You can use the following methods on Omise 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 Omise server that you can 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 Omise 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)
});

Processing 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 locations:

  • https://cdn.omise.co/omise.js (Singapore)
  • https://cdn2.omise.co/omise.js (Japan).