Search Query and Filters

The Search API allows you to search records within a given type (scope) of data.

Available Scopes

Usage

The search scope is required. A simple search looks like this:

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge"

The above example returns all charges on your account with the most recently created charges appearing first (order=reverse_chronological). The response is the first page (page=1) of paginated results with a default of 30 results per page (per_page=30). See Search API for all accepted parameters, object structure, and more examples.

You can add query and filters keys for more complex searches. When both query and filters are supplied, the result is the combined set.

Queries

When the query parameter is supplied, returned objects are those where the query string is found across one of a set of attributes specific to that scope.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "query=somchai"

The above example returns charges where the string somchai is found across one of the searchable query attributes (e.g. customer_name, description, etc.)

Filters

When the filters parameter is supplied, returned objects are those which match the conditions set by the filters object.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[amount]=1000"

The above example returns charges where the amount field is exactly 1000 currency units (USD, THB, JPY, etc.).

Note: for searching amount fields, use the commonly accepted currency unit, not the smallest currency unit. So, a charge created with amount 100000 and currency USD is searchable as 1000.

Booleans

For boolean (true or false) filters, some natural language equivalents are acceptable.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=yes"

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=on"

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=no"

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=off"

Ranges

For numeric and date filters, ranges and some natural language equivalents are acceptable.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[amount]=1000..2000"

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[created]=2019/01/01..2019/12/31"

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[created]=this_month"

The first example conducts a search for charges where the amount is between 1000 and 2000 (USD, THB, JPY, etc.). The second example conducts a search for charges where the creation date is within the year 2019. The third example conducts a search for charges where the creation date is this month.

Expanding ID Fields

Certain pre-defined fields can return either a reference to another object (via its id) or the object itself. For instance, on a refund object, the charge and transaction attributes are id strings (chrg_xxx and trxn_xxx). Use the expand parameter to return these attributes as charge and transaction objects instead.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=refund" \
     -d "expand=true"

Available Queries and Filters

Charge

Use scope=charge to search for Charge records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The charge identifier matching /chrg(_test)?_[0-9a-z]+/.

card_bank

Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.

card_brand

Card brand (e.g. Visa, Mastercard).

card_id

The card identifier matching /card(_test)?_[0-9a-z]+/.

card_name

Card owner name.

customer_description

Customer description.

customer_email

Customer email address.

customer_id

The customer identifier matching /cust(_test)?_[0-9a-z]+/.

description

Charge description.

failure_message

Message describing the failure if status == failed.

metadata

Custom metadata (e.g. {"answer": 42}) for charge.

Filters

FilterDescription

amount

Amount for charge in common currency unit. For example, use 1000 for 1000 THB.

authorized

Whether charge has been authorized.

capture

Whether charge is set to be automatically captured (paid).

captured

Whether charge has been captured (paid) (also searchable as paid).

captured_at

UTC datetime of charge capture (payment) in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) (also searchable as paid_at).

card_last_digits

Last four (4) digits of card number.

created

UTC datetime of charge creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency

Currency for charge as three-letter ISO 4217 code.

customer_present

Whether charge has a customer attached.

disputed

Whether charge is disputed.

failure_code

Failure code if status == failed. See testing for possible codes.

is_installment

Whether charge is installment.

refunded

Whether charge has been refunded.

refund_amount

Amount for refund in common currency unit. For example, use 1000 for 1000 THB.

reversed

Whether charge authorization has been reversed.

safe

Whether charge is safe. A safe charge is one which has successfully passed our fraud protection process.

scheduled

Whether charge is scheduled.

source_of_fund

Payment mode. One of card, offsite, or offline.

source_type

Payment source type. Value can be one of the following (depending on account and country):

  • alipay
  • barcode_alipay
  • bill_payment_tesco_lotus
  • econtext
  • installment_bay
  • installment_bbl
  • installment_first_choice
  • installment_kbank
  • installment_ktc
  • internet_banking_bay
  • internet_banking_bbl
  • internet_banking_ktb
  • internet_banking_scb
  • truemoney

See installments for allowed values.

status

Charge status. One of failed, expired, pending, reversed or successful.

voided

Whether charge has been voided.

installment_terms

Installment term in months. See installments for allowed values (type=installment_*).

Customer

Use scope=customer to search for Customer records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The customer identifier matching /cust(_test)?_[0-9a-z]+/.

description

Customer description.

email

Customer email address.

metadata

Custom metadata (e.g. {"answer": 42}) for customer.

Filters

FilterDescription

created

UTC datetime of customer creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Dispute

Use scope=dispute to search for Dispute records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The dispute identifier matching /dspt(_test)?_[0-9a-z]+/.

