Version: 2019-05-29 (Current)

Omise API Reference

Build powerful payment integrations with the Omise RESTful API. Process payments across 40+ payment methods in Southeast Asia and Japan.

Overview

The Omise API is organized around REST principles with predictable resource-oriented URLs, JSON-encoded requests and responses, and standard HTTP response codes and verbs.

Base URLs

Server	URL	Purpose
API Server	`https://api.omise.co`	Charges, customers, transfers, and account operations
Vault Server	`https://vault.omise.co`	Token creation (secure card data handling)

Current API Version

Version: 2019-05-29

Specify the API version using the Omise-Version header (optional, defaults to your account's API version):

Omise-Version: 2019-05-29

Quick Start

1. Get Your API Keys

Find your API keys in the Omise Dashboard:

Public Key (pkey_*) - For client-side operations (tokens, sources)
Secret Key (skey_*) - For server-side operations (charges, customers)

Keep Your Secret Key Safe

Never expose your secret key in client-side code, GitHub repositories, or public places. Use environment variables and server-side code only.

2. Authenticate Requests

Omise uses HTTP Basic Authentication:

Username: Your API key
Password: Leave blank (empty string)

# Using secret key
curl https://api.omise.co/charges \
  -u skey_test_YOUR_SECRET_KEY:

# Using public key
curl https://vault.omise.co/tokens \
  -u pkey_test_YOUR_PUBLIC_KEY:

3. Make Your First Request

Create a test charge:

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

Response:

{
  "object": "charge",
  "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
  "amount": 100000,
  "currency": "thb",
  "status": "successful",
  "authorized": true,
  "captured": true,
  ...
}

API Resources

Core Payment Processing

💳 Charges

Create, capture, and manage payment charges across all supported payment methods.

POST /charges • GET /charges/:id • PATCH /charges/:id

🔐 Tokens

Securely tokenize credit card information without PCI compliance burden.

POST /tokens • GET /tokens/:id

📱 Sources

Create payment sources for alternative payment methods like PromptPay, mobile banking, and QR codes.

POST /sources • GET /sources/:id

↩️ Refunds

Issue full or partial refunds for completed charges.

POST /charges/:id/refunds • GET /refunds/:id

Customer Management

👤 Customers

Store customer information and saved payment methods for recurring charges.

POST /customers • GET /customers/:id • PATCH /customers/:id

💳 Cards

Manage saved credit/debit cards attached to customers.

GET /customers/:id/cards • DELETE /customers/:id/cards/:card_id

Money Management

💸 Transfers

Transfer funds to bank accounts and manage automatic transfer schedules.

POST /transfers • GET /transfers/:id • GET /transfers/schedules

🏦 Recipients

Create and verify bank account recipients for transfers.

POST /recipients • GET /recipients/:id • POST /recipients/:id/verify

💰 Balance

Check your available and pending balance across all currencies.

GET /balance

📊 Transactions

View detailed transaction history for accounting and reconciliation.

GET /transactions • GET /transactions/:id

Additional Resources

⚖️ Disputes

Manage chargebacks and disputes.

📢 Events

Access event logs for webhooks.

📅 Schedules

Set up recurring charges and transfers.

🔗 Payment Links

Create shareable payment links.

🔍 Search

Search across all resources.

⚙️ Account

View and update account settings.

Essential Guides

Before diving into specific endpoints, familiarize yourself with these core concepts:

🔐 Authentication

Learn how to authenticate API requests using public and secret keys, handle API versioning, and secure your integration.

❌ Error Handling

Understand error response formats, common error codes, and best practices for handling failures gracefully.

📄 Pagination

Navigate large result sets efficiently with offset and limit parameters.

🔁 Idempotency

Safely retry requests without duplicating operations using idempotency keys.

🏷️ API Versioning

Manage API version changes and maintain backward compatibility.

⏱️ Rate Limiting

Stay within API rate limits and handle rate limit errors.

Common Workflows

Accept a Credit Card Payment

Client-side: Create a token with card data
```
POST https://vault.omise.co/tokens
```
Server-side: Create a charge with the token
```
POST https://api.omise.co/charges
```

View Complete Guide →

Accept PromptPay QR Payment

Server-side: Create a PromptPay source
```
POST https://api.omise.co/sources
```
Display QR code to customer
Receive webhook when payment completes

View Complete Guide →

Save Card for Future Charges

Create a customer
```
POST https://api.omise.co/customers
```

Attach card token to customer

PATCH https://api.omise.co/customers/:id

Charge the customer's default card
```
POST https://api.omise.co/charges
```

View Complete Guide →

Response Format

All API responses are JSON-encoded objects with an object field indicating the resource type:

{
  "object": "charge",
  "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
  "livemode": false,
  "amount": 100000,
  "currency": "thb",
  ...
}

List Objects

List endpoints return paginated results:

{
  "object": "list",
  "data": [
    { "object": "charge", "id": "chrg_..." },
    { "object": "charge", "id": "chrg_..." }
  ],
  "limit": 20,
  "offset": 0,
  "total": 142,
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-02-07T23:59:59Z"
}

Testing

Use test API keys (containing _test_) for development:

Test Public Key: pkey_test_...
Test Secret Key: skey_test_...

Test keys:

✅ Don't process real payments
✅ Accept test card numbers
✅ Return realistic responses
✅ Trigger webhooks to test endpoints

View Test Cards →

Client Libraries

Official libraries for popular programming languages:

Getting Help

Documentation

API Reference: You're here!
Payment Guides: Accept Payments
Webhooks: Webhooks Guide
Testing: Testing Guide

Support

Dashboard: https://dashboard.omise.co
Support Email: support@omise.co
Status Page: https://status.omise.co

Community

GitHub: https://github.com/omise
Stack Overflow: Tag omise

Next Steps

🔐 Authentication Guide

Learn how to authenticate your API requests and secure your integration.

Get Started →

💳 Charges API

Start accepting payments by creating your first charge.

View Charges API →

Ready to build? Start with Authentication or jump straight to Creating a Charge.

Overview​

Base URLs​

Current API Version​

Quick Start​

1. Get Your API Keys​

2. Authenticate Requests​

3. Make Your First Request​

API Resources​

Core Payment Processing​

Customer Management​

Money Management​

Additional Resources​

Essential Guides​

🔐 Authentication​

❌ Error Handling​

📄 Pagination​

🔁 Idempotency​

🏷️ API Versioning​

⏱️ Rate Limiting​

Common Workflows​

Accept a Credit Card Payment​

Accept PromptPay QR Payment​

Save Card for Future Charges​

Response Format​

List Objects​

Testing​

Client Libraries​

Getting Help​

Documentation​

Support​

Community​

Next Steps​

🔐 Authentication Guide

💳 Charges API

Overview

Base URLs

Current API Version

Quick Start

1. Get Your API Keys

2. Authenticate Requests

3. Make Your First Request

API Resources

Core Payment Processing

Customer Management

Money Management

Additional Resources

Essential Guides

🔐 Authentication

❌ Error Handling

📄 Pagination

🔁 Idempotency

🏷️ API Versioning

⏱️ Rate Limiting

Common Workflows

Accept a Credit Card Payment

Accept PromptPay QR Payment

Save Card for Future Charges

Response Format

List Objects

Testing

Client Libraries

Getting Help

Documentation

Support

Community

Next Steps