Installing Omise.js

Learn how to add Omise.js to your web application and configure it for secure payment tokenization.

Installation Methods

Omise.js can be installed in two ways:

1. CDN (Recommended)

The simplest way to get started. Add this script tag to your HTML:

<!DOCTYPE html>
<html>
<head>
    <title>My Store</title>
</head>
<body>
    <!-- Your page content -->

    <!-- Add Omise.js before closing body tag -->
    <script src="https://cdn.omise.co/omise.js"></script>
    <script>
        // Initialize Omise.js
        Omise.setPublicKey("pkey_test_YOUR_PUBLIC_KEY");
    </script>
</body>
</html>

Benefits:

✅ No build step required
✅ Always up-to-date
✅ Cached by browsers
✅ Works with any framework

CDN URLs:

Production: https://cdn.omise.co/omise.js
Specific version: https://cdn.omise.co/omise.js@4.0.0
Beta: https://cdn.omise.co/omise-next.js

Versioning

We recommend using the version-less URL to automatically receive updates. If you need a specific version for compatibility, pin to a version number.

2. NPM Package

For modern build tools and bundlers:

# Install via npm
npm install omise-js

# Or via yarn
yarn add omise-js

# Or via pnpm
pnpm add omise-js

Then import in your JavaScript:

import Omise from 'omise-js';

// Initialize
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');

Configuration

Basic Setup

// Set your public key
Omise.setPublicKey("pkey_test_YOUR_PUBLIC_KEY");

// Verify configuration
console.log('Omise.js loaded:', typeof Omise !== 'undefined');

Framework-Specific Setup

React

// src/App.jsx
import { useEffect } from 'react';

function App() {
    useEffect(() => {
        // Load Omise.js from CDN
        const script = document.createElement('script');
        script.src = 'https://cdn.omise.co/omise.js';
        script.async = true;
        script.onload = () => {
            window.Omise.setPublicKey(process.env.REACT_APP_OMISE_PUBLIC_KEY);
        };
        document.body.appendChild(script);

        return () => {
            document.body.removeChild(script);
        };
    }, []);

    return <div>Your app</div>;
}

Or use the npm package:

import Omise from 'omise-js';
import { useEffect } from 'react';

function PaymentForm() {
    useEffect(() => {
        Omise.setPublicKey(process.env.REACT_APP_OMISE_PUBLIC_KEY);
    }, []);

    const handleSubmit = async (e) => {
        e.preventDefault();

        window.Omise.createToken('card', {
            name: cardName,
            number: cardNumber,
            expiration_month: parseInt(expiryMonth),
            expiration_year: parseInt(expiryYear),
            security_code: cvv
        }, (statusCode, response) => {
            if (statusCode === 200) {
                console.log('Token:', response.id);
            }
        });
    };

    return <form onSubmit={handleSubmit}>{/* form fields */}</form>;
}

Vue.js

// main.js
import { createApp } from 'vue';
import App from './App.vue';

// Load Omise.js
const script = document.createElement('script');
script.src = 'https://cdn.omise.co/omise.js';
script.onload = () => {
    window.Omise.setPublicKey(import.meta.env.VITE_OMISE_PUBLIC_KEY);
};
document.head.appendChild(script);

createApp(App).mount('#app');

<!-- PaymentForm.vue -->
<template>
    <form @submit.prevent="handleSubmit">
        <!-- form fields -->
    </form>
</template>

<script setup>
const handleSubmit = () => {
    window.Omise.createToken('card', cardData, (statusCode, response) => {
        if (statusCode === 200) {
            console.log('Token:', response.id);
        }
    });
};
</script>

Angular

// app.component.ts
import { Component, OnInit } from '@angular/core';

declare global {
    interface Window {
        Omise: any;
    }
}

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html'
})
export class AppComponent implements OnInit {
    ngOnInit() {
        this.loadOmiseScript();
    }

    loadOmiseScript() {
        const script = document.createElement('script');
        script.src = 'https://cdn.omise.co/omise.js';
        script.onload = () => {
            window.Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
        };
        document.body.appendChild(script);
    }

    handlePayment(cardData: any) {
        window.Omise.createToken('card', cardData, (statusCode: number, response: any) => {
            if (statusCode === 200) {
                console.log('Token:', response.id);
            }
        });
    }
}