card_brand

Card brand (e.g. Visa, Mastercard).

card_id

The card identifier matching /card(_test)?_[0-9a-z]+/.

card_name

Card owner name.

metadata

Custom metadata (e.g. {"answer": 42}) for dispute.

message

Explanation for dispute.

reason_code

Dispute reason code.

reason_message

Dispute message associated with the dispute reason code.

Filters

FilterDescription

amount

Amount for dispute in common currency unit. For example, use 1000 for 1000 THB.

card_first_digits

First six (6) digits of the card number: the issuer identification number (IIN).

card_last_digits

Last four (4) digits of card number.

charge_id

The charge identifier matching /chrg(_test)?_[0-9a-z]+/.

closed_at

UTC datetime of dispute closure (i.e. status changed to won or lost) of the dispute in ISO 8601 format.

created

UTC datetime of dispute creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency

Currency for dispute as three-letter ISO 4217 code.

status

The dispute status. One of open, pending, won or lost. (note: won and lost disputes are retrievable using the /disputes/closed endpoint).

Use scope=link to search for Link records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The link identifier matching /link(_test)?_[0-9a-z]+/.

currency

Currency for link as three-letter ISO 4217 code.

description

Link description.

link_reference

URI of link.

title

Link title.

Filters

FilterDescription

amount

Amount for link in common currency unit. For example, use 1000 for 1000 THB.

created

UTC datetime of link creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

multiple

Whether link is able to be used more than once.

used

Whether single-use link (multiple=false) was used.

used_at

UTC datetime of the usage of the link in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Single-use links only.

Recipient

Use scope=recipient to search for Recipient records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The recipient identifier matching /recp(_test)?_[0-9a-z]+/.

bank_name

Bank account holder name.

bank_brand

Bank account brand name.

description

Recipient description.

email

Recipient email address.

metadata

Custom metadata (e.g. {"answer": 42}) for recipient.

name

Recipient name.

tax_id

Recipient tax ID.

Filters

FilterDescription

active

Whether recipient is active.

activated_at

UTC datetime of the activation of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

bank_last_digits

Last four (4) digits of bank account number.

created

UTC datetime of recipient creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

deleted

Whether recipient is deleted.

failure_code

Recipient creation failure code. One of name_mismatch, account_not_found, or bank_not_found.

type

Recipient type. One of individual or corporation.

verified

Whether recipient is verified.

verified_at

UTC datetime of the verification of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Refund

Use scope=refund to search for Refund records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The refund identifier matching /rfnd(_test)?_[0-9a-z]+/.

card_bank

Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.

card_brand

Card brand (e.g. Visa, Mastercard).

card_id

The card identifier matching /card(_test)?_[0-9a-z]+/.

card_name

Card owner name.

charge_description

Charge description.

currency

Currency for refund as three-letter ISO 4217 code.

metadata

Custom metadata (e.g. {"answer": 42}) for refund.

Filters

FilterDescription

amount

Amount for refund in common currency unit. For example, use 1000 for 1000 THB.

card_first_digits

First 6 digits of the card number: the issuer identification number (IIN).

card_last_digits

Last four (4) digits of card number.

charge_id

The charge identifier matching /chrg(_test)?_[0-9a-z]+/.

created

UTC datetime of refund creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

status

Status of the refund.

voided

Whether the refund has been voided.

Transfer

Use scope=transfer to search for Transfer records. The following queries and filters are specific to this scope.

Queries

QueryDescription

id

The transfer identifier matching /trsf(_test)?_[0-9a-z]+/.

bank_name

Bank account holder name.

bank_brand

Bank account brand name.

failure_code

Failure code for transfer. One of insufficient_balance, invalid_recipient, transfers_suspended, transfer_deleted, transfer_sent, or transfer_failed.

failure_message

Message describing the failure if failure_code exists.

metadata

Custom metadata (e.g. {"answer": 42}) for transfer.

recipient_email

Recipient email address.

recipient_id

Recipient identifier to which the transfer was sent.

recipient_name

Name of recipient to which transfer was sent.

transaction_id

The transaction identifier matching /trxn(_test)?_[0-9a-z]+/.

Filters

FilterDescription

amount

Amount for transfer in common currency unit. For example, use 1000 for 1000 THB.

created

UTC datetime of transfer creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency

Currency for transfer as three-letter ISO 4217 code.

deleted

Whether transfer is deleted.

fee

Omise transfer fee.

paid

Whether transfer was paid.

paid_at

UTC datetime of the transfer payment in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

sent

Whether transfer was sent.

sent_at

UTC datetime of the transfer send event in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).