Search charges

GEThttps://api.omise.co/search

Search and filter charges to find transactions by description, metadata, card details, customer information, and more. The Search API provides powerful full-text search capabilities across all charges.

---

🔑API Credentials

▼

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`scope`STRING(required)

Search scope. Must be set to "charge" to search charges.

Example:"charge"

Values:charge

Recommended - 2 fieldsRecommended Parameters

▼

`query`STRING(optional)

Search query string. Searches across charge description, metadata, card details (last 4 digits, brand, bank), and customer information. Supports multiple words (AND logic) and partial matches.

Example:"order 1234"

`filters`OBJECT(optional)

Filter criteria to narrow search results. Common filters include status, currency, amount, capture, paid, and created date ranges.

Example:{"status":"successful","currency":"thb","paid":true}

Additional - 3 fieldsAdditional Parameters

▼

---

Responses

200

Successful search

Search completed successfully. Returns a search result object with matching charges in the data array.

Response includes:

• data - Array of charge objects matching the search criteria
• total - Total number of results matching the search
• total_pages - Number of pages available
• page - Current page number
• per_page - Number of results per page
• order - Sort order applied (chronological or reverse_chronological)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required scope parameter
• Invalid page number (below 1)
• Invalid per_page value (above 100 or below 1)
• Malformed filters object

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

422

Invalid scope

Invalid search scope provided.

Common causes:

• Scope parameter is not "charge"
• Invalid scope value

---

Code samples

cURL

curl https://api.omise.co/search \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "scope=charge" \
  -d "query=order 1234" \
  -d "filters[status]=successful" \
  -d "filters[currency]=thb"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

results = Omise::Search.execute({
  scope: 'charge',
  query: 'order 1234',
  filters: {
    status: 'successful',
    currency: 'thb'
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

results = omise.Search.execute(
    scope='charge',
    query='order 1234',
    filters={
        'status': 'successful',
        'currency': 'thb'
    }
)

Node.js

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

const results = await omise.search.execute({
  scope: 'charge',
  query: 'order 1234',
  filters: {
    status: 'successful',
    currency: 'thb'
  }
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$results = OmiseSearch::execute([
    'scope' => 'charge',
    'query' => 'order 1234',
    'filters' => [
        'status' => 'successful',
        'currency' => 'thb'
    ]
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Map<String, Object> filters = new HashMap<>();
filters.put("status", "successful");
filters.put("currency", "thb");

SearchResult<Charge> results = client.search()
    .scope("charge")
    .query("order 1234")
    .filters(filters)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var results = await client.Search.Execute(new SearchRequest
{
    Scope = "charge",
    Query = "order 1234",
    Filters = new Dictionary<string, object>
    {
        { "status", "successful" },
        { "currency", "thb" }
    }
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

results, _ := client.Search(&operations.SearchCharges{
    Scope: "charge",
    Query: "order 1234",
    Filters: map[string]interface{}{
        "status":   "successful",
        "currency": "thb",
    },
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check that scope is provided and parameters are valid
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_scope	Invalid search scope	Ensure scope is set to "charge"

Search Filter Options

Filter	Type	Description
status	string	Charge status (pending, successful, failed, expired, reversed)
currency	string	Currency code (thb, jpy, sgd, myr, usd, etc.)
amount	integer	Exact amount in smallest currency unit
capture	boolean	Whether charge is captured (true/false)
paid	boolean	Whether charge is paid (true/false)
created	object	Date range filter (e.g., {gte: '2025-01-01', lte: '2025-01-31'})

---

Try it out

Required - 1 fields

▼

scope(Required)

Recommended - 2 fields

▼

Additional - 3 fields

▼