Next.js

// pages/_app.js
import { useEffect } from 'react';
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
    return (
        <>
            <Script
                src="https://cdn.omise.co/omise.js"
                onLoad={() => {
                    window.Omise.setPublicKey(process.env.NEXT_PUBLIC_OMISE_PUBLIC_KEY);
                }}
            />
            <Component {...pageProps} />
        </>
    );
}

export default MyApp;

Environment Variables

Store your API keys securely using environment variables:

.env File

# .env.local (for Next.js)
NEXT_PUBLIC_OMISE_PUBLIC_KEY=pkey_test_YOUR_KEY

# .env (for React/Vite)
REACT_APP_OMISE_PUBLIC_KEY=pkey_test_YOUR_KEY
VITE_OMISE_PUBLIC_KEY=pkey_test_YOUR_KEY

# .env (for Node.js backend)
OMISE_SECRET_KEY=skey_test_YOUR_SECRET_KEY

Secret Keys

NEVER expose your secret key in client-side code! Only use public keys in the browser.

Accessing in Code

// React
const publicKey = process.env.REACT_APP_OMISE_PUBLIC_KEY;

// Vite
const publicKey = import.meta.env.VITE_OMISE_PUBLIC_KEY;

// Next.js
const publicKey = process.env.NEXT_PUBLIC_OMISE_PUBLIC_KEY;

// Initialize Omise.js
Omise.setPublicKey(publicKey);

Verification

Test that Omise.js is properly installed:

// Check if Omise.js is loaded
if (typeof Omise !== 'undefined') {
    console.log('✓ Omise.js loaded successfully');
} else {
    console.error('✗ Omise.js failed to load');
}

// Check if key is set
Omise.setPublicKey('pkey_test_YOUR_KEY');

// Verify with a test token creation
Omise.createToken('card', {
    name: 'Test User',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2027,
    security_code: '123'
}, function(statusCode, response) {
    if (statusCode === 200) {
        console.log('✓ Token created:', response.id);
    } else {
        console.error('✗ Token creation failed:', response.message);
    }
});

Requirements

Browser Support

Omise.js works in all modern browsers:

✅ Chrome 60+
✅ Firefox 55+
✅ Safari 11+
✅ Edge 79+
✅ Opera 47+
✅ iOS Safari 11+
✅ Chrome for Android

HTTPS Required

Omise.js only works on HTTPS pages (except localhost for development).

<!-- ✅ GOOD -->
https://yourdomain.com
https://staging.yourdomain.com
http://localhost:3000 (development only)

<!-- ❌ BAD -->
http://yourdomain.com (will not work)

Content Security Policy

If you use CSP headers, whitelist Omise domains:

<meta http-equiv="Content-Security-Policy"
      content="
        script-src 'self' https://cdn.omise.co;
        connect-src 'self' https://api.omise.co https://vault.omise.co;
        frame-src https://api.omise.co;
      ">

Or in your server configuration:

# Nginx
add_header Content-Security-Policy "script-src 'self' https://cdn.omise.co; connect-src 'self' https://api.omise.co https://vault.omise.co; frame-src https://api.omise.co;";

Common Issues & Troubleshooting

Issue: "Omise is not defined"

Causes:

Script hasn't loaded yet
Script blocked by ad blocker
CSP blocking script

Solution:

// Wait for script to load
window.addEventListener('load', function() {
    if (typeof Omise !== 'undefined') {
        Omise.setPublicKey('pkey_test_YOUR_KEY');
    }
});

// Or use script onload event
const script = document.createElement('script');
script.src = 'https://cdn.omise.co/omise.js';
script.onload = () => {
    Omise.setPublicKey('pkey_test_YOUR_KEY');
};
document.body.appendChild(script);

Issue: "Public key is required"

Cause: Forgot to call setPublicKey() before using Omise methods

Solution:

// Always set key first
Omise.setPublicKey('pkey_test_YOUR_KEY');

// Then use Omise methods
Omise.createToken('card', cardData, callback);

Issue: CORS errors

Cause: Trying to use Omise.js on HTTP (not HTTPS)

Solution:

Use HTTPS in production
Use http://localhost for development
Or use ngrok: ngrok http 3000

Issue: Works locally but not in production

Causes:

