Omise.js

Omise.js is a JavaScript library for collecting payment details in a user's browser and securely transmitting them to Omise 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 the available methods for adding it to your checkout page.

Requirements

• Enable HTTPS on your checkout page.

Recommended: Enable HTTPS across your entire site.
Do not collect or store 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 in a user's browser.

Omise.js sends these details to designated servers, which return a one-time-use value — a token or a source — that you can safely use on your server to create charges.

Examples

The following GitHub repositories contain working examples of Omise.js integrations:

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

Pre-Built Payment Form

You can use Omise.js to request tokens and sources directly, or use the pre-built payment form. The pre-built form securely collects, validates, and transmits user data to Omise servers. It also collects additional browser data to help protect against fraud.

How the Pre-Built Form Works

The integration follows this sequence:

1. The user (customer) accesses your checkout page.
2. The website loads Omise.js.
3. Omise.js creates an iframe for secure payment collection.
4. Omise.js loads pay.html in the iframe.
5. PayJS loads Omise.js in a secure environment.
6. PayJS loads itself and prepares the payment interface.
7. The payment methods or form is displayed to the user.
8. When the customer submits payment information, the payload is sent to PayJS.
9. PayJS validates the payload.
10. If validation fails, the system displays errors to the customer.
11. If validation succeeds:
    1. The payload is sent to Omise.js.
    2. Omise.js calls either the /token or the /source API.
    3. The Omise server returns the token or source object.
    4. Omise.js sends the API response to PayJS.
    5. If the API returns an error, the system displays an error message to the customer.
    6. If the API call is successful:
       1. PayJS sends the result to Omise.js.
       2. Omise.js sends the token, source, or both to the website.
       3. The website processes the data.
       4. The server initiates payment using the token or source.
       5. The server receives the payment result.
       6. The server updates the payment status.
       7. The website displays the result to the customer.

By default, Omise.js renders a Pay with Omise button. Clicking the button opens a payment form where the user enters their payment details. Clicking Pay [amount] requests a one-time-use token or source directly from Omise 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. Configure your payment form by adding the following HTML to your checkout page.

Usage

<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 must point to a location on your backend server that accepts a POST request containing the token or source.
• The <script> element must be placed inside the <form> element.
• data-key — your public key.
• data-amount — the amount to display on the form, expressed in the smallest unit for the given currency.
• data-default-payment-method — the default payment method shown on the form.
• 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 omiseToken and omiseSource parameters.

• If credit or debit card details were submitted, omiseToken is set to the generated token identifier and omiseSource is null.
• If details for another payment method were submitted, omiseSource is set to the generated source identifier and omiseToken is null.

See Processing Tokens and Sources.

Using JavaScript

You can also configure the payment form using JavaScript. Omise.js provides an OmiseCard object for this purpose.

Usage

<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"
  });

  const button = document.querySelector("#checkoutButton");
  const 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 must point to a location on your backend server that accepts 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 omiseToken and omiseSource parameters.

• If credit or debit card details were submitted, omiseToken is set to the generated token identifier and omiseSource is null.
• If details for another payment method were submitted, omiseSource is set to the generated source identifier and omiseToken is null.

See Processing Tokens and Sources.

OmiseCard Methods

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

configure

Sets the default configuration for the form. This is the recommended place to set your public key. Buttons configured via configureButton and forms opened via open inherit this configuration.

You must call configure before calling open.

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

configureButton

Sets button-specific configuration for the form. If the button is outside the form, include the submitFormTarget key in the configuration object 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

Attaches the configurations set via configureButton to their target buttons. After attaching, clicking a configured button triggers the payment form.

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

OmiseCard.attach();

open

Opens the payment form.

You must call configure before calling open.

OmiseCard.open({
  amount: 10000,
  submitFormTarget: '#checkout-form',
  onCreateTokenSuccess: (nonce) => {
    /* Handler for token or source creation. Use this to submit a form or send an Ajax request to the server. */
  },
  onFormClosed: () => {
    /* Handler for form closure. */
  },
});

Parameters

The following parameters are situational and apply only to specific payment methods.

Supported Payment Methods for Pre-Built Form

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

To enable additional payment methods on your live account, contact support@omise.co.

* Created source type will be econtext.

Requesting Tokens and Sources Directly

