Omise.js API Reference

Complete reference for all Omise.js methods, parameters, and response objects.

Initialization

Omise.setPublicKey()

Set your Omise public key before making any API calls.

Signature:

Omise.setPublicKey(publicKey: string): void

Parameters:

Parameter	Type	Required	Description
`publicKey`	string	✓	Your Omise public key starting with `pkey_`

Example:

Omise.setPublicKey("pkey_test_5xs8t3mho5d4pbbkjz1dk");

Notes:

Must be called before any other Omise.js method
Use test keys (pkey_test_...) for development
Use live keys (pkey_live_...) for production
Key is stored in memory only, not persisted

Token Creation

Omise.createToken()

Create a tokenized representation of payment data.

Signature:

Omise.createToken(
    type: string,
    data: object,
    callback: (statusCode: number, response: object) => void
): void

Parameters:

Parameter	Type	Required	Description
`type`	string	✓	Token type: `"card"` or `"tokenization"`
`data`	object	✓	Card data or tokenization data
`callback`	function	✓	Callback function receiving (statusCode, response)

Card Token

Create a token from card information.

Card Data Object:

{
    name: string,              // Cardholder name
    number: string,            // Card number (13-19 digits)
    expiration_month: number,  // Month (1-12)
    expiration_year: number,   // Full year (e.g., 2027)
    security_code: string,     // CVV/CVC (3-4 digits)

    // Optional billing address
    city?: string,
    postal_code?: string,
    country?: string           // ISO 3166-1 alpha-2 (e.g., "TH")
}

Example:

Omise.createToken("card", {
    name: "John Doe",
    number: "4242424242424242",
    expiration_month: 12,
    expiration_year: 2027,
    security_code: "123",
    city: "Bangkok",
    postal_code: "10110",
    country: "TH"
}, function(statusCode, response) {
    if (statusCode === 200) {
        console.log("Token ID:", response.id);
        // response.id = "tokn_test_5xs8t3mho5d4pbbkjz1dk"
    } else {
        console.error("Error:", response.message);
    }
});

Digital Wallet Token

Create a token from digital wallet data (Google Pay, Apple Pay).

Tokenization Data Object:

{
    method: string,  // "googlepay" or "applepay"
    data: object     // Token data from payment provider
}

Google Pay Example:

const googlePayToken = {
    signature: "...",
    protocolVersion: "ECv2",
    signedMessage: "..."
};

Omise.createToken("tokenization", {
    method: "googlepay",
    data: googlePayToken
}, callback);

Apple Pay Example:

const applePayToken = {
    paymentData: {...},
    transactionIdentifier: "...",
    paymentMethod: {...}
};

Omise.createToken("tokenization", {
    method: "applepay",
    data: applePayToken
}, callback);

Token Response

Success Response (Status 200):

{
    object: "token",
    id: "tokn_test_5xs8t3mho5d4pbbkjz1dk",
    livemode: false,
    location: "/tokens/tokn_test_5xs8t3mho5d4pbbkjz1dk",
    used: false,
    charge_status: "unknown",
    card: {
        object: "card",
        id: "card_test_5xs8t3mho5d4pbbkjz1dk",
        livemode: false,
        location: null,
        country: "us",
        city: null,
        postal_code: null,
        financing: "",
        bank: "",
        last_digits: "4242",
        brand: "Visa",
        expiration_month: 12,
        expiration_year: 2027,
        fingerprint: "XjOdjaoKvKLxNFvbxdPo7hpO8VRQVOM5bZt9e1D4NG0=",
        name: "John Doe",
        security_code_check: true,
        tokenization_method: null,
        created_at: "2025-02-06T10:30:45Z"
    },
    created_at: "2025-02-06T10:30:45Z"
}

Error Response (Status 400+):

{
    object: "error",
    location: "https://docs.omise.co/api-errors#invalid-card",
    code: "invalid_card",
    message: "number is invalid"
}

Source Creation

Omise.createSource()

Create a payment source for alternative payment methods.

Signature:

Omise.createSource(
    type: string,
    data: object,
    callback: (statusCode: number, response: object) => void
): void

Parameters:

Parameter	Type	Required	Description
`type`	string	✓	Payment method type
`data`	object	✓	Source data including amount and currency
`callback`	function	✓	Callback function receiving (statusCode, response)

Supported Payment Methods

PromptPay

Omise.createSource("promptpay", {
    amount: 50000,      // Required
    currency: "THB"     // Required
}, callback);

