検索クエリとフィルター

このページで扱うトピック

Search API(検索)を使用すると、特定のタイプ(scope)のデータ内レコードを検索できます。

使用法

検索scopeが必要です。 次のように簡単な検索を行えます。

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

上記の例では、最後に作成された課金が最初に表示された状態で、アカウントのすべての課金が返されています。 結果はページ分割され、応答は最初のページに表示され、1ページあたりのデフォルトの結果は30です。 使用可能なすべてのパラメーター、オブジェクト構造、およびその他の例については、Search APIを参照してください。

検索を絞り込むには、queryおよびfiltersパラメーターを追加します。 queryとfiltersの両方が指定された場合、結果は結合されることになります。

　クエリ

queryパラメータが指定されると、返されるオブジェクトは、その範囲に固有の属性の1つとしてクエリ文字列が検索されるオブジェクトとなります。

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

上記の例では、検索用のクエリ属性の1つ(例えば、customer_name)で文字列somchaiが探索された場合の課金を返しています。

フィルター

filtersパラメーターが指定されている場合、返されるオブジェクトは、フィルターオブジェクトによって設定された条件に一致するオブジェクトです。

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

上記の例では、amountフィールドが正確に1000 USDの課金を返しています。

金額フィールドの検索には、最小通貨単位ではなく、一般に使用されている通貨単位を利用します。 したがって、amount=100000とcurrency=USDで作成された課金は、filters[amount]=1000として検索可能です。

ブーリアン

ブーリアン値フィルターの場合、trueとfalseの代わりに同値の自然言語が利用されます。

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"

範囲

数値および日付フィルターには範囲を追加できます。 同じような自然言語(たとえばthis_month)も利用できます。

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"

最初の例では、金額が1000〜2000(USD、THB、JPYなど)の料金を検索します。 2番目の例では、2019年内に作成された課金の検索を実行します。 3番目の例では、今月作成された課金の検索を実行します。

IDフィールドを展開する

API全体で特定の属性は、識別子、デフォルト、またはオブジェクト自体を返すことができます。 こうした属性をオブジェクトとして返すには、expandパラメーターを使用します。

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

検索結果のエクスポート

特定の範囲(課金、顧客、チャージバック、追加振込先口座、課金の払い戻し、送金)をエクスポートできます。 検索を作成し、export=trueとfilter_type(monthly_captured,monthly_created, または monthly_dateのいずれか)を渡す場合、レスポンスには、新しく作成され、エクスポートの識別子に設定されたexport属性が含まれている必要があります。オプションで、filter_dateを渡すことができます。その時点での月がデフォルトの値となります。

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

利用可能なクエリとフィルター

charge

このレコード scope=charge to search for charge を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Charge amount in main unit of charge currency. 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).
captured_at UTC datetime of charge capture (payment) in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
credit_card_brand Card brand (e.g. Visa, Mastercard).
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.
disputed Whether charge is disputed.
failure_code Failure code if status == failed. See testing for possible codes.
fraud Whether charge is confirmed to be fraudulent.
is_installment Whether charge is installment.
refunded Charge amount refunded.
refund_amount Amount for refund in common currency unit. For example, use 1000 for 1000 THB.
scheduled Whether charge is scheduled.
source_of_fund Payment mode. One of card, offsite, or offline.
source_type Payment source type
status Charge status. One of failed, expired, pending, reversed or successful.
voided Whether, in the case of a refund, charge was voided instead. Charges are voided if refund is processed before settlement time.
installment_terms Installment term in months. See installments for allowed values (type=installment_*).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
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_name Card owner name.
description Charge description.
failure_message Message describing the failure if status == failed.
metadata Custom metadata (e.g. {"answer": 42}) for charge.

charge_schedule

このレコード scope=charge_schedule to search for charge schedule を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
status One of:
  • active: The schedule is running.
  • expiring: The schedule's next occurrence is its last.
  • expired: The schedule has reached its last occurrence and is not running anymore.
  • deleted: The schedule has been deleted and is not running anymore.
  • suspended: The schedule could not be completed and was stopped.
