- Integration Guidelines
- Retrieve Transactions (Universal)
Retrieve Transactions (Universal)
The Retrieve Transactions operation allows you to retrieve transaction details of all of your merchants, facilitating reporting and other business requirements. Available from version 57 of the API, the Retrieve Transactions operation offers the following benefits:
- Merchant version neutrality: Transaction data are represented in a format independent of the API version used by the merchant when they submitted the transaction. Merchant transactions can be accessed in the same way, regardless of the API version used by the merchant when they submitted the transaction. For more information, see Merchant Version Neutrality.
- Performance: A high performance API offering quick data export where transactions can be downloaded in bulk for up to a 13-month period.
- Flexibility: Allows transaction search by creation date, and optionally by updated date or the existence of particular fields.
- Pagination: Results are grouped into pages of transactions for manageable download sizes, and subsequent pages can be requested with a simple
iteratorreturned as part of the previous page's HTTP header. - Efficiency: Transactions contain only the fields that are relevant to that particular record, which reduces the size of the report and allows for filtering of transactions based on select fields and their existence. For example, if the transaction was not risk assessed, the
transactionRiskAssessmentResultfield is not included in the response. Additionally, the API supports itemized fields when provided on the transaction such as line item details. - Data integrity: Data integrity checking in the form of content length and the MD5 checksum in the HTTP response header provides reliability with the ability to verify the response.
- Customized Response: Supports field selection where you can specify the fields to be returned in the response. This useful if you want to exclude sensitive data, for example, PII data fields such as account identifier, payer name, payer email, etc.
Merchant Version Neutrality
This operation uses a data model where transaction details are returned in fields that are independent of the API version used to process the transaction. This is beneficial when you retrieve and view transaction history of merchants who processed their transaction using different API versions.
The Spring by Citi Payment Gateway's Reporting API stores transaction details in fields that are specific to the API version that was used to process the transaction. However, a particular field might be named differently across multiple API versions but store the same underlying information. If you work with many merchants, this can make analyzing and processing transactions difficult for reporting purposes.
For example, suppose that you want to view the details of two transactions using the Reporting API. A merchant processed transaction 1 in API version 10, and transaction 2 in API version 48. In transaction 1, the card number details were stored in the card.number field, while the card number details for transaction 2 were stored in the sourceOfFunds.provided.card.number field.
As the following table shows, the same transaction data is represented by two different fields because the transactions were processed using different API versions.
| Transaction | card.number |
sourceOfFunds.provided.card.number |
|---|---|---|
| Transaction 1 | 5123450000000008 | <blank> |
| Transaction 2 | <blank> | 5123450000000008 |
When retrieving details of the same two transactions using the Retrieve Transactions operation, the card details of both transactions are represented by the same transactionAccountIdentifier field, as shown in the following table. This is regardless of the API version the merchant used to process the transaction.
| Transaction | transactionAccountIdentifier |
|---|---|
| Transaction 1 | 5123450000000008 |
| Transaction 2 | 5123450000000008 |
The version-neutral representation of transaction details are easy to read, analyze, and process when retrieving a large number of transactions across many merchants.
Prerequisites
To use the Retrieve Transactions API via the gateway:
- You must be enabled for the Reporting API privilege, and
- You must create your Reporting API credentials to authenticate to the gateway. For more information, see the Secure Your Integration documentation.
Create Retrieve Transactions Request
The Retrieve Transactions request returns transactions that were created in the Spring by Citi Payment Gateway within a defined date range. Use the predicate query parameter to define any additional conditions and filter the number of returned transactions to only those that meet your conditions. You must include the predicate query parameter in the URL of the initial request.
In addition to the response returning transactions that were created in a defined date range, you can further filter the returned transactions to the following scenarios:
- Transactions that were created and also updated between a defined date range. You must specify a start and end date, and time for both the transaction creation and update.
- Transactions that were created between a defined date range and contain a valid Retrieve Transactions response field. You must specify a start and end date, and time for the transaction creation, and specify the field that must exist in each transaction.
- Transactions that were created and updated between a defined date range and contain a valid Retrieve Transactions response field. You must specify a start and end date, and time for both the transaction creation and update, and specify the field.
When retrieving transactions using the predicate parameter, note the following:
- The end date and time must be at least one hour in the past from the date and time of when you submit the request. This applies to the end date and time for transactions created and transactions updated.
- The specified date range of transactions created cannot be more than 397 days (13 months). For example, if you want to retrieve orders that were created with a start date of October 01, 2019, then the latest end date you can specify is November 02, 2020 (2020 being a leap year).
Query Parameters and Fields
The following table describes the supported query parameters for the Retrieve Transactions URL and the fields supported for each query parameter.
| Query Parameter | Supported Field | Existence | Type | Description |
|---|---|---|---|---|
predicate |
Required with all initial requests | JSON | Defines the conditions to limit the number of transactions that are returned to only those that meet these conditions. Every initial request must contain the predicate query parameter in the URL, and the value must be URL encoded. However, to retrieve the next page of orders that are not returned in the initial response, the predicate parameter is replaced with the iterator parameter and its value. |
|
transactionTimeOfRecord |
Required with all initial requests | JSON | Indicates the date and time the transaction was created and is used to specify a date range to retrieve transactions that were created within that time frame. You must use this field in the initial request to submit the start and end date and time. Must be UTC time in ISO 8601 format, yyyy-mm-ddThh:mm:ssZ | |
transactionLastUpdatedDate |
Optional | JSON | Indicates the date and time the transaction was last updated. It is used to filter the retrieved transactions that were created within a defined date range specified in the transactionTimeOfRecord field AND were updated within the defined date range specified in this field. You must use this field to submit both a start date and time and an end date and time. Must be UTC time in ISO format, yyyy-mm-ddThh:mm:ssZ |
|
exists |
Optional | JSON | Specifies a field that must exist in each returned transaction, providing further filtering capability. The specified field must be a valid response field. See Retrieve Transactions response fields for a complete list of available fields. Note that you can only have one exists condition in the predicate parameter with each request. |
|
iterator |
N/A | Required to retrieve the next page of orders | String | Retrieves the next page of transactions that were not returned in the initial response. In a response where all transactions are not returned, the Iterator and its value are returned in the HTTP header of the response. You must then submit request(s) using the iterator parameter and the Iterator value from the previous response until the response does not contain an iterator. |
fields |
N/A | Optional Used to limit the fields returned in the response |
Array | Specifies the fields that must be returned in the response for each transaction, providing further filtering capability. The specified fields must be valid response fields else the gateway returns an error. See Retrieve Transactions response fields for a complete list of available fields. The format of the field must exactly match the Retrieve Transactions response field name — simply copy and paste. See Example Request 3.
If you specify this parameter in the initial request, you must also include it in subsequent requests, if any, to limit the fields returned in the response in the next page of transactions. |
Here's an example of a basic Retrieve Transactions request using the predicate query parameter returning transactions that were created in a defined date range. Submit the following request and specify the start and end date and time.
/GET https://na.gateway.spring.citi.com/api/rest/version/58/mso/{msoId}/transaction?predicate={
"and": [
{
">=": [
{
"field": "transactionTimeOfRecord"
},
"2020-05-31T00:00:00.001Z"
]
},
{
"<": [
{
"field": "transactionTimeOfRecord"
},
"2020-06-30T00:00:00.000Z"
]
}
]
}
Retrieve Transactions Response
For a successful Retrieve Transactions request, the response will contain a list of transactions that match the criteria defined in the predicate query parameter. The response will be empty if there are no transactions that meet the conditions that were defined in the predicate query parameter.
The response contains the following details:
- The transaction details represented in a format independent of the API version
- The complete Retrieve Transaction response as returned to the merchant when retrieving the transaction details using the merchant Retrieve Transaction operation.
The response is returned in the following format:
{"<field 1 for transaction 1>”:”value11”, “<field2 for transaction 1>”:”value21”,…..}\n
{“<field 1 for transaction 2>”:”value12”, “<field2 for transaction 2>”:”value22”,…..}\n
A key advantage of using the Retrieve Transactions operation is that it uses JSON syntax for both the request and the response. This is useful because you can automate the parsing and processing of the JSON information by other applications to suit your requirements.
Each transaction returned in the response will only include a particular field and its value if they are contained in the transaction's details. For example, if a transaction was not risk assessed, the transactionRiskAssessmentResult field and its value is not included in the response. However, all transactions returned in the response will include the following fields:
merchantIdorderIdtransactionIdtransactionTimeOfRecordtransactionType
The following example shows a response to a request that was submitted with the predicate query parameter. Additional spaces and newline characters have been added for the sake of clarity and readability.
{
"acquirerId":"TEST_ACQUIRER_S2I",
"acquirerMerchantId":"123456",
"acquirerResponseCode":"800",
"acquirerTerminalId":"60801",
"dataModel":"WEB_SERVICE",
"gatewayResponseCode":"APPROVED",
"merchantId":"TEST_MERCHANT",
"merchantTransactionSource":"INTERNET",
"orderId":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"retrieveTransactionApiResponse":{
"authorizationResponse":{
"posData":"1009S0100000",
"transactionIdentifier":"123456789012345"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_MERCHANT",
"order":{
"amount":1000.0,
"creationTime":"2020-05-31T13:56:16.790Z",
"currency":"USD",
"id":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"status":"CAPTURED",
"totalAuthorizedAmount":1000.0,
"totalCapturedAmount":1000.0,
"totalRefundedAmount":0.0
},
"response":{
"acquirerCode":"800",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"TEST_GLOBAL_ISSUER",
"number":"512345xxxxxx0008",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfRecord":"2020-05-31T13:56:16.836Z",
"transaction":{
"acquirer":{
"id":"TEST_ACQUIRER_S2I",
"merchantId":"123456"
},
"amount":1000.0,
"currency":"USD",
"frequency":"SINGLE",
"id":"1",
"receipt":"200531103583",
"source":"INTERNET",
"terminal":"60801",
"type":"AUTHORIZATION"
},
"version":"42"
},
"rrn":"200531103583",
"transactionAccountIdentifier":"512345xxxxxx0008",
"transactionAccountIdentifierEntryPoint":"SERVER_API",
"transactionAccountIdentifierPresentation":"UNKNOWN",
"transactionAmount":"USD 1000.00",
"transactionCardExpiryDate":"1/39",
"transactionCardFundingMethod":"CREDIT",
"transactionFrequency":"SINGLE",
"transactionId":"1",
"transactionLastUpdatedDate":"2020-05-31T13:56:17.222Z",
"transactionPaymentMethod":[
"MASTERCARD"
],
"transactionTimeOfRecord":"2020-05-31T13:56:16.836Z",
"transactionType":"AUTHORIZATION"
}\n
{
"acquirerId":"TEST_ACQUIRER_S2I",
"acquirerMerchantId":"123456",
"acquirerTerminalId":"60801",
"dataModel":"WEB_SERVICE",
"gatewayResponseCode":"APPROVED",
"merchantId":"TEST_MERCHANT",
"merchantTransactionSource":"INTERNET",
"orderId":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"retrieveTransactionApiResponse":{
"authorizationResponse":{
"posData":"1009S0100000",
"transactionIdentifier":"123456789012345"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_MERCHANT",
"order":{
"amount":1000.0,
"creationTime":"2020-05-31T13:56:16.790Z",
"currency":"USD",
"id":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"status":"CAPTURED",
"totalAuthorizedAmount":1000.0,
"totalCapturedAmount":1000.0,
"totalRefundedAmount":0.0
},
"response":{
"acquirerCode":"",
"acquirerMessage":"",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"TEST_GLOBAL_ISSUER",
"number":"512345xxxxxx0008",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfRecord":"2020-05-31T13:56:17.070Z",
"transaction":{
"acquirer":{
"id":"TEST_ACQUIRER_S2I",
"merchantId":"123456"
},
"amount":1000.0,
"currency":"USD",
"frequency":"SINGLE",
"id":"2",
"receipt":"20053194184",
"source":"INTERNET",
"terminal":"60801",
"type":"CAPTURE"
},
"version":"42"
}
"rrn":"20053194184",
"transactionAccountIdentifier":"512345xxxxxx0008",
"transactionAccountIdentifierEntryPoint":"SERVER_API",
"transactionAccountIdentifierPresentation":"UNKNOWN",
"transactionAmount":"USD 1000.00",
"transactionCardExpiryDate":"1/39",
"transactionCardFundingMethod":"CREDIT",
"transactionFrequency":"SINGLE",
"transactionId":"2",
"transactionLastUpdatedDate":"2020-05-31T13:56:17.222Z",
"transactionPaymentMethod":[
"MASTERCARD"
],
"transactionTimeOfRecord":"2020-05-31T13:56:17.070Z",
"transactionType":"CAPTURE"
}
Retrieve the Next Page of Transactions
If a large number of transactions meet the defined conditions, the initial response to a Retrieve Transactions request will not return all transactions. Instead, the Spring by Citi Payment Gateway delivers the transactions in multiple responses. When there are more transactions than what is returned in the previous response, the API response contains the Iterator and its value in the HTTP header, as shown in the example. Note that the content length and the MD5 checksum are also included in the HTTP header.
Iterator:7YpYUTXjUDYh0Z1ZvNkEISpAdIUdghxlU1OlXhdYPTJUW_-GxoZFQm75ZzP6l5P_EjEurlQ5-gTuguW2XuHBMQ Content-MD5:xxPU5bkg1699Gh9btoAmEg== Content-Length:1323345
Iterator returned in the HTTP header is unique for each response.To retrieve the next page of transactions, submit additional requests with the iterator parameter and set its value to the Iterator value returned in the HTTP header of the previous response. The following example shows the syntax of a request using the iterator parameter in the URL.
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/transactionReport
Body:
{
"iterator": "7YpYUTXjUDYh0Z1ZvNkEISpAdIUdghxlU1OlXhdYPTJUW_-GxoZFQm75ZzP6l5P_EjEurlQ5-gTuguW2XuHBMQ"
}
Note that the Iterator value that you submit in each subsequent request will be unique.
Iterator and its value in the HTTP header. This lets you know that there are no more transactions to return.Continue to submit additional requests using the iterator parameter, setting its value to the Iterator value returned in the HTTP header of the previous response until the Iterator and its value are not returned in the HTTP header.
predicate and iterator parameters. The request must contain either the predicate parameter, or the iterator, but not both.Additonal Examples
This section contains examples with advanced conditions required for additional filtering, and shows the fields that must be provided in the predicate and fields query parameters.
Example Request 1
This example shows how to retrieve transactions that were created in a defined date range (October 1, 2019–November 01, 2020) AND were updated between a defined date range (December 5, 2019–January 5, 2020).
GET https://na.gateway.spring.citi.com/api/rest/version/58/mso/{msoId}/transaction?predicate={
"and": [
{
">=": [
{
"field": "transactionTimeOfRecord"
},
"2019-10-01T00:00:00.001Z"
]
},
{
"<": [
{
"field": "transactionTimeOfRecord"
},
"2020-11-01T00:00:00.000Z"
]
},
{
">=": [
{
"field": "transactionLastUpdatedDate"
},
"2019-12-05T00:00:00.001Z"
]
},
{
"<": [
{
"field": "transactionLastUpdatedDate"
},
"2020-01-05T00:00:00.000Z"
]
}
]
}
Example Request 2
This example shows how to retrieve transactions that were created in a defined date range (October 1, 2019–November 01, 2020) AND contain a particular field (transactionRiskAssessmentResult field).
GET https://na.gateway.spring.citi.com/api/rest/version/58/mso/{msoId}/transaction?predicate={
"and": [
{
">=": [
{
"field": "transactionTimeOfRecord"
},
"2019-10-01T00:00:00.001Z"
]
},
{
"<": [
{
"field": "transactionTimeOfRecord"
},
"2020-11-01T00:00:00.000Z"
]
},
{
"exists": {
"field": "transactionRiskAssessmentResult"
}
}
]
}
Example Request 3
This example shows how to retrieve orders that were created in a defined date range (October 1, 2019–November 01, 2020) AND contain a particular field (riskAssessmentResult field) AND where the response only contains a specific set of fields.
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/transactionReport
Body:
{
"predicate": {
"and": [
{"GTE":["transactionTimeOfRecord","2020-10-01T00:00:00.000Z"]},
{"LT":["transactionTimeOfRecord","2021-11-02T00:00:00.000Z"]},
{"exists": {"field": "transactionRiskAssessmentResult"}}
]
},
"fields": ["transactionId", "transactionAmount", "transactionItem[n].brand", "retrieveTransactionApiResponse.order.notificationUrl"]
}