- Integration Guidelines
- Retrieve Orders (Universal)
Retrieve Orders (Universal)
The Retrieve Orders operation allows you to retrieve order details of all of your merchants, facilitating reporting and other business requirements. The retrieved order details include all of the transactions that comprise the order and the raw API response for that order. Available from version 57 of the API, the Retrieve Orders operation offers the following benefits:
- Merchant version neutrality: Order and transaction data are represented in a format independent of the API version used by the merchant when they submitted the transaction. Merchant orders and 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 orders and transactions can be downloaded in bulk for up to a 13-month period.
- Flexibility: Allows order search by creation date, and optionally by updated date or the existence of particular fields.
- Pagination: Results are grouped into pages of orders for manageable download sizes, and subsequent pages can be requested with a simple
iteratorreturned as part of the previous page's HTTP header. - Efficiency: Orders and transactions contain only the fields that are relevant to that particular record, which reduces the size of the report and allows for filtering of orders based on select fields and their existence. For example, if an order was not risk assessed, the
riskAssessmentResultfield 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.
- Transaction Filtering: Allows filtering transactions that are returned in the response for each order.
- 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 order and transaction details are returned in fields that are independent of the API version used to process the order. This is beneficial when you retrieve and view the order history of merchants who processed their orders using different API versions.
The Spring by Citi Payment Gateway's Reporting API stores order details in fields that are specific to the API version that was used to process the order. 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 orders difficult for reporting purposes.
For example, suppose that you want to view the details of two orders using the Reporting API. A merchant processed order 1 in API version 10, and order 2 in API version 48. In order 1, the card number details were stored in the card.number field, while the card number details for order 2 were stored in the sourceOfFunds.provided.card.number field.
As the following table shows, the same order data is represented by two different fields because the orders were processed using different API versions.
| Order | card.number |
sourceOfFunds.provided.card.number |
|---|---|---|
| Order 1 | 5123450000000008 | <blank> |
| Order 2 | <blank> | 5123450000000008 |
When retrieving details of the same two orders using the Retrieve Orders operation, the card details of both orders are represented by the same accountIdentifier field, as shown in the following table. This is regardless of the API version the merchant used to process the order.
| Order | accountIdentifier |
|---|---|
| Order 1 | 5123450000000008 |
| Order 2 | 5123450000000008 |
The version-neutral representation of the order details is easy to read, analyze, and process when retrieving a large number of orders across many merchants.
Note that an order is always identified by the most recently used account identifier when there are multiple initial transactions submitted for the same order. For example, suppose that a payer attempted to pay with their credit card, but the transaction failed, and they subsequently paid with their PayPal account. The card number for the failed transaction is stored in the sourceOfFunds.provided.card.number field, and the PayPal account ID for the subsequent transaction is stored in the sourceOfFunds.provided.paypal.accountEmail field, as shown in the following table.
| Order | Transaction | sourceOfFunds.provided.card.number |
sourceOfFunds.provided.paypal.accountEmail
|
|---|---|---|---|
| Order 1 | Transaction 1 | 5123450000000008 | <blank> |
| Transaction 2 | <blank> | john.smith@test.com |
When retrieving this order's details using the Retrieve Orders operation, the account identifier of the last successful transaction is represented by the accountIdentifier field. The account identifiers of the individual transactions are represented by the transactionAccountIdentifier field, as shown in the following table.
| Order | accountIdentifier |
Transaction | transactionAccountIdentifier |
|---|---|---|---|
| Order 1 | john.smith@test.com | Transaction 1 | 5123450000000008 |
| Transaction 2 | john.smith@test.com |
Prerequisites
To use the Retrieve Orders 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 Orders Request
The Retrieve Orders request returns orders 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 orders to only those that meet the specified conditions. You must include the predicate query parameter in the URL of the initial request.
In addition to the response returning orders that were created in a defined date range, you can further filter the returned orders to the following scenarios:
- Orders that were created and also updated between a defined date range. You must specify a start and end date, and time for both the order creation and order update.
- Orders that were created between a defined date range and contain a valid Retrieve Orders response field. You must specify a start and end date, and time for the order creation, and specify the field that must exist in each order.
- Orders that were created and updated between a defined date range and contain a valid Retrieve Orders response field. You must specify a start and end date, and time for both the order creation and order update, and specify the field.
When retrieving orders 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 both the order creation and order update.
- the specified date range of the orders 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 Orders 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 orders 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. |
|
orderCreationDate |
Required with all initial requests | JSON | Indicates the date and time the order was created and is used to specify a date range to retrieve orders 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 | |
orderLastUpdatedDate |
Optional | JSON | Indicates the date and time the order was last updated. It is used to filter the retrieved orders that were created within a defined date range specified in the orderCreationDate 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 order, providing further filtering capability. The specified field must be a valid response field. See Retrieve Orders 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 orders that were not returned in the initial response. In a response where all orders 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. |
transactionPredicate |
Optional Used to limit the transactions included in the response. |
JSON | Defines the conditions to limit the number of transactions that are returned for each order to only those that meet these conditions. | |
transactionLastUpdatedDate |
Optional | JSON | Indicates the date and time the transaction was last updated in the gateway. It is used to filter the retrieved transactions for each order. Must be UTC time in ISO format, yyyy-mm-ddThh:mm:ssZ | |
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 order, providing further filtering capability. The specified fields must be valid response fields else the gateway returns an error. See Retrieve Orders response fields for a complete list of available fields. The format of the field must exactly match the Retrieve Orders response field name — simply copy and paste. See Example Request 4.
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 orders. |
Here's an example of a basic Retrieve Orders request using the predicate query parameter returning orders 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}/order?predicate={
"and": [
{
">=": [
{
"field": "orderCreationDate"
},
"2020-05-31T13:56:16.790Z"
]
},
{
"<": [
{
"field": "orderCreationDate"
},
"2020-06-30T13:56:16.790Z"
]
}
]
}
Retrieve Orders Response
For a successful Retrieve Orders request, the response will contain a list of orders that match the criteria defined in the predicate query parameter. The response will be empty if there are no orders that meet the conditions that were defined in the predicate query parameter.
The response contains the following details:
- the order details represented in a format independent of the API version
- the details for all transactions for the order that are represented in a format independent of the API version, and
- the complete Retrieve Order response as returned to the merchant when retrieving the order details using the merchant's Retrieve Order operation
The response is in ndjson format. Each entry is separated from the next by a line break (\n).
Where no order(s) match the criteria defined in the predicate the response will be empty.
The response is returned in the following format:
{"<field 1 for order 1>":"value11", "<field2 for order 1>":"value21",…..}\n
{"<field 1 for order 2>":"value12", "<field2 for order 2>":"value22",…..}\n
All transactions for each order are also returned in the response in the following format:
{
transaction: [
{"<field 1 for transaction 1>":"value111", "<field2 for transaction 1>":"value211",…..},
{"<field 1 for transaction 2>":"value112", "<field2 for transaction 2>":"value221",…..},
...
]
}
A key advantage of using the Retrieve Orders 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 order that is returned in the response will only include a particular field and its value if they are contained in the order's details. For example, if a order was not risk assessed, the riskAssessmentResult field and its value is not included in the response. However, all orders returned in the response will include the following fields:
merchantIdorderIdorderAmountorderCreationDateorderLastUpdatedDate
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.
{
"accountIdentifierEntryPoint":"SERVER_API",
"accountIdentifierPresentation":"UNKNOWN",
"cardExpiryDate":"1/39",
"cardFundingMethod":"CREDIT",
"merchantId":"TEST_MERCHANT",
"orderAmount":"USD 1000.00",
"orderCreationDate":"2020-05-31T13:56:16.790Z",
"orderId":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"orderLastUpdatedDate":"2020-05-31T13:56:17.222Z",
"orderOutstandingAuthorizationAmount":"USD 0.00",
"orderStatus":"CAPTURED",
"orderTotalAuthorizedAmount":"USD 1000.00",
"orderTotalCapturedAmount":"USD 1000.00",
"orderTotalRefundedAmount":"USD 0.00",
"retrieveOrderApiResponse":{
"amount":1000.0,
"creationTime":"2020-05-31T13:56:16.790Z",
"currency":"USD",
"id":"bbf72a48-e027-49df-a9f4-d24e4e6cd50d",
"merchant":"TEST_MERCHANT",
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"TEST_GLOBAL_ISSUER",
"number":"512345xxxxxx0008",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"status":"CAPTURED",
"totalAuthorizedAmount":1000.0,
"totalCapturedAmount":1000.0,
"totalRefundedAmount":0.0,
"transaction":[
{
"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"
},
{
"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"
}
]
},
"transaction":[
{
"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",
"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":[
"MASTRCARD"
],
"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",
"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 Orders
If a large number of orders meet the defined conditions, the initial response to a Retrieve Orders request will not return all orders. Instead,
the Spring by Citi Payment Gateway delivers the orders in multiple responses. When there are more orders 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 orders, submit subsequent 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.
https://na.gateway.spring.citi.com/api/rest/version/58/mso/{msoId}/order?iterator=<value_from_Iterator_parameter>
Note that the Iterator value that you submit in each subsequent request will be unique.
Iterator and its value in the HTTP header, which indicates that all orders have been returned. Continue to submit additional requests using the iterator parameter 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.Additional Examples
This section contains examples with advanced conditions required for additional filtering, and shows the fields that must be provided in the predicate, transactionPredicate, and fields query parameters.
Example Request 1
This example shows how to retrieve orders 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).
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/orderReport
Body:
{
"predicate": {
"and": [
{"GTE":["orderCreationDate","2020-10-01T00:00:00.000Z"]},
{"LT":["orderCreationDate","2021-11-02T00:00:00.000Z"]},
{"GTE":["orderLastUpdatedDate","2020-12-05T00:00:00.000Z"]},
{"LT":["orderLastUpdatedDate","2021-01-06T00:00:00.000Z"]}
]
}
}
Example Request 2
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).
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/orderReport
Body:
{
"predicate": {
"and": [
{"GTE":["orderCreationDate","2020-10-01T00:00:00.000Z"]},
{"LT":["orderCreationDate","2021-11-02T00:00:00.000Z"]},
{"exists": {"field": "riskAssessmentResult"}}
]
}
}
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 contain a limited set of transactions for each order (only transactions last updated on December 5, 2020).
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/orderReport
Body:
{
"predicate": {
"and": [
{"GTE":["orderCreationDate","2020-10-01T00:00:00.000Z"]},
{"LT":["orderCreationDate","2021-11-02T00:00:00.000Z"]},
{"exists": {"field": "riskAssessmentResult"}}
]
},
"transactionPredicate":{
"and":[
{"GTE":["transactionLastUpdatedDate","2021-01-05T00:00:00.000Z"]},
{"LT":["transactionLastUpdatedDate","2021-01-06T00:00:00.000Z"]}
]
}
}
Example Request 4
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 contain a limited set of transactions for each order (only transactions last updated on December 5, 2020) AND where the response only contains a specific set of fields.
POST https://na.gateway.spring.citi.com/api/rest/version/64/mso/{msoId}/orderReport
Body:
{
"predicate": {
"and": [
{"GTE":["orderCreationDate","2020-10-01T00:00:00.000Z"]},
{"LT":["orderCreationDate","2021-11-02T00:00:00.000Z"]},
{"exists": {"field": "riskAssessmentResult"}}
]
},
"transactionPredicate":{
"and":[
{"GTE":["transactionLastUpdatedDate","2021-01-05T00:00:00.000Z"]},
{"LT":["transactionLastUpdatedDate","2021-01-06T00:00:00.000Z"]}
]
},
"fields": ["orderId", "orderAmount", "accountHolder", "accountIdentifier", "transaction[n].transactionId", "transaction[n].transactionAmount", "transaction[n].transactionItem[n].brand", "retrieveOrderApiResponse.notificationUrl"]
}