Transaction Search API

Using the Transaction Search API, you can search for your transactions that meet specific criteria.
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.

Creating a Transaction Search Request

Follow these steps to create a transaction search request:
  1. Send a POST request to
    https://<url_prefix>/tss/v2/searches
     and include these required fields:

    ADDITIONAL INFORMATION

    • query
    • sort
    Use the name of the server as the
    <url_prefix>
    :
    • Production:
      api.cybersource.com
    • Production in India:
       api.in.cybersource.com
    • Test:
      apitest.cybersource.com
  2. Include these optional fields:

    ADDITIONAL INFORMATION

    • save
    • name
    • timezone
    • offset
    • sort
    For a list of supported time zones, see Supported Time Zones.

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
.
This list identifies the supported fields and how each filter can be used.
Query Parameters:
applicationInformation.applications.reconciliationId
 OR
reconciliationId
Transaction reference number, returned by the original transaction response.
Examples: 
applicationInformation.applications.reconciliationId:H74U3AD377ER921
reconciliationId:H74U3AD377ER921
buyerInformation.merchantCustomerId
Your identifier for the customer.
Example: 
buyerInformation.merchantCustomerId:0535439670
clientReferenceInformation.code
Client-generated order reference or tracking number. We recommend that you send a unique value for each transaction so that you can perform meaningful searches for the transaction.
Example: 
clientReferenceInformation.code:12345
clientReferenceInformation.partner.solutionId
Identifier for the partner that is integrated to our platform.
Example: 
clientReferenceInformation.partner.solutionId:89012345
deviceInformation.ipAddress
IP address of the customer's device.
Example: 
deviceInformation.ipAddress:23.45.35.29
id
A unique identification number generated by
Cybersource
 to identify the submitted request.
Example: 
id:6590834057836283403955
installmentInformation.identifier
Identifier for an installment payment transaction.
Example: 
installmentInformation.identifier:1000000000
merchantId
Cybersource
 merchant ID.
Example: 
merchantId:merchant10
merchantInformation.resellerId
Only for reseller. Query transactions for all merchants under the reseller portfolio.
Example: 
merchantInformation.resellerId:1234
merchantInformation.accountId
Query transactions for one of your merchant accounts.
Example: 
merchantInformation.accountId:cybs_acct
orderInformation.amountDetails.currency
ISO Standard Currency Codes.
See ISO Standard Country Codes for more information.
Example: 
orderInformation.amountDetails.currency:[USD]
orderInformation.amountDetails.totalAmount
Grand total for the order.
Example: 
orderInformation.amountDetails.totalAmount:100.00
orderInformation.billTo.email
Customer's email address.
Example: 
orderInformation.billTo.email:null@example.com
orderInformation.billTo.firstName
Customer’s first name. This name must be the same as the name on the card.
Example: 
orderInformation.billTo.firstName:John
orderInformation.billTo.lastName
Customer’s last name. This name must be the same as the name on the card.
Example: 
orderInformation.billTo.lastName:Doe
orderInformation.billTo.phoneNumber
Phone number associated with the customer's billing address.
Example: 
orderInformation.billTo.phoneNumber:8394552567
orderInformation.shipTo.phoneNumber
Phone number associated with the customer's shipping address.
Example: 
orderInformation.shipTo.phoneNumber:8394552567
paymentInformation.bank.account.number
Full bank account number.
Example: 
paymentInformation.bank.account.number:1234567890
paymentInformation.bank.account.prefix
The initial six numbers of a bank account number.
Example: 
paymentInformation.bank.account.prefix:1234
paymentInformation.bank.account.suffix
Last four digits of the customer’s bank account number.
Example: 
paymentInformation.bank.account.suffix:4321
paymentInformation.card.number
Full payment account number.
Example: 
paymentInformation.card.number:4111111111111111
paymentInformation.card.prefix
Initial six numbers on a payment account number.
Example: 
paymentInformation.card.prefix:4111
paymentInformation.card.suffix
Last four digits of the customer’s card number.
Example: 
paymentInformation.card.suffix:1111
paymentInformation.customer.customerId
Unique identifier for the customer's card and billing information.
Example: 
paymentInformation.customer.customerId:548323
paymentInformation.paymentType.method
Indicates the payment method used in this payment transaction. See Filtering by Payment Type for more information.
Example: 
paymentInformation.paymentType.method:MC
paymentInformation.paymentType.type
Indicates the payment type used in this payment transaction. For example: credit card or check. See Filtering by Payment Type for more information.
Example: 
paymentInformation.paymentType.type:credit card
processingInformation.commerceIndicator
Type of transaction. Some payment card companies use this information when determining discount rates.
Example: 
processingInformation.commerceIndicator:123abc
processorInformation.approvalCode
Authorization code returned by the processor.
Example: 
processorInformation.approvalCode:1234
processorInformation.retrievalReferenceNumber
Unique number that our platform generates to identify the transaction.
Example: 
processorInformation.retrievalReferenceNumber:122908889379
submitTimeUtc
The date and time a transaction was submitted, or a range of times. See Filtering Using submitTimeUtc for more information.
Example: 
submitTimeUtc:[2022-05-11T03:21:03Z]
The following examples show several ways of using these keywords in the query parameter.
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}”

Example: Creating a Search Request

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"
}

Retrieving a Saved Transaction Search Request

To retrieve a saved transaction search, your client application must send an HTTPS GET request to the server. The format of the URL is as follows:
GET https://<url_prefix>/tss/v2/searches/{searchID}
Transaction Search Request URL Values
Value
Description
<
url_prefix
>
Name of the server from which to download the report. Use one of these values:
  • Production:
    api.cybersource.com
  • Production in India
    : api.in.cybersource.com
  • Test:
    apitest.cybersource.com
searchID
The ID returned in the search request response.

Responses

This call can return one of the following HTTP status codes:
  • 200
    : Successful response.
  • 404
    : The specified resource is not found in the system.
  • 500
    : Unexpected server error.
For detailed information on the responses, including which fields are returned, see the Transaction Search REST API Reference.