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

Examples

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

• https://github.com/omise/omise.js-example
• https://github.com/omise/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.

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

Integrate Using HTML Data Attributes

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.

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.

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.

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

Situational Parameters

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

Google Pay Parameters

Atome Parameters

The following parameters are used only by Atome for shipments.

User Interface Parameters

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

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.

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

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.

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.

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