PayNow (Singapore)

Omise.createSource("paynow", {
    amount: 5000,       // Required
    currency: "SGD"     // Required
}, callback);

TrueMoney Wallet

Omise.createSource("truemoney", {
    amount: 30000,              // Required
    currency: "THB",            // Required
    phone_number: "+66876543210" // Required
}, callback);

Rabbit LINE Pay

Omise.createSource("rabbit_linepay", {
    amount: 20000,      // Required
    currency: "THB"     // Required
}, callback);

Mobile Banking

// SCB Easy App
Omise.createSource("mobile_banking_scb", {
    amount: 40000,
    currency: "THB"
}, callback);

// KBank Mobile Banking
Omise.createSource("mobile_banking_kbank", {
    amount: 40000,
    currency: "THB"
}, callback);

// Bangkok Bank Mobile Banking
Omise.createSource("mobile_banking_bay", {
    amount: 40000,
    currency: "THB"
}, callback);

// Krung Thai Mobile Banking
Omise.createSource("mobile_banking_ktb", {
    amount: 40000,
    currency: "THB"
}, callback);

E-Wallets

// GrabPay
Omise.createSource("grabpay", {
    amount: 10000,
    currency: "SGD"  // or "THB", "MYR"
}, callback);

// ShopeePay
Omise.createSource("shopeepay", {
    amount: 25000,
    currency: "THB"
}, callback);

// Boost (Malaysia)
Omise.createSource("boost", {
    amount: 3000,
    currency: "MYR"
}, callback);

// Touch 'n Go (Malaysia)
Omise.createSource("touch_n_go", {
    amount: 5000,
    currency: "MYR"
}, callback);

// Alipay
Omise.createSource("alipay", {
    amount: 50000,
    currency: "THB"
}, callback);

// WeChat Pay
Omise.createSource("wechat_pay", {
    amount: 50000,
    currency: "THB"
}, callback);

Bank Transfers

// FPX (Malaysia)
Omise.createSource("fpx", {
    amount: 10000,
    currency: "MYR",
    email: "customer@example.com",  // Required
    bank: "test"                     // Bank code (see FPX docs)
}, callback);

// DuitNow QR (Malaysia)
Omise.createSource("duitnow_qr", {
    amount: 5000,
    currency: "MYR"
}, callback);

Installments

// Krungthai Card Installment
Omise.createSource("installment_kbank", {
    amount: 50000,
    currency: "THB",
    installment_term: 6  // 3, 6, 10 months
}, callback);

// Bay Installment
Omise.createSource("installment_bay", {
    amount: 50000,
    currency: "THB",
    installment_term: 10
}, callback);

// First Choice Installment
Omise.createSource("installment_first_choice", {
    amount: 30000,
    currency: "THB",
    installment_term: 6
}, callback);

// KTC Installment
Omise.createSource("installment_ktc", {
    amount: 50000,
    currency: "THB",
    installment_term: 6
}, callback);

// SCB Installment
Omise.createSource("installment_scb", {
    amount: 50000,
    currency: "THB",
    installment_term: 10
}, callback);

Buy Now Pay Later (BNPL)

// Atome
Omise.createSource("atome", {
    amount: 50000,
    currency: "THB",
    phone_number: "+66876543210",  // Required
    email: "customer@example.com",  // Required
    name: "John Doe",              // Required
    shipping: {                     // Required for physical goods
        address: {
            country: "TH",
            city: "Bangkok",
            postal_code: "10110",
            state: "Bangkok",
            street1: "123 Main St"
        }
    },
    items: [                       // Optional but recommended
        {
            sku: "PROD-001",
            name: "Product Name",
            quantity: 1,
            amount: 50000,
            currency: "THB"
        }
    ]
}, callback);

Source Response

Success Response (Status 200):

{
    object: "source",
    id: "src_test_5xs8t3mho5d4pbbkjz1dk",
    livemode: false,
    location: "/sources/src_test_5xs8t3mho5d4pbbkjz1dk",
    type: "promptpay",
    flow: "redirect",
    amount: 50000,
    currency: "THB",
    charge_status: "unknown",
    references: {
        qr_code: "00020101021..."  // For QR-based payments
    },
    created_at: "2025-02-06T10:30:45Z"
}

OmiseCard (Pre-Built Form)

OmiseCard.configure()

Configure the pre-built payment form.

Signature:

OmiseCard.configure(options: object): void

Options:

