- 集成指南
- 实施 Batch 集成
实施 Batch 集成
先决条件
- 请确保已为 Batch 服务启用商家配置文件。
- 在开始集成之前，请参阅最佳做法和建议。
集成步骤
步骤 1： 访问网关
第一步，检查与 Mastercard Gateway 的连接。
步骤 2： 了解您的输入字段
在开始构建集成之前，您必须准备好需要输入的字段的值。
步骤 3： 创建批处理请求
创建请求的正文是集成中的关键步骤。
步骤 4： 发送批处理请求
有许多组件可以确保交易请求正文安全地发送到 Mastercard Gateway。
步骤 5： 检索批处理状态
批处理提交后，您可以定期请求批处理状态以确定批处理的当前状态。
步骤 6： 处理批处理响应
批量操作完成后，您可以请求一个包含每个已上载操作的结果的响应文件。
步骤 7： 测试与投入使用
测试可以让您检查您的集成是否按预期工作。
疑难解答和常见问题
我能否在一个批处理请求中使用多个商家配置文件？
可以，您可以在一个批处理请求中使用多个商家配置文件，前提是您可以确保每个操作记录行的操作凭据（商家识别码和身份验证密码）均有效，可以支持成功的身份验证和授权。
默认情况下，批处理中每个操作的操作凭据将使用批处理请求标头中提供的身份验证凭据（商家标识符和密码）。 您可以选择使用默认机制，或者针对每个操作记录行提供操作凭据。 如果使用后一种方法，操作身份验证将使用操作级别凭据，不会默认为上载批处理凭据。 如果操作级别凭据不正确，批处理上载将被拒绝。
在下方的示例批处理文件中，VOID 操作将使用批处理请求标头凭据，因为未提供商家识别码和密码。
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
批处理提交失败的可能原因有哪些？
批处理提交可能由于以下错误情况而失败。
| 场景 | 错误消息 |
|---|---|
| 批处理由于 SHA-1 消息摘要不匹配未完成 | 批处理提交由于以下原因之一失败：
|
批处理名称重复
|
批处理提交失败： 当前正在上载具有此名称的批处理，或已上载具有此名称但内容不同的批处理。 如果文件正在上载，请等待上载结束。 如果您使用的文件名已被使用，请重命名文件并再次提交。 |
如果您没有足够的权限提交批处理，将返回身份验证错误：
|
身份验证失败： 在记录 <record number> 中提供的凭据不正确。 这可能是由以下原因造成的：
|
| 如果您在操作级别只提供了密码但未提供商家 ID，将返回身份验证错误。 | 身份验证失败。 在批处理文件的记录 <record number> 中，提供了密码但未提供商家 ID。 请添加商家 ID 或删除密码以为此记录使用批处理级别的商家凭据，然后尝试重新提交请求。 |
| 如果批处理凭据的格式不正确，将返回身份验证错误。 | 身份验证失败： 在标头中提供的凭据可能：
|
如果出现以下情况，则会返回身份验证错误：
|
身份验证失败： 为批处理提供的凭据无效。 请更正凭据，并尝试重新提交请求。 |
| 如果标头包含无效字符，则会返回解析错误。 | 批处理提交失败： 无法解析批处理，因为标头包含非法字符。 允许的字符包括：
|
| 如果操作记录行包含的值多于标头中定义的值，将返回解析错误。 | 批处理提交失败： 由于记录 <record number> 包含的值多于标头中定义的数量而无法解析批处理。 请更正批处理，然后尝试重新提交。 |
| 如果超过最大单个字段尺寸或操作记录中发生未知解析错误，将返回解析错误。 | 批处理提交失败： 批处理由于记录 <record number> 中的错误无法解析。 请确保批处理符合文件格式并且您使用的是正确的编码，然后尝试再次提交批处理。 |
| 如果没有提供编码或者提供了不受支持的编码，则会返回编码错误。 | 请求失败： 提供的编码不受支持。 支持的编码是 UTF-8 和 LATIN1。 请使用支持的编码再次提交请求。 |
| 找不到批处理 | 请求失败： 找不到具有此批次名称的批次。 请更正批处理名称并再次提交请求。 |
| 所提供版本的长度检查失败。 | 请求失败： 提供的版本无效。 请更正版本并重新提交请求。 |
| 对提供的批处理名称的长度检查失败。 | 请求失败： 提供的批处理名称无效。 请更正批处理名称并再次提交请求。 |
| 所提供商家 ID 的长度检查失败。 | 请求失败： 提供的商家 ID 无效。 请更正商家 ID 并重新提交请求。 |
| 发生网关错误 | 由于网关内部错误，无法将请求提交给网关。 请稍后重试。 |
Batch 处理操作可能由于通信或系统故障失败，导致出现以下错误之一：
- 由于内部系统故障而发生错误。
- 由于服务器目前没有足够的资源来处理请求而发生错误。
- 处理 Tokenization 验证交易时发生错误
如果出现此错误且操作可重试，Batch 将尝试重新发送操作进行处理，直到操作收到不可重试的响应或达到重试次数限制。
Batch 会存储您上载的批处理名称及其对应的消息完整性代码 (MIC)。 Batch 将识别之前提交的具有批处理名称但包含不同内容的批处理并拒绝。
与之前提交的批处理具有相同名称和内容的批处理也可以被识别，Batch 将返回与之前上载的批处理相同的状态。 因此，如果商家怀疑存在传输问题，他可以验证批处理是否已成功上载到 Batch。
提交的要进行处理的批处理请求的标头行中的值只能包含可以在 API NVP 字段名称中找到的字符。 允许使用以下字符：
- 字母数字（a-z、A-Z、0-9）
- 句点 (.)
- 方括号 ([ ])
如果遇到解析错误，Batch 将拒绝批处理。 解析包括将批处理拆分为行，将行拆分为字段。
在以下情况下可能会发生解析错误：
- 操作记录包含的逗号超过标头记录中包含的逗号数量
- 超出了最大单个字段大小
在重新提交批处理进行处理前，您必须先更正这些错误。
最佳做法和建议
Batch 服务不能保证按照批处理文件中指定的顺序处理操作，因为 Batch 调度程序可以并行处理操作。 此行为可能要归因于重试功能，即，如果批处理文件中的某些操作需要重试，那么就绪操作将被首先处理，不论其指定的顺序如何。 例如，即使后续操作在初始操作后指定（Authorization 在 Capture 之后，Pay 在 Void 之后），Capture 也可能在 Authorization 之前执行，或 Void 在 Pay 之前执行。
因此，对于必须严格按照顺序进行的操作，建议您先运行初始批处理操作，等待批处理响应文件，如果成功，再运行后续批处理操作。
Tokenization 将卡的详细信息存储在令牌中。 要将 Tokenization 与 Batch 一起使用，您必须在批处理文件中使用令牌标识符，如下所示。
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
操作凭据包括商家识别码和密码。 批处理中每个操作的操作凭据将默认为批处理请求标头中提供的身份验证凭据（商家识别码和密码）。 但是，如果您根据操作记录行为两个字段都指定了值，那么操作身份验证将使用操作级别凭据，不会默认为上载批处理凭据。
可以，您可以在单个批处理文件中处理多种操作类型，只要它们与同一订单不相关，即它们不包含相同的订单标识符。 Batch 服务不能保证按照批处理文件中指定的顺序处理操作，因为 Batch 调度程序可以并行处理操作。 此行为可能要归因于重试功能，即，如果批处理文件中的某些操作需要重试，那么就绪操作将被首先处理，不论其指定的顺序如何。 例如，如果 Pay 和 Void 操作在同一个批处理文件中，则 Void 可以在 Pay 之前执行。 但是，如果操作与同一订单不相关，即，如果它们包含不同的订单标识符，您可以在一个批处理文件中有多个操作类型。
可以，您可以在单个批处理文件中使用多个卡详细信息来源（除付款会话标识符外）。 有关多个来源的信息，请参见多个卡详细信息来源。
以下示例中的 Authorize 操作使用令牌而不是卡详细信息。
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,