.
active Whether scheduled charge is active or not. Includes schedules where status==active or status==expiring
amount Scheduled charge amount in main unit of charge currency. For example, use 1000 for 1000 THB.
created UTC datetime of schedule creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
card_last_digits Last four (4) digits of card number.

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
recurrence_id The schedule identifier matching /schd(_test)?_[0-9a-z]+/.
currency Currency for scheduled charge as three-letter ISO 4217 code.
description Scheduled charge description.
customer_email Customer email address.
card_brand Card brand (e.g. Visa, Mastercard).
card_bank Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.
card_name Card owner name.

customer

このレコード scope=customer to search for customer を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
created UTC datetime of customer creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
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.

dispute

このレコード scope=dispute to search for dispute を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Dispute amount in smallest unit of dispute currency.
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.
fraud Whether dispute is related to a fraudulent charge.
status The dispute status. One of open, pending, won or lost. (note: won and lost disputes are retrievable using the /disputes/closed endpoint).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
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.

このレコード scope=link to search for link を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Link amount in main unit of link currency. For example, use 1000 for 1000 THB.
created UTC datetime of link creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for link as three-letter ISO 4217 code.
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.

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
id The link identifier matching /link(_test)?_[0-9a-z]+/.
description Link description.
link_reference URI of link.
title Link title.

receipt

このレコード scope=receipt to search for receipt を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
created UTC datetime of receipt creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
id The receipt identifier matching /rcpt(_test)?_[0-9a-z]+/.

recipient

このレコード scope=recipient to search for recipient を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
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).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
id The recipient identifier matching /recp(_test)?_[0-9a-z]+/.
bank_name Bank account holder name. For Japanese bank accounts, see notes on entering bank account holder names.
bank_brand Bank account brand (Thailand and Singapore only).
description Recipient description.
email Recipient email address.
metadata Custom metadata (e.g. {"answer": 42}) for recipient.
name Recipient name.
tax_id Recipient tax ID.

refund

このレコード scope=refund to search for refund を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Refund amount in smallest unit of charge currency.
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 refunded charge was voided instead. Charges are voided if refund is processed before settlement time.

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
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.

transfer

このレコード scope=transfer to search for transfer を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Transfer amount in smallest unit of transfer currency.
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.
fee Opn Payments 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).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
id The transfer identifier matching /trsf(_test)?_[0-9a-z]+/.
bank_name Bank account holder name. For Japanese bank accounts, see notes on entering bank account holder names.
bank_brand Bank account brand (Thailand and Singapore only).
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]+/.

transfer_schedule

このレコード scope=transfer_schedule to search for transfer schedule を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
status One of:
  • active: The schedule is running.
  • expiring: The schedule's next occurrence is its last.
  • expired: The schedule has reached its last occurrence and is not running anymore.
  • deleted: The schedule has been deleted and is not running anymore.
  • suspended: The schedule could not be completed and was stopped.
.
active Whether scheduled transfer is active or not. Includes schedules where status==active or status==expiring
created UTC datetime of schedule creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
recurrence_id The schedule identifier matching /schd(_test)?_[0-9a-z]+/.
recipient_name Name of recipient of scheduled transfer.

transaction

このレコード scope=transaction to search for transaction を使用します。 次のクエリとフィルターは、このスコープに固有のものです。

フィルター

filtersオブジェクトで次のキーを使用して特定の値を検索します。

キー 説明
amount Transaction amount in smallest unit of transaction currency.
created UTC datetime of transaction creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for transaction as three-letter ISO 4217 code.
hold_until UTC datetime of when transaction amount becomes part of available balance in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) (also searchable as transferable_at)
kind Kind of transaction. One of balance_lost, balance_recovered, charge_captured, charge_captured_platform_fee, dispute_started, dispute_won, dispute_overturned_loss, dispute_overturned_win, invoice_paid, receipt_adjusted, refund_paid, refund_processed, refund_voided, transfer_failed, transfer_sent, transfer_waived.

クエリ

query文字列を使用して、次のキーを検索します。

キー 説明
id The transaction identifier matching /trxn(_test)?_[0-9a-z]+/.
record_id Origin for transaction. One of charge identifier, refund identifier, transfer identifier, dispute identifier, or receipt identifier.
Omiseは、お客様のウェブサイト全般における利便性を向上するためにクッキーを利用し、お客様のアクセス、閲覧履歴に関する情報を収集します。 当社のウェブサイトを閲覧し続けることにより、お客様は当社のプライバシーポリシーに同意することとします。 詳細はこちら