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.
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.
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 includetotalCount: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