- 集成指南
- 支持的功能（其他功能）
- 补充数据
- II 级和 III 级数据
II 级和 III 级数据
信用卡交易可以通过交易数据的三个级别提交： I 级、II 级和 III 级。 每个级别由所提供的用于处理交易的信息量来定义。
- I 级包括标准交易数据，如日期、卡号和购买总额。
- II 级包括 I 级数据以及增强的交易数据，如客户参考号、发票号我销售税金额。
- III 级包括 II 级数据以及单项商品详细信息。
如果您接受商务卡、企业卡或购物卡，那么在交易中提供 II/III 数据可以在交易过程中享受到更好的交换费率。 您的客户的业务也可以从逐条记录的卡账单，以及支持并简化业务流程（如购买授权、对账和报告）的信息中受益。
请注意，网关不会验证交易中提供的数据是否足以获得享受卡组织需要的特定交换费率的资格。
仅 Direct API 版本 42 及以上版本支持 II/III 级数据。
在初始操作中提供 II/III 级数据
在创建订单时，您提供的所有 II 或 III 级数据都将应用到订单中的所有交易。
如果您使用网关执行 3DS 身份验证和付款交易，则可以通过提交 INITIATE_AUTHENTICATION，随后提交带有 II/III 级数据的 AUTHENTICATE_PAYER 请求来创建订单，并可以在后续的 AUTHORIZE、PAY 或 VERIFY 请求中提供 authentication.transactionId，II/III 级数据使用引用的身份验证填充。
如果 Authorize、Pay 或 Verify 请求中提供的 order.amount 与身份验证的 order.amount 不同，将不会从身份验证中复制 II/III 级数据。 在这种情况下，您必须提供有关财务交易的 II/III 级数据，因为不能从订单默认确定这些数据。
如果您在 AUTHENTICATE_PAYER 请求中提供了 II/III 级数据，然后在后续的 AUTHORIZE、PAY 或 VERIFY 请求中提供 authentication.transactionId，您仍然可以在财务请求中提交相同或不同的 II/III 级数据来覆盖身份验证中提供的 II/III 级数据。
AUTHENTICATE_PAYER 请求从版本 64 开始支持 II 级字段，从版本 77 开始支持 III 级字段。
Authenticate Payer API 参考 [REST][NVP]
在后续操作中提供 II/III 级数据
如果您希望执行以下操作，则只需在后续操作（Capture 或 Refund）中提供 II/III 级数据：
- 覆盖为订单提供的数据
您可以通过在订单级提供数据来覆盖订单的 II/III 级数据。 您可能希望使用此方法更正创建订单时提供的信息。 更新的信息随后将应用于订单中的所有后续交易。 例如，
order.customerReference只能覆盖交易请求中显示的订单级字段。 例如，order.amount可以在 Authorize 交易请求中提供，但不能在 Capture 交易请求中提供。请参见下方 II/III 级表中的订单级字段列。
- 提供仅适用于该交易的数据
您可以提供仅适用于特定交易的 II/III 级数据。 例如，
transaction.taxAmount请参见下方 II/III 级表中的交易级字段列。
- 执行交易金额与订单金额不同的 Capture 或 Refund 交易。 这种情况下，您必须在交易中提供 II/III 级数据，如金额或单项商品详细信息，因为这些信息无法从订单中默认获得。
将 II/III 级数据发送到收单行
当网关将 II/III 级数据发送到您的收单行后，在交易中提供的值将优先于在订单级提供的值。 如果您未在交易中提供值，网关会将在订单级提供的值发送给收单行（如果适用）。
提交到收单行的 II/III 级数据仅用于 Capture 和 Refund 交易，不用于 Authorization 或 Verification Only 交易。
II 级数据
若要在交易请求中提供以下 II 级数据，请使用对应的订单级和/或交易级 Direct API 字段（如下表所示）。
| II 级数据 | 订单级字段 | 交易级字段 |
|---|---|---|
| 客户订单日期 | order.customerOrderDate |
|
| 订单金额（创建订单时提交的待授权金额） | order.amount如果您提供任何小计金额（ order.itemAmount、order.shippingAndHandlingAmount、order.taxAmount、order.gratuityAmount、order.cashbackAmount）、order.discount.amount，订单金额必须等于小计金额的总和减去折扣金额。 |
|
| 商品金额 | order.itemAmount如果您未提供此值但提供了单项商品数据，那么此金额计算为所有单项商品的商品总额（ order.item[n].unitPrice 乘以 order.item[n].quantity）之和。 如果您同时提供此值和单项商品数据，那么此字段中的值必须等于计算后的值。如果计算后的值中小数位超过了付款人货币的最小单位，网关会使用“舍入到偶数”算法舍入总额。 例如，如果 2.555（数量）乘以 3（单价）总计为 7.665，如果付款人使用的货币（美元）最小单位为 2，那么舍入后的商品金额将等于 7.66。 请确保在请求中提供商品金额字段时使用此舍入方法。 |
transaction.itemAmount |
| 运费和手续费金额 | order.shippingAndHandlingAmount交易（包括任何适用税费）的运费和手续费总金额。 |
transaction.shippingAndHandlingAmount |
| 运费和手续费纳税金额 | order.shippingAndHandlingTaxAmount仅版本 67 及以上版本支持此字段。 对交易的运费和手续费金额征收的纳税金额。 此金额包含在 order.shippingAndHandlingTaxAmount 字段中提供的运费和手续费金额中。
|
transaction.shippingAndHandlingTaxAmount |
| 运费和手续费税率 | order.shippingAndHandlingTaxRate仅版本 67 及以上版本支持此字段。 适用于订单的运费和手续费金额的税率，用以确定运费和手续费纳税金额。 如果税率为 2.5%，提供 0.025。 |
transaction.shippingAndHandlingTaxRate |
| 纳税金额 | order.dutyAmount仅版本 67 及以上版本支持此字段。 交易的关税金额，也称为手续费。 |
transaction.dutyAmount |
| 纳税金额 | order.taxAmount如果您未提供此值但提供了单项商品数据，那么此金额计算为所有单项商品的税金总额（ order.item[n].unitTaxAmount 乘以 order.item[n].quantity）之和。 如果您同时提供此值和单项商品数据，那么此字段中的值必须等于计算后的值。如果计算后的值中小数位超过了付款人货币的最小单位，网关会使用“舍入到偶数”算法舍入总额。 例如，如果 2.555（数量）乘以 3（单价）总计为 7.665，如果付款人使用的货币（美元）最小单位为 2，那么舍入后的商品金额将等于 7.66。 请确保在请求中提供商品金额字段时使用此舍入方法。 |
transaction.taxAmount |
| 纳税类型 [n] | order.tax[n].type您可能需要提交收单行所需的正确的枚举值。 请联系 ANZ Worldline Payment Solutions 了解详细信息。 |
transaction.tax[n].type您可能需要提交收单行所需的正确的枚举值。 请联系 ANZ Worldline Payment Solutions 了解详细信息。 |
| 纳税金额 [n] | order.tax[n].amount |
transaction.tax[n].amount |
| 税率 [n] | order.tax[n].rate |
transaction.tax[n].rate |
| 免税标记 | order.taxStatus |
transaction.taxStatus |
| 折扣金额 | order.discount.amount |
transaction.discountAmount |
| 商家购买参考 | order.reference如果未提供，网关将使用 order.id（强制字段）中提供的值。 |
|
| 发票号 | order.invoiceNumber |
|
| 客户/持卡人参考号 | order.customerReference |
|
| 请求者姓名 | order.requestorName |
|
| 商家税务登记 ID - 联邦/国际 | order.taxRegistrationId |
如果您是美国商家，请提供您的联邦税务 ID。 如果您是加拿大商家，请提供您的加拿大税务局的 HST（统一销售税）账户。 |
| 商家税务登记 ID - 州/省/自治区/直辖市/地方 | order.localTaxRegistrationId |
|
| 客户增值税注册号 | customer.taxRegistrationId |
|
| 商家地址 - 邮政编码 | 在商家配置文件中配置的值提交给收单行。 | |
| 商家地址 - 州/省/自治区/直辖市 | 在商家配置文件中配置的值提交给收单行。 | |
| 发货地邮政编码 | shipping.origin.postcodeZip如果未提供，在商家配置文件中配置的值可能会提交给收单行。 |
|
| 送货地址街道 | shipping.address.streetshipping.address.street2 |
|
| 送货地址城市 | shipping.address.city |
|
| 送货地址州/省/自治区/直辖市 | shipping.address.stateProvince您必须提供三个字符的 ISO 3166-2 国家/地区细分代码。 如果目的地是美国领地，提供国家/地区代码。 例如，shipping.address.conational 和 shipping.address.stateProvince 字段中的 GUM。仅当订单中包含的所有商品都运往同一地点时，再提供此字段。 |
|
| 送货地址国家/地区 | shipping.address.country如果目的地是美国领地，提供国家/地区代码。 例如， shipping.address.country 和 shipping.address.stateProvince 字段中的 GUM。 仅当订单中包含的所有商品都已运送到同一地点时，再提供此字段。
|
|
| 送货地址邮政编码 | shipping.address.postcodeZip |
|
| 账单地址姓名 | customer.firstNamecustomer.lastName |
|
| 账单地址街道 1 | billing.address.street |
|
| 账单地址街道 2 | billing.address.street2 |
|
| 账单地址城市 | billing.address.city |
|
| 账单地址州/省/自治区/直辖市 | billing.address.stateProvince |
|
| 账单地址邮政编码 | billing.address.postcodeZip |
|
| 账单地址国家/地区 | billing.address.country |
|
III 级数据
III 级数据包括上面列出的 II 级数据以及单项商品数据。 若要在交易请求中提供以下 III 级数据，请使用对应的订单级（来自 order.item[n] 参数组）和/或交易级（来自 transaction.item[n] 参数组）Direct API 字段（如下表所示）。
所有 III 级字段均为可选字段；但是，如果您在交易请求中提供了单项商品数据，那么您必须至少提供该商品的名称、数量和单价。
| III 级数据 | 订单级字段 | 交易级字段 |
|---|---|---|
| 商品商家税务 ID | 此值不能在商品级提供。 对于所有商品，字段 order.taxRegistrationId 中订单级别提供的值将提交给收单行。 |
|
| 商品总额 | 如果收单行消息中需要提供此值，那么此金额计算为所有单项商品的商品总额（order.item[n].unitPrice 乘以 order.item[n].quantity）之和。 |
|
| 商品计量单位 | order.item[n].unitOfMeasure您可能需要提交收单行所需的正确的枚举值。 请联系 ANZ Worldline Payment Solutions 了解详细信息。 |
transaction.item[n].unitOfMeasure您可能需要提交收单行所需的正确的枚举值。 请联系 ANZ Worldline Payment Solutions 了解详细信息。 |
| 商品描述 | order.item[n].description |
transaction.item[n].description |
| 商品品牌 | order.item[n].brand |
transaction.item[n].brand |
| 商品类别 | order.item[n].category |
transaction.item[n].category |
| 商品行业类别 | order.item[n].industryCategory |
transaction.item[n].industryCategory |
| 商品名称 | order.item[n].name |
transaction.item[n].name |
| 商品 SKU | order.item[n].sku |
transaction.item[n].sku |
| 商品 UNSPSC（联合国标准产品和服务代码） | order.item[n].detail.unspsc |
transaction.item[n].detail.unspsc |
| 商品 UPC（通用产品代码） | order.item[n].detail.upc |
transaction.item[n].detail.upc |
| 商品编码 | order.item[n].detail.commodityCode |
transaction.item[n].detail.commodityCode |
| 商品数量 | order.item[n].quantity当十进位数量与金额（ order.item[n].unitPrice、order.item[n].unitTaxAmount 或 order.item[n].unitDiscountAmount）相乘，并且计算后的值中小数位超过了付款人货币的最小单位时，网关会使用“舍入到偶数”算法舍入总额。 例如，如果 2.555（数量）乘以 3（单价）总计为 7.665，如果付款人使用的货币（美元）最小单位为 2，那么舍入后的商品金额将等于 7.66。 |
transaction.item[n].quantity |
| 商品单价 | order.item[n].unitPrice此金额乘以 order.item[n].quantity 得出单项商品的商品总额。 如果提供了 order.itemAmount，那么所有单项商品的商品总额之和必须等于 order.itemAmount 中的值
|
transaction.item[n].unitPrice |
| 商品单位税额 | order.item[n].unitTaxAmount此金额乘以 order.item[n].quantity 得出单项商品的纳税总额。 如果提供了 order.taxAmount，那么所有单项商品的纳税总额之和必须等于 order.taxAmount 中的值。
|
transaction.item[n].unitTaxAmount |
| 商品纳税类型 | order.item[n].detail.unitTaxType使用此字段可提供为此单项商品收取的纳税类型（如果只使用单一纳税类型）。 |
transaction.item[n].detail.unitTaxType |
| 商品税率（百分比） | order.item[n].detail.unitTaxRate使用此字段可提供为此单项商品收取的税率（如果只使用单一税率）。 |
transaction.item[n].detail.unitTaxRate |
| 商品纳税类型 [n] | order.item[n].detail.tax[m].typeorder.item[n].detail.tax[m].amountorder.item[n].detail.tax[m].rate使用这些字段可以按照纳税类型提供单项商品的订单纳税金额细分。 如果对此单项商品收取了多个纳税类型的税款，此选项适用。 如果有单一纳税类型，使用 order.item[n].detail.unitTaxType |
transaction.item[n].detail.tax[m].typetransaction.item[n].detail.tax[m].amounttransaction.item[n].detail.tax[m].rate使用这些字段可以按照纳税类型提供单项商品的交易纳税金额细分。 如果对此单项商品收取了多个纳税类型的税款，此选项适用。 如果有单一纳税类型，使用 transaction.item[n].detail.unitTaxType |
| 商品纳税金额 [n] | ||
| 商品税率 [n]（百分比） | ||
| 商品折扣金额 | order.item[n].unitDiscountAmount此金额乘以 order.item[n].quantity 得出单项商品的折扣总额。 如果提供了 order.discount.amount，那么此字段中的值必须等于所有单项商品折扣总额的总和。 |
transaction.item[n].unitDiscountAmount |
| 商品折扣率（百分比） | order.item[n].detail.unitDiscountRate |
transaction.item[n].detail.unitDiscountRate |