{
    // Required
    publicKey: string,
    amount: number,
    currency: string,

    // Payment methods
    defaultPaymentMethod?: string,
    otherPaymentMethods?: string[],

    // UI customization
    frameLabel?: string,
    frameDescription?: string,
    submitLabel?: string,
    buttonLabel?: string,
    locale?: string,  // "en", "th", "ja"
    image?: string,   // Logo URL

    // Customer data
    name?: string,
    email?: string,
    phoneNumber?: string,

    // Other
    location?: "yes" | "no",
    metadata?: object,

    // Callbacks
    onCreateTokenSuccess: (nonce: string) => void,
    onFormClosed?: () => void
}

Example:

OmiseCard.configure({
    publicKey: "pkey_test_5xs8t3mho5d4pbbkjz1dk",
    amount: 50000,
    currency: "THB",
    defaultPaymentMethod: "credit_card",
    otherPaymentMethods: ["promptpay", "truemoney"],
    frameLabel: "ACME Store",
    submitLabel: "Pay Now",
    locale: "en",
    onCreateTokenSuccess: (nonce) => {
        console.log("Created:", nonce);
    }
});

OmiseCard.open()

Open the payment form modal.

Signature:

OmiseCard.open(): void

Example:

document.getElementById('pay-button').addEventListener('click', () => {
    OmiseCard.open();
});

OmiseCard.close()

Close the payment form modal.

Signature:

OmiseCard.close(): void

Example:

OmiseCard.close();

Error Codes

Token Creation Errors

Code	Message	Solution
`invalid_card`	number is invalid	Check card number format
`invalid_card`	expiration date cannot be in the past	Use future date
`invalid_card`	security code failed verification	Check CVV
`empty_card`	name can't be blank	Provide cardholder name
`invalid_expiration_month`	expiration month is invalid	Use 1-12
`invalid_expiration_year`	expiration year is invalid	Use 4-digit year
`invalid_security_code`	security code is invalid	Provide 3-4 digit CVV
`invalid_number`	number is invalid	Check card number
`invalid_country`	country is invalid	Use ISO 3166-1 alpha-2
`public_key_is_required`	public key is required	Call setPublicKey first

Source Creation Errors

Code	Message	Solution
`invalid_amount`	amount is invalid	Amount must be positive integer
`invalid_currency`	currency is invalid	Use correct currency for method
`phone_number_required`	phone number is required	Provide phone number
`email_required`	email is required	Provide email address
`invalid_phone_number`	phone number is invalid	Use E.164 format (+66...)
`invalid_email`	email is invalid	Provide valid email

HTTP Status Codes

Status	Meaning	Action
`200`	Success	Process the response
`400`	Bad Request	Fix the request data
`401`	Unauthorized	Check public key
`402`	Payment Required	Contact Omise support
`404`	Not Found	Check endpoint URL
`429`	Too Many Requests	Implement rate limiting
`500`	Server Error	Retry or contact support
`503`	Service Unavailable	Retry later

Type Definitions

TypeScript

declare global {
    interface Window {
        Omise: {
            setPublicKey(publicKey: string): void;
            createToken(
                type: 'card',
                data: CardData,
                callback: TokenCallback
            ): void;
            createToken(
                type: 'tokenization',
                data: TokenizationData,
                callback: TokenCallback
            ): void;
            createSource(
                type: string,
                data: SourceData,
                callback: SourceCallback
            ): void;
        };
        OmiseCard: {
            configure(options: OmiseCardOptions): void;
            open(): void;
            close(): void;
        };
    }
}

interface CardData {
    name: string;
    number: string;
    expiration_month: number;
    expiration_year: number;
    security_code: string;
    city?: string;
    postal_code?: string;
    country?: string;
}

interface TokenizationData {
    method: 'googlepay' | 'applepay';
    data: any;
}

interface SourceData {
    amount: number;
    currency: string;
    [key: string]: any;
}

type TokenCallback = (statusCode: number, response: TokenResponse | ErrorResponse) => void;
type SourceCallback = (statusCode: number, response: SourceResponse | ErrorResponse) => void;

interface TokenResponse {
    object: 'token';
    id: string;
    livemode: boolean;
    used: boolean;
    card: CardObject;
    created_at: string;
}

interface SourceResponse {
    object: 'source';
    id: string;
    livemode: boolean;
    type: string;
    flow: string;
    amount: number;
    currency: string;
    created_at: string;
}

interface ErrorResponse {
    object: 'error';
    code: string;
    message: string;
}

