Sign Up

Developer Guide Menu

Creating a Transaction Search Request

To create a transaction search, your client application must send a POST request. The request body contains the details for creating the search, such as the search name, the time zone, and the parameters for the search. The format of the URL is as follows:
POST https://url_prefix/tss/v2/searches
The format of the request body is:
{
  "save": "boolean",
  "name": "string" ,
  "timezone": "string",
  "query": "string",
  "offset": "integer",
  "limit": "integer",
  "sort": "integer"
}
For a complete list of field-level descriptions, see the API Reference Guide.

Filtering by Query Parameter

You can use the supported API fields in the table below as query parameters in the
query
 field of the search request.
Supported operators are
AND
 and
OR
.
Use the format
field:value AND field2:value
.
Field hierarchy uses the dotted format
object.field
 or
object.field.subfield
.
The table below lists the supported fields and how each filter can be used.

Table:

Query Parameters
Field/Parameter
Description
Example
clientReferenceInformation.code
Client-generated order reference or tracking number. CyberSource recommends that you send a unique value for each transaction so that you can perform meaningful searches for the transaction.
clientReferenceInformation.code:12345
submitTimeUtc
The date and time a transaction was submitted, or a range of times.
For more information, see the Time Filtering section below.
merchantInformation.resellerId
Only for resellers: query transactions for all merchants under the reseller portfolio.
merchantInformation.resellerId:1234
merchantInformation.accountId
Only for resellers: query transactions for one of your merchant accounts.
merchantInformation.accountId:cybs_acct
paymentInformation.card.number
Payment account number.
paymentInformation.card.number:4111111111111111
paymentInformation.bank.account.checkNumber
Payment account number.
paymentInformation.bank.account.checkNumber:213421432143
proccessorInformation.approvalCode
Authorization code for the transaction.
proccessorInformation.approvalCode:1234
The following examples show several ways of using these keywords in the query parameter.

Table:

Keyword Query Examples
Type of Search
Example
Two filters, using AND.
“query”: “clientReferenceInformation.code:1111 AND submitTimeUtc:[NOW/DAY-1DAYS TO NOW/DAY+1DAY}"
Three values for one filter, using OR.
“query”: “clientReferenceInformation.code:(1111 OR 2222 OR 3333)”
Multiple filters and values, using both AND and OR.
“query”: “clientReferenceInformation.code:(1111 OR 2222 OR 3333) AND submitTimeUtc:[NOW/DAY-1DAYS TO NOW/DAY+1DAY}”

Filtering Using submitTimeUtc

The
submitTimeUtc
 field uses date math expressions, which enables you to use dates and times relative to a fixed moment, including the current time which is represented by
NOW
.
You can also use Epoch Time for the start and end time. For example,
submitTimeUtc:[1556712000000 TO 1556757600000
].
Date Math Syntax
Date math expressions consist of either adding some quantity of time in a specified unit, or rounding the current time by a specified unit. Expressions can be joined and are evaluated left to right.
A slash
/
 is used to indicate rounding.
NOW/HOUR
 represents the beginning of the current hour. If the current time is 4:12 PM (
NOW
), then
NOW/HOUR
 would be the start of that hour, 4:00 PM.Valid values in Date Math are:
DAY
 or
DAYS
MONTH
 or
MONTHS
MINUTE
 or
MINUTES
Date Math Range
Date math supports date range searches. The syntax is [startDate TO endDate}.
[
 indicates the date is included in the range;
{
 indicates the date is excluded.
For example, If we want to search for transactions from the previous day, and the current date is May 3, 2019,
[NOW/DAY-1DAY TO NOW/DAY
} would search for transactions with a date between May 2, 2019, 12:00 AM to May 2, 2019, 11:59 PM.
More Examples
Last hour:
[NOW/HOUR-1HOUR TO NOW/HOUR}
Today:
[NOW/DAY TO NOW/DAY+1DAY}
Yesterday:
[NOW/DAY-1DAY TO NOW/DAY}
Last 7 days:
[NOW/DAY-7DAYS TO NOW/DAY+1DAY}
Month-to-Date:
[NOW/MONTH TO NOW/DAY+1DAY}
Last month:
[NOW/MONTH-1MONTH TO NOW/MONTH}
Last 6 months:
[NOW/DAY-6MONTHS TO NOW/DAY+1DAY}

Example: Transaction Search Request

POST https://<url_prefix>/tss/v2/searches

{
  "save": "save",
  "name": "Search by Code",
  "timezone": "America/Denver",
  "query": "clientReferenceInformation.code:123456",
  "offset": "0",
  "limit": "100",
  "sort": "submitTimeUtc:desc"
}

Responses

This call can return one of the following HTTP status codes:
  • 201: Successful response. If no records are found, the response will include
    totalCount:0
    .
  • 400: Invalid request.
  • 502: Unexpected system error or system timeout.
For detailed information on the responses, including which fields are returned, see the
Transaction Search REST API Reference
index.html#transaction-search.
On This Page
Top