- 集成指南
- 支持的功能（付款选项）
- 动态货币兑换
动态货币兑换
American Express Payment Gateway 可以向您提供来自 DCC 提供商以您的首选货币定价的商品和服务的实时费率报价。 您可以向付款人提供此汇率，然后付款人可以选择使用首选货币或卡的币种支付。 持卡人可以在购物时确切了解使用本国货币将支付的金额，由此从此项服务中获益。
主要优点
- 付款人可以在销售点使用账单货币为商品或服务付款。
- 您收到一笔货币兑换费用。
- 订单按订单所用货币处理。
- 付款人看到的订单金额用卡账单上的货币表示。
- 付款人不会在卡账单上看到货币兑换费用（因为此项费用包含在所提供的费率报价内）。
费率报价的先决条件
- 您必须在希望使用的 DCC 提供商处注册。
American Express Payment Gateway 目前支持：
- FEXCO。
通过网关管理费率报价
对交易应用 DCC 有四种相互排斥的基本情况：
- 您不希望在交易中应用 DCC；例如，如果付款人的卡的货币与您的首选货币匹配。
- 如果出价在表中，但没有此出价，您希望应用 DCC。
- 您希望应用 DCC。 DCC 提供商已出价。 您已向付款人提供了此出价，但被其拒绝。
- 您希望应用 DCC。 DCC 提供商已出价。 您已向付款人提供了此出价，并被其接受。
请求费率报价
您可以通过在 Payment Options Inquiry (apiOperation=PAYMENT_OPTIONS_INQUIRY) 请求中为以下字段提供数据来请求费率报价：
order.amount.order.currency.paymentType. 如果提供，则必须设置为CREDIT。
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND。在使用 REST 协议调用 Payment Options Inquiry 操作时，应确保请求参数包含在 URI（作为查询参数）中，而不包含在 JSON 主体中。 下方是 Curl 中的 DCC 费率报价的 REST 请求示例。
curl --user merchant.TESTMERCHANT-DCC:<PASSWORD>"https://gateway-na.americanexpress.com/api/rest/version/72/merchant/TESTMERCHANT-DCC/paymentOptionsInquiry?order.amount=123.34&order.currency=USD&sourceOfFunds.provided.card.prefix=531335999"
费率报价状态响应
American Express Payment Gateway 返回有关 DCC 报价的以下信息。 这些信息中有一部分将包含在您在付款页或 PED 终端向付款人显示的信息中，且与组织和法律要求一致。
currencyConversion.gatewayCode:QUOTE_PROVIDED: 提供的报价。NOT_ELIGIBLE: DCC 不适用于此卡和/或货币。UNSUPPORTED_CARD_BRAND: 不支持的卡品牌。INSUFFICIENT_INFORMATION: 请求中缺少必填字段。ERROR: DCC 提供商无法处理此操作。
currencyConversion.provider: DCC 报价提供商的名称。currencyConversion.providerCode: 由 DCC 提供商生成，用于汇总 DCC 报价请求的成功或其他信息。currencyConversion.providerReceipt: DCC 提供商的唯一费率报价参考。（不一定提供。）currencyConversion.exchangeRateSource: 用作汇率来源的财务数据机构。currencyConversion.payerExchangeRate: 用于将交易金额转换为付款人货币的汇率。 包括currencyConversion.marginPercentage。currencyConversion.payerAmount: 以付款人货币计的交易总金额。currencyConversion.payerCurrency: DCC 提供商提供的 DCC 费率报价的货币。currencyConversion.marginPercentage: 以提供兑换服务的交易金额的百分比形式使用的外汇标价。currencyConversion.exchangeRateTime: 兑换率有效期间的时间戳。currencyConversion.quoteExpiry: 指示 DCC 报价过期时间的时间戳。 （不一定提供。）currencyConversion.offerText: 包含 DCC 报价的输入表单的 HTML 片段。 此信息必须向付款人显示以收集他们的选择信息。currencyConversion.requestId: 在 PAYMENT_OPTIONS_INQUIRY 响应中返回的 DCC 报价请求的唯一识别码。
Payment Options Inquiry API 参考[REST][NVP]
为交易使用费率报价
-
如果您从 DCC 提供商处获取费率报价 (
currencyConversion.gatewayCode=QUOTE_PROVIDED)，您可以向付款人提供货币兑换报价。费率报价优惠文字
Visa 和 Mastercard 对于向付款人显示 DCC 信息做出了一些特定要求，以确保向付款人显示作出明智选择所需要的信息。 这包括 DCC 报价和交易收据内的费用和收费详细信息（如果付款人接受报价）。
DCC 规则的基本原则：
- 持卡人可以选择使用商家货币或其本国货币支付，交易详细信息全部公开透明。
- 持卡人有权选择接受或拒绝 DCC 报价。
- 与 DCC 相关的条款和条件向持卡人充分披露。
报价介绍
系统将在
paymentTypes.card.currencyConversion.offerText中为您提供报价文本。 您可以通过设置locale=<Valid language identifier or IETF language tag of payer's locale>来指定报价文本的区域设置（例如，en代表英语，pt-BR代表巴西葡萄牙语，es-MX代表墨西哥西班牙语）。区域特定的 HTML 格式 DCC 报价文本在
paymentTypes.card.currencyConversion.offerText中返回，支持以下区域设置：- 法语 (fr_FR)
- 德语 (de_DE)
- 墨西哥西班牙语 (es_MX)
- 中文：
- 简体中文 (zh_CN)
- 港式中文 (zh_HK)
- 巴西葡萄牙语 (pt_BR)
- 日语 (ja_JP)
- 印度尼西亚语 (id_ID)
- 英语：
- 美国英语 (en_US)
- 英国英语 (en_UK)
- 澳大利亚英语 (en_AU)
如果区域不受支持，American Express Payment Gateway 将根据以下组织提供报价文本：
- 语言代码与支持的最近区域匹配（如果有）。
- 如果您未设置
interaction.locale，或者如果所提供的区域和基本语言不受支持，American Express Payment Gateway 将尝试使用您配置的默认区域。 如果配置的区域和基本语言也不受支持，报价将使用en_US显示。
然后付款人可以：-
接受 DCC 报价并选择使用卡货币付款。
在这种情况下，请使用以下参数发起交易请求：
- American Express Payment Gateway 在响应中返回的
currencyConversion.requestId。 currencyConversion.uptake=ACCEPTED.
向付款人提供在
RETRIEVE_TRANSACTION响应的paymentTypes.card.currencyConversion.receiptText中提供的收据文本。 这使用与报价文本相同的区域。 - American Express Payment Gateway 在响应中返回的
-
拒绝 DCC 报价并选择使用订单货币支付 (
currencyConversion.uptake=DECLINED)。在这种情况下，请使用以下参数发起交易请求：
- American Express Payment Gateway 在响应中返回的
currencyConversion.requestId。 currencyConversion.uptake=DECLINED.
- American Express Payment Gateway 在响应中返回的
-
如果您在 Payment Options Inquiry 响应中收到以下信息之一：
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRANDcurrencyConversion.gatewayCode=NOT_ELIGIBLEcurrencyConversion.gatewayCode=ERROR
您必须在您的交易请求中设置
currencyConversion.uptake=NOT_AVAILABLE，并提供正确的currencyConversion.requestId。
这支持 DCC 提供商将数据用于分析和报告目的。
如果您在网关外部获得了费率报价，则必须明确提供 DCC 提供商在交易请求中向您返回的 DCC 详细信息。
如果您想在执行付款之前使用身份验证 API 对付款人进行身份验证，则必须按照说明将 DCC 字段传入到 Initiate Authentication 操作。 付款人身份验证完成后，您可以通过 Authorize 或 Pay 操作继续对同一订单进行付款，并提供您在 Initiate Authentication 和 Authenticate Payer 操作中提供的 authentication.transactionId。 您无需在财务交易中再次传递 DCC 字段，因为 DCC 字段在引用的付款人身份验证交易中传递。
过账/退款 DCC 交易
过账
必须在 Authorize 交易请求中提供 DCC 详细信息。 DCC 详细信息应用于订单中的过账。
对于完全过账，将使用来自 Authorize 请求的 DCC 详细信息。
对于部分或超额过账，American Express Payment Gateway 将按比例计算金额的百分比。
退款
如果您通过 American Express Payment Gateway 中 DCC 的 MSO 进行配置，此配置将应用于后续退款。
配置选项：
CURRENT: 请求新费率报价在退款交易日期提供实际费率。HISTORICAL: 订单创建时使用的费率将应用于退款。
如果初始交易为 currencyConversion.uptake=ACCEPTED：
- 配置为
CURRENT：- 将为特定退款金额请求费率报价。 这将生成新的
currencyConversion.requestId。 新费率报价将应用于退款。 - 交易响应返回
currencyConversion.uptake=ACCEPTED。
- 将为特定退款金额请求费率报价。 这将生成新的
- 配置为
HISTORICAL：- 为发起订单中的交易提供的 DCC 详细信息将用于计算退款的
currencyConversion.payerAmount。 - 对于部分退款或超额退款金额，初始交易的
currencyConversion.payerAmount将按比例以商家金额的百分比形式提供。 使用按比例方法时，将使用标准舍入法。 - 如果您使用部分退款来执行过账金额的完全退款，最后的部分退款将包含未付的已过账付款人金额。 这样做是为了处理部分金额的舍入。 如果总退款金额不等于总过账金额，将不对付款人金额进行验证（例如，超额退款）。
- 交易响应返回
currencyConversion.uptake=ACCEPTED。
- 为发起订单中的交易提供的 DCC 详细信息将用于计算退款的
如果初始交易为 currencyConversion.uptake=DECLINED、NOT_AVAILABLE 或 NOT_REQUIRED：
如果初始授权和过账作为非 DCC 交易成功处理，您提交后续退款请求将与您的商家配置无关：
- 将不请求费率报价。
- 不会在退款交易响应或 Retrieve Transaction 操作中返回
currencyConversion字段。
测试您的 DCC 集成
您可以使用测试商家配置文件来测试您的 DCC 集成。