This approach offers the most flexibility and full support for all payment methods. However, you must build your own form and handle all events.

Do not use name attributes as identifiers for custom form <input> elements. When present, the value of these elements is submitted with the form to your server, which risks sending sensitive information such as card numbers.

Use data-* or id attributes as identifiers instead. See Merchant Security Best Practices.

How a Custom Form Works

The integration follows this sequence:

1. The user visits the website.
2. The website loads Omise.js.
3. The website displays a custom card form to the user.
4. The user enters their card details.
5. The website validates the payload.
6. If validation fails, the website displays errors to the user.
7. If validation passes:
   1. The user clicks the Pay button.
   2. The website sends the card details to Omise.js to create a token.
   3. Omise.js calls either the /token or the /source API.
   4. The Omise server returns the token or source object.
   5. Omise.js sends the API response back to the website.
   6. If the API returns an error, the website displays the error to the user.
   7. If the API call is successful, the website sends the response to the backend.

Usage

Add the following <script> element to load Omise.js:

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

Once loaded, the Omise object is available in your environment.

Omise Methods

Use the following methods on Omise to create a one-time-use token or source.

setPublicKey

Authenticates requests using your public key.

Omise.setPublicKey("OMISE_PUBLIC_KEY");

createToken

Creates a one-time-use token from the Omise server. Use the token to create a charge or attach a card to a customer object.

const 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) {
  if (statusCode === 200) {
    // response["id"] contains the token identifier
    console.log(response["id"]);
  } else {
    // Handle error — response["message"] contains the error description
    console.error(response["message"]);
  }
});

createSource

Creates a one-time-use source from the Omise server. Use the source to create a charge. See the Source API for available source types and required parameters.

const sourceParameters = {
  "amount": 12345,
  "currency": "THB",
  "phone_number": "0123456789"
};

Omise.createSource("truemoney_jumpapp", sourceParameters, function(statusCode, response) {
  if (statusCode === 200) {
    // response["id"] contains the source identifier
    console.log(response["id"]);
  } else {
    // Handle error — response["message"] contains the error description
    console.error(response["message"]);
  }
});

Processing Tokens and Sources

After Omise.js returns a token or source to your frontend, your server must use it to create a charge. Tokens and sources are one-time-use and expire if unused.

• For tokens, see Charging Cards. For full details and code examples, see the Charge API.
• For sources, see the relevant guide in the API documentation under Payment Methods.

Important: Never use a token or source more than once. Each value is invalidated after a single charge attempt, regardless of whether the charge succeeds.

Error Handling

When a callback receives a non-200 status code, the response object contains details about the failure.

Common error codes returned by Omise.js:

For the full list of error codes, see the API Errors reference.

CDN

Load Omise.js from the following URL:

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

Frequently Asked Questions

General

What is Omise.js and why do I need it?

Omise.js is a JavaScript library that handles secure collection and transmission of payment details from a user's browser directly to Omise servers. It is required for all web-based payment integrations. Because sensitive card data never touches your server, your PCI DSS compliance scope is significantly reduced.

Does Omise.js store card data on my server?

No. Omise.js sends payment details directly from the user's browser to Omise servers and returns only a token or source identifier to your server. Your server never receives or stores raw card data.

Which approach should I use — the pre-built form or a custom form?

Use the pre-built form if you want a fast, low-maintenance integration. Use a custom form if you need full control over the UI or need to support payment methods not available in the pre-built form.

Is Omise.js compatible with single-page applications (SPAs)?

Yes. Use the JavaScript (OmiseCard) method and call OmiseCard.configure() once on initialisation. Call OmiseCard.open() programmatically when the user is ready to pay. Avoid re-embedding the script tag on each route change.

Can I use Omise.js with a framework such as React, Vue, or Angular?

Yes. Load Omise.js via a <script> tag in your HTML (or dynamically on component mount) and interact with the OmiseCard or Omise global objects. Official framework wrappers are not currently provided, but both APIs work well with event-driven component architectures.

Security

Why must my checkout page use HTTPS?

HTTPS ensures that communication between the user's browser and your page is encrypted. Without it, attackers can intercept or modify the page before Omise.js loads, potentially replacing the secure form with a malicious one. Omise.js will not function on pages served over plain HTTP.

