Quickstart Guide

Create your first test charge in 5 minutes. This guide walks you through making your first API call to accept a payment.

What You'll Build

By the end of this guide, you'll have:

• ✅ Created an Omise test account
• ✅ Located your API keys
• ✅ Made your first API call
• ✅ Created a successful test charge
• ✅ Understood the basic payment flow

Time Required: 5-10 minutes

Step 1: Create Your Account

1. Go to dashboard.omise.co/signup
2. Enter your email address
3. Create a password (at least 10 characters with uppercase, lowercase, number, and special character like @ # ?)
4. Click Register
5. Verify your email address

Instant Access

You'll get immediate access to your test dashboard - no business verification required!

Step 2: Get Your API Keys

1. Log into your Test Dashboard
2. Navigate to Settings → Keys
3. You'll see two keys:
   • Public Key (pkey_test_...) - for client-side operations
   • Secret Key (skey_test_...) - for server-side operations

Keep Keys Secure

Never expose your secret key in client-side code or public repositories!

Step 3: Make Your First Charge

Omise uses a two-step process to accept payments:

Understanding the Flow

Step 3a: Create a Token

First, tokenize the payment method using your public key. This keeps card data out of your servers.

cURL

curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_YOUR_PUBLIC_KEY: \
  -d "card[name]=John Doe" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2027" \
  -d "card[security_code]=123"

JavaScript

// Using Omise.js (recommended)
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');

Omise.createToken('card', {
  name: 'John Doe',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2027,
  security_code: '123'
}, function(statusCode, response) {
  if (statusCode == 200) {
    console.log('Token:', response.id);
    // Send token to your server
  } else {
    console.error('Error:', response.message);
  }
});

PHP

<?php
require_once 'vendor/autoload.php';

define('OMISE_PUBLIC_KEY', 'pkey_test_YOUR_PUBLIC_KEY');

$token = OmiseToken::create([
  'card' => [
    'name' => 'John Doe',
    'number' => '4242424242424242',
    'expiration_month' => 12,
    'expiration_year' => 2027,
    'security_code' => '123'
  ]
]);

echo $token['id']; // tokn_test_...
?>

Response:

{
  "object": "token",
  "id": "tokn_test_5xp6ca4dtzx5cskm9mk",
  "livemode": false,
  "location": "/tokens/tokn_test_5xp6ca4dtzx5cskm9mk",
  "used": false,
  "card": {
    "object": "card",
    "id": "card_test_5xp6ca3y2vtgcw24o9p",
    "livemode": false,
    "brand": "Visa",
    "last_digits": "4242",
    "expiration_month": 12,
    "expiration_year": 2027
  },
  "created_at": "2024-01-15T07:30:00Z"
}

Save the token.id value - you'll need it in the next step!

Step 3b: Create a Charge

Now use the token with your secret key to create a charge on your server.

cURL

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_YOUR_SECRET_KEY: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_5xp6ca4dtzx5cskm9mk"

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_YOUR_SECRET_KEY'
});

omise.charges.create({
  amount: 100000, // Amount in smallest currency unit (satangs, cents, etc.)
  currency: 'thb',
  card: 'tokn_test_5xp6ca4dtzx5cskm9mk'
}, function(err, charge) {
  if (err) {
    console.error('Error:', err.message);
  } else {
    console.log('Charge successful:', charge.id);
  }
});

Python

import omise

omise.api_secret = 'skey_test_YOUR_SECRET_KEY'

charge = omise.Charge.create(
    amount=100000,  # Amount in smallest currency unit
    currency='thb',
    card='tokn_test_5xp6ca4dtzx5cskm9mk'
)

print('Charge ID:', charge.id)
print('Status:', charge.status)

Ruby

require 'omise'

Omise.secret_api_key = 'skey_test_YOUR_SECRET_KEY'

charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: 'tokn_test_5xp6ca4dtzx5cskm9mk'
})

puts "Charge ID: #{charge.id}"
puts "Status: #{charge.status}"

PHP

<?php
require_once 'vendor/autoload.php';

define('OMISE_SECRET_KEY', 'skey_test_YOUR_SECRET_KEY');

$charge = OmiseCharge::create([
  'amount' => 100000,
  'currency' => 'thb',
  'card' => 'tokn_test_5xp6ca4dtzx5cskm9mk'
]);

echo 'Charge ID: ' . $charge['id'] . PHP_EOL;
echo 'Status: ' . $charge['status'] . PHP_EOL;
?>

Response:

{
  "object": "charge",
  "id": "chrg_test_5xp6ccfmecft4zxrb7p",
  "location": "/charges/chrg_test_5xp6ccfmecft4zxrb7p",
  "amount": 100000,
  "currency": "thb",
  "status": "successful",
  "paid": true,
  "transaction": "trxn_test_5xp6ccfmvcsm7ih0c8w",
  "card": {
    "object": "card",
    "id": "card_test_5xp6ca3y2vtgcw24o9p",
    "livemode": false,
    "brand": "Visa",
    "last_digits": "4242"
  },
  "created_at": "2024-01-15T07:30:15Z"
}

🎉 Congratulations! You've successfully created your first charge!

Step 4: View in Dashboard

1. Go to your Test Dashboard
2. Click on Charges in the left menu
3. You'll see your test charge with status "Successful"

Test Cards

Use these card numbers for testing different scenarios:

Card Number	Brand	Result
4242 4242 4242 4242	Visa	✅ Successful
5555 5555 5555 4444	Mastercard	✅ Successful
3530 1113 3330 0000	JCB	✅ Successful
3782 822463 10005	Amex	✅ Successful

Any Expiry & CVV

In test mode, use any future expiration date and any 3-4 digit CVV code.