Using test keys in production
HTTPS not configured
CSP blocking requests

Solution:

Use live keys: pkey_live_...
Ensure HTTPS is enabled
Check CSP headers
Verify firewall rules

Testing Installation

Create a simple test page:

<!DOCTYPE html>
<html>
<head>
    <title>Omise.js Test</title>
</head>
<body>
    <h1>Omise.js Installation Test</h1>
    <div id="status">Loading...</div>

    <script src="https://cdn.omise.co/omise.js"></script>
    <script>
        const statusEl = document.getElementById('status');

        // Test 1: Check if Omise.js loaded
        if (typeof Omise === 'undefined') {
            statusEl.innerHTML = '❌ Omise.js failed to load';
            statusEl.style.color = 'red';
        } else {
            statusEl.innerHTML = '✅ Omise.js loaded successfully!';
            statusEl.style.color = 'green';

            // Test 2: Set public key
            try {
                Omise.setPublicKey('pkey_test_5xs8t3mho5d4pbbkjz1dk');
                statusEl.innerHTML += '<br>✅ Public key set successfully!';

                // Test 3: Create test token
                Omise.createToken('card', {
                    name: 'Test User',
                    number: '4242424242424242',
                    expiration_month: 12,
                    expiration_year: 2027,
                    security_code: '123'
                }, function(statusCode, response) {
                    if (statusCode === 200) {
                        statusEl.innerHTML += '<br>✅ Test token created: ' + response.id;
                    } else {
                        statusEl.innerHTML += '<br>❌ Token creation failed: ' + response.message;
                        statusEl.style.color = 'orange';
                    }
                });
            } catch (error) {
                statusEl.innerHTML += '<br>❌ Error: ' + error.message;
                statusEl.style.color = 'red';
            }
        }
    </script>
</body>
</html>

FAQ

Do I need to install Omise.js on the server?

No! Omise.js is a client-side library that runs in the browser only. For server-side operations (creating charges, refunds, etc.), use the server libraries.

Can I use Omise.js offline?

No, Omise.js requires internet connection to communicate with Omise servers for tokenization. Both your users and your server need internet access.

Which version should I use?

Use the version-less CDN URL (https://cdn.omise.co/omise.js) to automatically receive updates and bug fixes. Only pin to a specific version if you need guaranteed compatibility.

Can I self-host Omise.js?

While technically possible, we strongly discourage it because:

You won't receive security updates
PCI compliance may be affected
Performance may be slower
You're responsible for updates

Always use the official CDN.

Does Omise.js work with TypeScript?

Yes! Install the type definitions:

npm install --save-dev @types/omise

Then use with types:

declare global {
    interface Window {
        Omise: any;
    }
}

window.Omise.setPublicKey('pkey_test_YOUR_KEY');

What about bundler compatibility?

Omise.js works with all modern bundlers:

✅ Webpack
✅ Vite
✅ Rollup
✅ Parcel
✅ esbuild

We recommend loading via CDN for best performance, but npm package works with all bundlers.

Payment Form Integration - Use pre-built payment form
Custom Integration - Build custom UI
API Reference - Complete method documentation
Testing Guide - Test your integration
Security Best Practices

Installation Methods​

1. CDN (Recommended)​

2. NPM Package​

Configuration​

Basic Setup​

Framework-Specific Setup​

React​

Vue.js​

Angular​

Next.js​

Environment Variables​

.env File​

Accessing in Code​

Verification​

Requirements​

Browser Support​

HTTPS Required​

Content Security Policy​

Common Issues & Troubleshooting​

Issue: "Omise is not defined"​

Issue: "Public key is required"​

Issue: CORS errors​

Issue: Works locally but not in production​

Testing Installation​

FAQ​

Related Resources​

Next Steps​

Installation Methods

1. CDN (Recommended)

2. NPM Package

Configuration

Basic Setup

Framework-Specific Setup

React

Vue.js

Angular

Next.js

Environment Variables

.env File

Accessing in Code

Verification

Requirements

Browser Support

HTTPS Required

Content Security Policy

Common Issues & Troubleshooting

Issue: "Omise is not defined"

Issue: "Public key is required"

Issue: CORS errors

Issue: Works locally but not in production

Testing Installation

FAQ

Related Resources

Next Steps