Why should I not use name attributes on custom form inputs?

When a form is submitted, any <input> element with a name attribute has its value included in the POST body sent to your server. For sensitive fields such as card numbers or CVV codes, this would route raw card data through your server — a serious security risk and a PCI DSS violation. Use id or data-* attributes to identify fields instead, so their values are only ever read by Omise.js in the browser.

What is the iframe used for in the pre-built form?

The pre-built form loads inside an iframe served from Omise's own domain. This means the payment form runs in a separate browsing context from your page. Your JavaScript cannot access the card details typed inside the iframe, which prevents accidental or malicious exposure of sensitive data.

Where can I find my public key?

Your public key is available on the Omise Dashboard under Settings → Keys. Use the test public key during development and the live public key in production. Never use your secret key in client-side code.

Tokens and Sources

What is the difference between a token and a source?

A token represents a credit or debit card and is created when a customer enters card details. A source represents a non-card payment method (for example, PromptPay, GrabPay, or an e-wallet) and contains redirect or QR information needed to complete the payment. Both are one-time-use identifiers that your server passes to the Charge API.

How long does a token or source remain valid?

Tokens are valid for a single use and expire after a short period if unused (typically a few minutes). Sources expire according to the rules of the underlying payment method. Always use a token or source promptly after receiving it and do not cache or reuse it.

What happens if both omiseToken and omiseSource are null in the POST to my server?

This indicates that the payment form was submitted without successfully creating a token or source — for example, if the user closed the form before completing payment. Your server should handle this case gracefully, such as by returning the user to the checkout page with an appropriate message.

Can I attach a card token to a customer for future charges?

Yes. Pass the token identifier to the Customers API to attach the card to a customer object. You can then charge that customer later without requiring them to re-enter their card details.

Payment Methods

How do I know which payment methods are available for my account?

Available payment methods depend on your account's registered country and the methods enabled by Omise. Log in to the Omise Dashboard to view your enabled payment methods. To request additional methods, contact support@omise.co.

Can I show multiple payment methods in the pre-built form?

Yes. Use the data-other-payment-methods attribute (or the otherPaymentMethods parameter in JavaScript) to pass a comma-separated list of additional payment method identifiers alongside the default. For example:

data-other-payment-methods="promptpay,truemoney_jumpapp,grabpay"

Does the pre-built form support Google Pay and Apple Pay?

Yes, with additional configuration required for live traffic:

• Google Pay — set data-googlepay-merchant-id to your Google Pay merchant ID.
• Apple Pay — set data-applepay-merchant-id and data-applepay-validation-url to your Apple Pay merchant ID and server validation endpoint respectively.

Both work without these parameters in test mode.

Troubleshooting

The payment form does not appear when the button is clicked.

Check the following:

• OmiseCard.configure() has been called with a valid publicKey before OmiseCard.open().
• The Omise.js script has fully loaded before any OmiseCard calls are made. Place your script logic after the <script src="https://cdn.omise.co/omise.js"> tag, or wait for the DOMContentLoaded event.
• Your page is served over HTTPS. Omise.js will not load on HTTP pages.
• No browser console errors are present. Open the browser developer tools and check the Console and Network tabs for blocked requests or JavaScript errors.

I am receiving an authentication_failure error.

This means the public key provided to Omise.js is missing, malformed, or does not match the expected environment (test vs live). Verify that:

• The key starts with pkey_ (public keys always use this prefix).
• You are using the correct key for your environment (test key for test mode, live key for production).
• No extra whitespace or characters have been introduced when copying the key.

The token or source is not being received by my server.

Confirm that:

• The action attribute on your <form> points to the correct server endpoint.
• For the data-attributes approach, the <script> tag is inside the <form> element.
• For the JavaScript approach, form.omiseToken.value or form.omiseSource.value is being set before form.submit() is called.
• Your server is reading the omiseToken and omiseSource POST parameters (not query parameters).

My custom form is accidentally submitting card data to my server.

This happens when card-related <input> elements have name attributes. Remove all name attributes from card input fields and use id or data-* attributes instead. See Requesting Tokens and Sources Directly for guidance.

How do I test the integration without processing real payments?

Use your test public key from the Omise Dashboard. In test mode, you can use Omise's test card numbers to simulate successful and failed payment scenarios without any real charges being made.