View all test cards →

Next Steps

Now that you've made your first charge, here's what to explore next:

1. Build a Real Checkout

Use Omise.js for Production

Learn how to implement a complete checkout flow with a payment form.

View Omise.js Guide →

2. Explore Payment Methods

Add More Payment Options

Accept PromptPay, TrueMoney, mobile banking, and 40+ other payment methods.

Browse Payment Methods →

3. Handle Webhooks

Get Real-Time Updates

Receive notifications when payments succeed, fail, or get refunded.

Set Up Webhooks →

4. Test Thoroughly

Test All Scenarios

Simulate failures, refunds, and different payment methods.

Testing Guide →

5. Go Live

Launch to Production

Complete your business verification and start accepting real payments.

Going Live Checklist →

Common Issues & Solutions

Token Creation Fails

Problem: Getting authentication errors when creating tokens.

Solution:

• Verify you're using your public key (starts with pkey_)
• Check that the key is for test mode (pkey_test_...)
• Ensure the key is active in your dashboard

Charge Creation Fails

Problem: Charge returns an error or invalid request.

Solution:

• Verify you're using your secret key (starts with skey_)
• Ensure the token hasn't been used already (tokens are single-use)
• Check that the amount is in the smallest currency unit (e.g., satangs for THB)
• Verify the currency code is correct (e.g., thb, jpy, sgd)

Card Declined in Test Mode

Problem: Test card is being declined.

Solution:

• Use the correct test card numbers from our list
• Ensure you're in test mode (using test keys)
• Check that you're using a future expiration date

FAQ

Why do I need both a token and a charge?

The two-step process keeps your integration secure:

1. Token Creation happens on the client (browser/app) using your public key. This way, sensitive card data goes directly to Omise without touching your servers.

2. Charge Creation happens on your server using your secret key. Your server uses the token (not raw card data) to complete the payment.

This separation of concerns reduces your PCI compliance burden and keeps customer data secure.

Can I reuse tokens?

No, tokens are single-use only. Once you create a charge with a token, that token can't be used again.

To charge a customer multiple times, you need to:

• Create a Customer object and attach the card
• Use the customer ID for future charges
• Learn about Customers →

What currencies are supported?

Supported currencies depend on your account's region:

• Thailand: THB (Thai Baht)
• Japan: JPY (Japanese Yen)
• Singapore: SGD (Singapore Dollar)
• Malaysia: MYR (Malaysian Ringgit)

Some accounts may support multiple currencies. Check your dashboard for available options.

Learn about multi-currency →

How do I specify amounts?

Always specify amounts in the smallest currency unit:

• THB: 100000 = ฿1,000.00 (satangs)
• JPY: 1000 = ¥1,000 (yen - no decimal places)
• SGD: 10000 = S$100.00 (cents)
• MYR: 10000 = RM100.00 (cents)

Never use decimal points in the amount field.

Where can I find example code?

• Official Libraries: Each of our SDKs includes example code
• GitHub: Sample applications at github.com/omise
• Documentation: Code examples throughout these docs in 8+ languages

How do I transition from test to live?

1. Complete your business verification (see Going Live)
2. Switch from test keys to live keys in your code
3. Test with small real transactions first
4. Monitor your dashboard and webhook endpoints
5. Scale up gradually

Your integration code remains the same - only the API keys change!

Complete Example

Here's a complete HTML + JavaScript example you can run locally:

<!DOCTYPE html>
<html>
<head>
  <title>Omise Quickstart</title>
  <script src="https://cdn.omise.co/omise.js"></script>
</head>
<body>
  <h1>Pay ฿1,000.00</h1>

  <form id="payment-form">
    <div>
      <label>Card Number</label>
      <input type="text" id="card-number" value="4242424242424242">
    </div>
    <div>
      <label>Name</label>
      <input type="text" id="card-name" value="John Doe">
    </div>
    <div>
      <label>Expiry (MM/YY)</label>
      <input type="text" id="card-expiry" value="12/25">
    </div>
    <div>
      <label>CVV</label>
      <input type="text" id="card-cvv" value="123">
    </div>
    <button type="submit">Pay Now</button>
  </form>

  <div id="result"></div>

  <script>
    // Set your public key
    Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');

    document.getElementById('payment-form').addEventListener('submit', function(e) {
      e.preventDefault();

      const expiry = document.getElementById('card-expiry').value.split('/');

      // Step 1: Create token
      Omise.createToken('card', {
        name: document.getElementById('card-name').value,
        number: document.getElementById('card-number').value,
        expiration_month: expiry[0],
        expiration_year: '20' + expiry[1],
        security_code: document.getElementById('card-cvv').value
      }, function(statusCode, response) {
        if (statusCode == 200) {
          // Step 2: Send token to your server to create charge
          createCharge(response.id);
        } else {
          document.getElementById('result').innerHTML =
            '<p style="color:red">Error: ' + response.message + '</p>';
        }
      });
    });

    function createCharge(token) {
      // In production, this would call your server endpoint
      // Your server would then use the secret key to create the charge
      fetch('/api/charges', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          token: token,
          amount: 100000,
          currency: 'thb'
        })
      })
      .then(response => response.json())
      .then(data => {
        document.getElementById('result').innerHTML =
          '<p style="color:green">Payment successful! Charge ID: ' + data.id + '</p>';
      })
      .catch(error => {
        document.getElementById('result').innerHTML =
          '<p style="color:red">Error: ' + error.message + '</p>';
      });
    }
  </script>
</body>
</html>

---

Need Help?

• Check our troubleshooting guide
• Contact support@omise.co
• Join our developer community

Ready for more? Continue to Understanding Concepts to learn how Omise works in detail.