Event Reports
Event reports can facilitate an MSO's invoicing of merchants for services provided, and allow usage analysis of the gateway. Event records are generated for:
- Gateway usage by a merchant (such as normal order and transaction processing through API, Merchant Administration, Hosted Batch, or report downloads).
- Activation or deactivation of services in a merchant's configuration by an MSO.
- Creation or change to a merchant's details by a merchant (for example, phone number or address).
- Acceptance or rejection of the Terms and Conditions by a merchant.
An example of a usage event would be a payment authorization, or the tokenization of a credit card number. An activation event might be enabling payment plans for a merchant.
An events report request is a formatted HTTPS GET request. The format is defined as follows:
GET /reporting/version/<version>/mso/<msoid>/event?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>
Where:
- <version> is the Reporting API version number (the version is '1').
- <msoid> is the MSO ID.
- <starttime> and <endtime> indicate the time period to cover.
To make sure all related events that are part of the same event record have been collected and will appear in the report, you must not set an end time that is later than five minutes before the present time.
There are two optional parameters you can specify for event reports:
- 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'.
The start time is inclusive (event time >= timeOfRecord.start) and the end time is exclusive (event time < timeOfRecord.end). The start and end times are passed as parameters in ISO 8601 format:
yyyy-mm-ddThh:mm:ss(Z|HH:MM)
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 the time period to be from the start of one hour to the start of the next.
Each line in the returned report represents one event record with a defined structure. The structure is designed so you can use the formatted information as input for your own billing system or analysis tool.
One interaction with the gateway by a merchant can produce multiple event records. For example, say a payer visits a merchant's online shop and purchases something. This interaction might involve the following events:
This one process flow will result in the creation of six event data records. See the truncated example of an event record below.
| EDR ID | Type | Service | Operation | Source |
|---|---|---|---|---|
| CAfy8Q9wWPaYOBa0CF9E | USAGE | TOKEN | TOKENIZE | WEB_SERVICES_API |
| CAfy8Q9wWPaYOBa0CF5F | USAGE | PAYMENT | AUTHORIZE | WEB_SERVICES_API |
| CAfy8Q9wWPaYOBa0CF9C | USAGE | VERIFICATION | VERIFY | AUTO |
| CAfy8Q9wWPaYOBa0CF9C | USAGE | RISK | ASSESS_RISK | WEB_SERVICES_API |
| CAfy8Q9wWPaYOBa0CF8E | USAGE | RISK | REJECT | NOTIFICATION |
| CAfy8Q9wWPaYOBa0CF8E | USAGE | PAYMENT | VOID | RISK_AUTO |
To tell which records are tied to the same action, each record is prefaced with an identifier column (EDR ID). If a record has the same identifier as another record, they were both involved in the same payment gateway interaction.
Separating the data into fine-grained, individual usage or activation events that can be grouped allows you to utilize the event data to suit your own requirements.
The Type, Service, Operation, and Source fields describe the type of operation performed, and whether it was performed by the merchant, the payer, or the payment gateway. These fields are significant fields for deciding on which operations are chargeable (for example).
The fields that are displayed in an Event report are:
| Field | Description |
|---|---|
| Checksum | Check for integrity of event record. An algorithm can be used to |
| EDR ID | Identifier for an event record. Groups operations associated with a user interaction. |
| Time of Record | Indicates the time that the service was used. The time appears in UTC, or is user-specified using the csv.timeZone and csv.timeFormat parameters. |
| MSO | MSO ID |
| Merchant | Merchant ID |
| Type | Type of event record:Usage;Activate;Deactivate;Demographic |
| Service | Gateway service being delivered (for example, the Risk Service if risk assessment is part of the gateway interaction, or the Tokenization service if a payer's card is being tokenized or queried). |
| Service ID | Instance of the service being delivered, if applicable (for example, Verified by Visa or SafeKey are instances of the 3DS Service). |
| Operation | The operation performed by the service (for example, an assessment of a transaction is the operation performed by a Risk Service |
| Source | Origin of the operation (for example, API, or Merchant Manager). |
| Value | Enumerated value of the service requested, if applicable. (For example, if the event record is the activation of Risk, a value could be 'bronze' or 'silver'.) |
| Amount | Amount for the requested service, if applicable. This does not necessarily mean a currency amount (for example, a batch upload event is measured by the number of operations requested). |
| Unit | Units for the amount. |
| Acquirer | Identifier for the acquirer processing the operation |
| Result | Success or failure of the operation according to the gateway. This is not the same as the business result. Success indicates that the gateway and external systems processed the request as per specification (even if the outcome was a declined transaction).
|
| Link | Identifier of the persistent gateway record. If an event links to more than one record, they are separated by colons, for example, orderID:transactionID. |
Use the information in the event report, broken down by type and source, for your own gateway usage analysis or billing requirements.
Using Hosted Payment Form as an example:
- If a merchant uses Hosted Payment Form to perform an authorization, you could decide not to charge this instance of payment form usage, but instead bundle the cost into the authorization charge.
- However, if the payer used Hosted Payment Form for a token inquiry, you could charge the payment form usage.
- Contact Mastercard Gateway for complete details on the contents and format of Web Services reports and how they could be used for your analysis and billing requirements.
Event records in the report are grouped by EDR ID and then by service.
The integrity of billing data is important, as a simple corruption in a file can result in customers being overcharged. Billing data is protected from corruption within the gateway, but downloading billing data to your system and processing it introduces possible avenues for corruption.
To counter this, the gateway adds data to each billing record that lets you detect errors — the CRC field. You can use an algorithm to verify the CRC field and the validity of the record.
The algorithm is:
- Take the record: exclude the CRC field and the first comma, but include a terminating newline.
- Convert the record to bytes using UTF-8 encoding.
- Calculate the CRC32 using the algorithm described in http://www.ece.cmu.edu/~koopman/networks/dsn02/dsn02_koopman.pdf
- Express the result in hexadecimal, zero padded to length 8.
- If the CRC that you calculate is identical to the CRC shown in the record, there is negligible probability that the record is corrupted.
- As CRC32 is widely used (ZIP, MPG, Ethernet etc), there are many off-the-shelf implementations in many languages available for use.