- 集成指南
- 支持的功能 (Reporting)
- Reporting
Reporting
Reporting 让您可以通 Reporting API 下载交易。
- 报告显示指定时间段内创建或更新的交易的详细信息。 您可以指定填充报告的字段以及输出的列标头。
- 您可以使用 CSV 格式下载和存储交易数据来进行分析。 例如，可以使用商业智能或电子表格应用程序分析数据。
您可以通过三种方式获得订单和交易报告：
- 使用 Reporting API 集成下载报告
- 使用 Web 浏览器下载报告
- 使用门户下载报告
您可以使用逗号分隔值 (CSV) 格式下载包含在商家管理门户中的搜索结果列表中的交易。
先决条件
- 必须为 Reporting 服务启用 Mastercard Gateway 上的商家配置文件。
- 您必须生成密码才能访问 Reporting API。 请参见为 Reporting 生成密码。
报告中的交易数据
Reporting 记录所有与交易相关的事件。 在您请求交易报告时，所有与指定期间内的指定交易相关的事件都将被插入到报告中。 包括所有与该交易相关的更新事件。 您还可以灵活地根据您的业务需求筛选数据。
- 付款人身份验证
- Authorization/Pay
下图说明了报告机制。 请求的期间“1-Feb-2012”到“29-Feb-2012”的交易报告返回事件 1 和事件 2。这两个事件均与同一个交易相关。 事件 3 虽然也与该交易相关，但发生在指定期间结束之后，所以不会包括在报告内。
使用 Reporting API 集成下载报告
Reporting 需要 http GET 请求，如下方所示。
GET /history/version/1/merchant/<merchant>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>
其中：
<merchant>是您的商家 ID。<starttime>和 <endtime> 指示跨越的时间段。<columns>是包括在报告中的字段，以逗号分隔。 名称区分大小写。<columnheaders>是包括在报告中的列标头列表，以逗号分隔。
包含开始时间（交易时间 >= 开始时间），不包含结束时间（交易时间 < 结束时间）。
开始时间和结束时间以 ISO 8601 格式作为参数传送： yyyy-mm-ddThh:mm:ssZ，其中的 Z 指示时间为 UTC。 如果时间不是 UTC，时区差必须指定为 +/-hh[:mm]，例如，12:31+10（UTC + 10 小时），或 12:31:30-06:30（UTC - 6 小时 30 分钟）。 报告中显示的时间值（如果有）为 UTC 时间。
一天的开始为 00:00。 报告结束时间 (timeOfRecord.end) 不包括在内，因此，若要报告到一天结束，应使用第二天的开始时间 (00:00) 作为结束时间。 同样，如果您需要小时数据，指定一个窗口作为一个小时和下一个小时的开始。
时区和时间格式
您可以在请求中指定两个可选参数：
csv.timeZone=<+ or ->HH:MM
如果指定，记录时间在指示时区输出，无时区指示符。 请注意，+ 和 - 符号必须是 UTF-8 编码。 例如，如果您设置
csv.timeZone=%2B10:00（即+10.00），报告中的事件时间显示为 UTC+10 小时。如果忽略，输入为 UTC 时间，附带一个 'Z' 指示 UTC 时区。
csv.timeFormat=<iso8601 or iso8601-T>
如果指定为
iso8601-T，输出使用空格而不是 T 作为日期时间分隔符。如果忽略或指定为
iso8601，日期时间分隔符为“T”。
夏令时
我们建议您在下载报告时忽略夏令时。 但是，如果您希望下载的报告加上夏令时窗口，那么您需要通过以下方法进行管理：
- 修改您指定的时区
- 需要说明一下，在夏令时开始时您将丢失一个小时的记录，在夏令时结束时则会收到一个小时的重复记录。
为避免夏令时带来的麻烦，请使用 UTC 时区来指定时间窗口。
列参数指定报告中显示的字段。 可以指定的字段在您支持的 API 版本的 Retrieve Transaction 操作中介绍。 请注意，Reporting API 版本与 API 版本不同。 可使用最新 API 版本选择的字段可以在此处找到。
order.item[n].detail。如果您使用多个 API 版本处理交易，您可以指定跨不同版本通用的字段，也可以指定特定版本的唯一字段。 某个记录不存在的数据将显示为 CSV 格式的空值。但是，任何一个字段名称必须至少对于一个 API 版本是有效的。
如果您在 columnHeaders 参数中提供您自己的列标头，那么名称列表将与“columns”列表中的字段列表对应。 &columnHeaders 和 &columns 必须具有相同的成员数。
如果请求中未包括标头（忽略 &columnHeaders），列标头将为字段名称。 如果传送了空标头参数 (&columnHeaders=)，输出文件将不包含任何标头行。
在您确定了要包括在请求中的字段后，您可以将其转发到 Mastercard Gateway。 此请求由 HTTPS GET 请求提交到支付网关。Mastercard Gateway 假设 URL 请求使用 UTF-8 编码，并支持所有有用的 Unicode 字符。 您必须遵守 URL 编码规则（参见 RFC 3986）。
默认情况下，下载内容类型为 CSV，使用 ISO8859-1 编码。 您可以使用内容类型标头中的适当 mime 类型指定以下编码之一：
- ASCII
- UTF-8
- Big5
- GB18030
- Shift-JIS
- KOI8-R
- EUC-JP
- EUC-KR
- ISO8859-1
例如，要使用 UTF-8 下载，则指定"接受字符集： UTF-8"。
商家 ID 在 URL 中。 密码验证通过基本 HTTP 身份验证执行。 密码是在“商家管理”中配置的商家配置文件的 Reporting 密码（注意： 此密码与 API 密码不同）。 请参见为 Reporting 生成密码。
基本身份验证用户名为“merchant.default”。
Bash 脚本示例
Bash 脚本示例使用 Curl 下载报告（参见 http://curl.haxx.se/）。 Curl 预计要在 .netrc 文件中设置的密码。 这将在用户的主目录中创建。 您需要将以下行添加到 .netrc 文件；<password> 将替换您的密码：
machine paymentgateway.commbank.com.au login merchant.default password <password>
Windows PowerShell 示例
Api 密码加密存储在主文件夹 ($HOME) 的 reportingPassword 文件中。 若要生成 reportingPassword 文件，运行下载包中包括的 setpassword.ps1 脚本。
有关如何设置凭据的详细信息，请参见此处。
如果您未在请求或下载脚本中提交密码，在执行调用时系统将提示您（如果您的 https 客户端/浏览器支持）提供密码。
为实现自动下载，您的系统可能使用计时器进程（例如，Linux 中的 cron 或 Windows 中的 Scheduled Tasks）触发的脚本语言发起一系列下载调用。 托管文件传输产品也可以执行此操作。
您可以选择下载频率。 十分钟间隔将使您的数据更接近实时，但每日间隔可能更有效。 下载频率应能够阻止文件变得太大或间隔时间太久–这两个问题将增强下载失败的可能性以及修复问题的紧急性。
理想情况是将每个调用的开始时间 (timeOfRecord.start) 设置为前一个成功调用的结束时间 (timeOfRecord.end)。 这可以确保您一次即获得所有记录。 使用 HTTP 状态代码检查上一次调用是否失败。 如果失败，脚本应等待几分钟然后重试。Mastercard Gateway 从处理交易到交易可供下载有几分钟的延迟。 如果您尝试下载该期间的记录，Mastercard Gateway 使用 DATA_AVAILABLE_AFTER 响应和允许的最新结束时间拒绝请求。
示例脚本包包含以下脚本：
- basicreportexample.sh/basicreportexample.ps1 - 由命令行参数配置的简单脚本；其下载指定时间范围内的报告。
- downloadreport.sh/downloadreport.ps1 - 用于运行调度程序未管理的脚本；其下载自上一次运行起的所有新交易事件。
- setpassword.ps1 - 提示提供密码并在 reportingPassword 文件中加密的 Windows PowerShell 脚本。 此脚本使用仅可用于 Windows 的加密功能。
使用 Bash 脚本示例时，此脚本假设您已在 .netrc 中配置了 Reporting 密码。
在对经过验证的有效 GET 请求作出的响应中，Reporting 提供包含所有 API 交易记录的 CSV 文件，记录由在此请求中指定的所有字段筛选，在由开始日期和结束日期定义的时间范围内创建或更新。 记录从最早交易到最近交易按升序排序。
卡号在报告中是隐藏的。
下方是示例交易报告：
time,order id,transaction id,card number,card expiry month,card expiry year,amount,currency,type,acquirer,acquirerCode 2012-05-14T06:23:10.859Z,11336976611,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T01:25:19.694Z,11337131511,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T06:33:31.709Z,11337150032,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T22:15:53.276Z,11337206569,1,345678xxxxx4564,5,13,75.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T00:22:14.516Z,11337214154,1,345678xxxxx4564,5,13,72.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:17.447Z,11337218888,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:43.533Z,11337218921,1,345678xxxxx4564,5,13,78.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T11:15:00.093Z,11337598863,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T12:29:52.954Z,11337603409,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-22T01:51:09.996Z,11337651486,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
如果请求无效，或者如果您提交的商家 ID 和密码无效或未获授权访问报告 API，将返回包含详细信息的错误消息。
如果您提交两个请求，第一个请求的结束日期/时间是第二个请求的开始日期/时间，交易记录将不会缺少或重复。 如果一直到结束日期/时间没有记录，将返回错误消息，指示上一次可能的结束日期/时间。
如果您指定的报告期间内没有记录，将返回包含标头但没有条目行的 CSV 文件。
使用 Web 浏览器下载报告
您可以使用 Web 浏览器直接请求报告。 可以在请求中提供的 URL 中配置报告。
通过下方模板创建 URL：
https://YOUR_GATEWAY_SERVER/history/version/1/merchant/
YOUR_MERCHANT_ID/transaction?REPORT_CONTENTS_AND_FORMAT
REPORT_CONTENTS_AND_FORMATexample:columns=merchant,order.id,transaction.id, transaction.amount,transaction.amount& columnHeaders=Merchant,OrderID,TransactionID,Currency,Amount
&timeOfRecord.end=2015-01-24T18:43:54
&timeOfRecord.start=2015-01-12T18:38:40
这将检索包含 2015 年 1 月 15 日 18:43:54h 到 2015 年 1 月 24 日 18:38:40h 之间的交易的商家、订单 ID、交易 ID、交易货币和交易金额的报告。 列标头将显示“Merchant”、“OrderID”、“TransactionID”、“Currency”和“Amount”。
将 URL 粘贴到您的浏览器中。 系统将提示您插入密码。 密码是在“商家管理”中配置的商家配置文件的 Reporting 密码（注意： 此密码与 API 密码不同）。 请参见为 Reporting 生成密码。 用户名请输入 merchant.default。
为 Reporting 生成密码
Reporting 需要对 Mastercard Gateway 发起密码验证请求。 您可以在“商家管理”中生成密码。
- 导航到管理 > Reporting API 集成设置 > 编辑。
- 单击生成新密码。
- 选择通过密码启用 Reporting API 集成访问框。
- 将密码复制到剪贴板和/或文本文件。 稍后将用到此密码。
- 单击提交。
系统生成的密码为一个 16 字节的编码为十六进制字符串的随机生成值。 尽管它有足够的长度和强度来抵抗强力猜测，但仍应当像保护用户密码和其他敏感数据一样妥善保护它。
您必须始终至少生成并启用一个密码，但也可以最多设置两个密码。 安全起见，您应该定期更改密码。 为此，请更生新密码并更新报告下载脚本。 两个密码在此转换期间均有效。