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+

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​

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

Related Resources

Support