- Integration Guidelines
- Implementing a Reporting Integration
- Transaction Reports
Transaction Reports
Reporting integration allows you to download transaction record data in a formatted report from the American Express PSP.
You submit a password-authenticated request to the payment gateway for a report that shows details of all Web-Services API transactions created or updated within a time period you specify. You can specify the fields to populate the report, and the column headers in the output. The report is returned in csv format.
You can download and store your transaction data in CSV format for analysis. For example, the data can be analyzed by a business intelligence or a spreadsheet application.
Reporting requires an Ordered Read request that follows the standard format for a http GET.
The format is defined as follows:
GET /history/version/<version>/mso/<msoid>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>
Where:
- <version> is the Reporting API version number (the version is '1').
- <msoid> is the MSO ID in Merchant Manager.
- <starttime> and <endtime> indicate the time period to cover.
- <columns> are the fields to include in the report, separated by commas. The names are case sensitive.
- <columnheaders> is the list of column headers to include in the report, separated by commas.
order.item[n].detail.An example of a request is:
https://gateway-japa.americanexpress.com/history/version/1/mso/TEST/transaction?timeOfRecord.start=2012-04-01T00:00:00Z&timeOfRecord.end=2012-04-01T09:00:00Z&columns=order.id,transaction.reference,transaction.currency,transaction.amount&columnHeaders=Order,Reference,Currency,Amount
The start time is inclusive (transaction time >= start time) and the end time is exclusive (transaction time < end time). The start and end times are passed as parameters in ISO 8601 format:
yyyy-mm-ddThh:mm:ssZ
where Z indicates that the time is UTC. If the time is not UTC, a timezone offset must be specified as +/-hh[:mm], for example, 12:31+10 (UTC + 10 hours), or 12:31:30-06:30 (UTC minus 6 hours 30 minutes). Time values that appear in the report (if any) are in UTC.
The first instant of a day occurs at time 00:00. The end time of the report (timeOfRecord.end) is exclusive, so to report up to the end of a day, use the first instant of the next day (00:00) as the end time. Similarly, if you want hourly data, specify a window as the start of one hour and the start of the next.
Time zone and time format
You can specify two optional parameters in the request:
- csv.timeZone=<+ or ->HH:MM
If specified, the time of records is output in the indicated time zone and without a time zone indicator. For example, if you set 'csv.timeZone=+10:00', times of events appear in the report as UTC+10 hours.
If omitted, the output is UTC with a 'Z' appended to indicate UTC time zone.
- csv.timeFormat=<iso8601 or iso8601-T>
If specified as iso8601-T, the output uses a space instead of a T as the date-time separator.
If omitted, or specified as iso8601, the date-time separator is 'T'.
We recommend that you ignore daylight saving for report downloads. However, if you want report downloads to be windowed by daylight saving times, you need to manage that by:
- modifying the time zone that you specify
- accounting for the fact that you will lose one hour of records at the start of daylight saving, and will get one hour of duplicate records at the end of daylight saving.
To avoid daylight savings complications, use the UTC timezone to specify your time window.
The columns parameter specifies the fields that appear in the report. The fields that can be specified are described in the Retrieve Transaction operation for the version of Web-Services API that you support. Note that the Reporting API version is distinct from the Web-Services API version.
If you perform transactions using multiple API versions, you can specify fields either common to versions or unique to a particular version. Data that does not exist for a particular record will show as an empty value in the CSV. However, any field name must be valid for at least one API version.
Column headers
If you supply your own column headers in the columnHeaders parameter, the list of names corresponds to the list of fields in the 'columns' list. Both &columnHeaders and &columns must have the same number of members.
If there are no headers included in the request (&columnHeaders is omitted), the column headers will be the field names. If an empty header parameter is passed (&columnHeaders=) the output file will not contain any header rows.
Reporting records all events associated with a transaction. When you request a transaction report, all events related to the original transaction within the period you specify are inserted in the report, including any update events that were performed on the transaction. This mechanism enables easy access to all the transaction events and also the flexibility to filter data as per your business requirements.
The image below illustrates the reporting mechanism for transaction data.
Based on the illustration above, a transaction report requested for the period '1-Feb-2012' to '29-Feb-2012' returns Event 1 and Event 2, which are associated with the same transaction.
Records in a transaction report are ordered from oldest transaction to most recent.