- 集成指南
- 实施 <<batchIntegration>> 集成
实施 <<batchIntegration>> 集成
先决条件
- 请确保已为<<batchIntegration>>服务启用商家配置文件。
- 在开始集成前,请参见最佳做法和建议。
集成步骤
步骤 1:访问网关
第一步,检查与 QNB ALAHLI 的连接。
步骤 2:了解您的输入字段
在开始构建集成前,您必须为需要您输入的字段准备输入值。
步骤 3:创建批处理请求
创建请求主体是商家集成的关键步骤。
步骤 4:发送批处理请求
有很多组件可以确保交易请求主体安全地发送到 QNB ALAHLI。
步骤 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,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104169,TXID1,100,AUD,345678901234564,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 并重新提交请求。 |
发生网关错误 | 由于网关内部错误无法将请求提交到网关。请稍后重试。 |
<<batchIntegration>> 处理操作可能由于通信或系统故障失败,导致出现以下错误之一:
- 由于内部系统故障出现的错误。
- 由于服务器当时没有充足的资源处理请求而出现的错误。
- 处理 <<tokenization>> 验证交易时出现的错误
如果出现此错误且操作可重试,<<batchIntegration>> 将尝试重新发送操作进行处理,直到操作收到不可重试的响应或达到重试次数限制。
<<batchIntegration>> 将存储批处理名称以及您上载的相应的消息完整性代码 (MIC)。<<batchIntegration>> 将识别之前提交的具有批处理名称但包含不同内容的批处理并拒绝。
与之前提交的批处理具有相同名称和内容的批处理也可以被识别,<<batchIntegration>> 将返回与之前上载的批处理相同的状态。因此,如果商家怀疑存在传输问题,其可以验证批处理是否已成功上载到 <<batchIntegration>>。
提交的要进行处理的批处理请求的标头行中的值只能包含可以在 <<webServicesIntegration>> NVP 字段名称中找到的字符。允许使用以下字符:
- 字母数字(a-z、A-Z、0-9)
- 句点 (.)
- 方括号 ([ ])
如果遇到解析错误,<<batchIntegration>> 将拒绝批处理。解析包括将批处理拆分为行,将行拆分为字段。
以下情况可能出现解析错误:
- 操作记录包含的逗号超过标头记录中包含的逗号数量
- 超过最大单个字段尺寸
在重新提交批处理进行处理前,您必须先更正这些错误。
最佳做法和建议
<<batchIntegration>> 服务不能保证将处理的操作属于批处理文件中指定的同一个订单,因为 <<batchIntegration>> 调度程序可以并行处理操作。此行为可能要归因于重试功能,即,如果批处理文件中的某些操作需要重试,那么就绪操作将被首先处理,不论其指定的顺序如何。例如,即使后续操作在初始操作后指定(Authorization 在 Capture 之后,Pay 在 Void 之后),Capture 也可能在 Authorization 之前执行,或 Void 在 Pay 之前执行。
因此,对于必须严格按照顺序执行操作,建议您先运行初始的操作批处理,等待批处理响应文件,待成功后再运行后续的操作批处理。
<<tokenization>> 将卡详细信息存储在令牌中。若要通过 <<batchIntegration>> 使用 <<tokenization>>,您必须在批处理文件中使用令牌识别码,如下所示。
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,,,,
操作凭据包括商家识别码和密码。批处理中每个操作的操作凭据将默认为批处理请求标头中提供的身份验证凭据(商家识别码和密码)。但是,如果您根据操作记录行为两个字段都指定了值,那么操作身份验证将使用操作级别凭据,不会默认为上载批处理凭据。
可以,如果这些操作类型不是与同一个订单有关,即不包含相同的订单识别码,那么您便可以在一个批处理文件中处理多个操作类型。<<batchIntegration>> 服务不能保证将处理的操作属于批处理文件中指定的同一个订单,因为 <<batchIntegration>> 调度程序可以并行处理操作。此行为可能要归因于重试功能,即,如果批处理文件中的某些操作需要重试,那么就绪操作将被首先处理,不论其指定的顺序如何。例如,如果 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,,,,,