interface OmiseCardOptions {
    publicKey: string;
    amount: number;
    currency: string;
    defaultPaymentMethod?: string;
    otherPaymentMethods?: string[];
    frameLabel?: string;
    frameDescription?: string;
    submitLabel?: string;
    buttonLabel?: string;
    locale?: 'en' | 'th' | 'ja';
    image?: string;
    name?: string;
    email?: string;
    phoneNumber?: string;
    location?: 'yes' | 'no';
    metadata?: Record<string, any>;
    onCreateTokenSuccess: (nonce: string) => void;
    onFormClosed?: () => void;
}

Browser Compatibility

Feature	Chrome	Firefox	Safari	Edge
createToken	60+	55+	11+	79+
createSource	60+	55+	11+	79+
OmiseCard	60+	55+	11+	79+

Mobile:

iOS Safari 11+
Chrome for Android 60+

FAQ

Why am I getting "Omise is not defined" error?

This usually means the Omise.js script hasn't loaded yet. Ensure you've included the script tag and wait for it to load before calling any Omise methods:

<script src="https://cdn.omise.co/omise.js"></script>
<script>
  // Wait for DOM ready
  document.addEventListener('DOMContentLoaded', function() {
    Omise.setPublicKey('pkey_test_...');
  });
</script>

How do I handle token creation errors?

Use the error callback in createToken:

Omise.createToken("card", cardData, function(statusCode, response) {
  if (response.object === "error") {
    console.error(response.code, response.message);
    // Handle specific error codes
  }
});

Can I use Omise.js with React/Vue/Angular?

Yes. Import the script dynamically or use the npm package. For React:

useEffect(() => {
  const script = document.createElement('script');
  script.src = 'https://cdn.omise.co/omise.js';
  script.onload = () => Omise.setPublicKey('pkey_test_...');
  document.body.appendChild(script);
}, []);

What's the difference between tokens and sources?

Tokens are for credit/debit card payments and are created client-side
Sources are for alternative payment methods (e-wallets, bank transfers, QR codes) and can be created client-side or server-side

How do I test without real cards?

Use test card numbers in test mode:

4242424242424242 - Successful payment
4111111111140011 - Insufficient funds

See the Testing Guide for more test cards.

Is Omise.js PCI DSS compliant?

Yes. Omise.js sends card data directly to Omise servers, so sensitive card information never touches your server, helping you maintain PCI DSS compliance.

Support

Documentation: https://docs.omise.co/omise-js
Support: support@omise.co
GitHub: https://github.com/omise/omise.js

Initialization​

Omise.setPublicKey()​

Token Creation​

Omise.createToken()​

Card Token​

Digital Wallet Token​

Token Response​

Source Creation​

Omise.createSource()​

Supported Payment Methods​

PromptPay​

PayNow (Singapore)​

TrueMoney Wallet​

Rabbit LINE Pay​

Mobile Banking​

E-Wallets​

Bank Transfers​

Installments​

Buy Now Pay Later (BNPL)​

Source Response​

OmiseCard (Pre-Built Form)​

OmiseCard.configure()​

OmiseCard.open()​

OmiseCard.close()​

Error Codes​

Token Creation Errors​

Source Creation Errors​

HTTP Status Codes​

Type Definitions​

TypeScript​

Browser Compatibility​

FAQ​

Why am I getting "Omise is not defined" error?​

How do I handle token creation errors?​

Can I use Omise.js with React/Vue/Angular?​

What's the difference between tokens and sources?​

How do I test without real cards?​

Is Omise.js PCI DSS compliant?​

Related Resources​

Support​

Initialization

Omise.setPublicKey()

Token Creation

Omise.createToken()

Card Token

Digital Wallet Token

Token Response

Source Creation

Omise.createSource()

Supported Payment Methods

PromptPay

PayNow (Singapore)

TrueMoney Wallet

Rabbit LINE Pay

Mobile Banking

E-Wallets

Bank Transfers

Installments

Buy Now Pay Later (BNPL)

Source Response

OmiseCard (Pre-Built Form)

OmiseCard.configure()

OmiseCard.open()

OmiseCard.close()

Error Codes

Token Creation Errors

Source Creation Errors

HTTP Status Codes

Type Definitions

TypeScript

Browser Compatibility

FAQ

Why am I getting "Omise is not defined" error?

How do I handle token creation errors?

Can I use Omise.js with React/Vue/Angular?

What's the difference between tokens and sources?

How do I test without real cards?

Is Omise.js PCI DSS compliant?

Related Resources

Support