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

• Enable HTTPS on your checkout page.

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. You can safely use this value on your server to create charges.

Examples

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

• omise.js-example
• omise-flask-example

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.

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

Using Data Attributes

When 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 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 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 the form. This is a good place to set your public key. Buttons configured via the configureButton method will inherit this configuration. The form opened using the open method will also inherit this configuration.

You must call this method before calling the open method.

OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY',
});

configureButton

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

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 you have configured using configureButton. After attaching the configuration 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.

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

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

Supported Payment Methods for Pre-Built Form

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

* 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.

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.

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.

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.

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 location:

• https://cdn.omise.co/omise.js