Multi-Currency Transaction

仅适用于线上（EC）场景。

在线上交易中，商户经常面对来自不同国家的用户。交易发生时，用户通常更希望使用本国货币进行交易。因此，EVO Payment 提供了汇率查询（FX Rate Inquiry）和多币种定价（Multi-Currency Price，MCP）两项功能，以满足商户的需求。

汇率来源设置

您可以在 EVO Payment 门户中配置各场景使用的汇率来源。汇率来源分为两类：EVO Payment 汇率（EVO Payment FX Rate）和收单机构汇率（Acquirer FX Rate）。

在 EVO Payment 汇率下，您还可以针对不同卡组织（包括 Visa、Mastercard 和 JCB）指定汇率。此外，EVO Payment 支持自动选择优惠汇率（Priority FX Rate）。详情请参阅《EVO Payment 门户用户手册》。

如果您将汇率来源配置为收单机构汇率，请注意，在 EVO Payment 门户中设置汇率后，最长可能需要等待 5 分钟，才能在 API 调用中使用这些汇率。

汇率查询（FX Rate Inquiry）

该服务使商户能够获取每日汇率，并据此对商品重新报价。收单机构可以定义汇率来源，或设置自定义汇率及加价（markup）。

汇率来源设置

您可以在 EVO Payment 门户中配置汇率查询所使用的汇率来源。汇率来源分为两类：EVO Payment 汇率和收单机构汇率。在 EVO Payment 汇率下，您还可以针对不同卡组织（包括 Visa、Mastercard 和 JCB）指定汇率。此外，EVO Payment 支持自动选择优惠汇率。详情请参阅《EVO Payment 门户用户手册》。

汇率查询请求

您可以从服务端向 EVO Payment 以下接口发起 HTTP GET 请求：

/g2/v1/payment/mer/{sid}/FXRateInquiry

并指定以下额外参数：

参数	是否必填	说明
`baseCurrency`	M	被转换的原币种代码。
`quoteCurrency`	M	转换后的目标币种代码。

如果汇率来源为 EVO Payment 汇率，您可以查询任意两种币种之间的汇率。但如果汇率来源为收单机构汇率，您需要先在 EVO Payment 门户中配置相应汇率，才能通过 API 获取。

以下是不带任何查询参数的请求示例：

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/FXRateInquiry? baseCurrency=USD&quoteCurrency=IDR paymentMethod \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"

响应中的 localToTransFXRate 对象包含汇率信息，字段如下：

baseCurrency：被转换的原币种代码。
quoteCurrency：转换后的目标币种代码。
date：汇率值，精确到小数点后 7 位。
value：汇率处理日期。

详情请参阅*《EVO Payment API 规范》*。

以下是响应示例：

{
    "fxRateInquiry": {
        "localToTransFXRate": {
            "baseCurrency": "IDR",
            "date": "20230912",
            "quoteCurrency": "USD",
            "value": "0.0000688"
        }
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

多币种定价（MCP）

步骤 1：获取转换后的交易金额

您可以从服务端向 EVO Payment 以下接口发起 HTTP POST 请求：

/g2/v1/payment/mer/{sid}/FXRateInquiry

并指定以下额外参数：

参数	是否必填	说明
`merchantTransInfo`	M	汇率查询的参考信息，包括唯一的 `merchantTransID`，以及表示您发起请求时间的 `merchantTransTime`。
`transAmount`	M	支付转换后的币种。金额必须符合该币种的最小单位规则。
`localAmount`	M	支付转换前的币种和金额。金额必须符合该币种的最小单位规则。

以下是将 THB 转换为 HKD、获取转换后交易金额的示例：

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/evo.e-commerce.FXRateInquiry \
-H 'Content-Type: application/json' \
-H 'DateTime: 2023-09-12T11:50:50+08:00' \
-H 'SignType: SHA256' \
-H 'Authorization: e3a1623b09dd71ef4c400f222e88a38e87810451231f2ba5a64cc16e16cac148' \
-H 'MsgID: M202309121694490650235' \
-d '{
    "merchantTransInfo": {
        "merchantTransID": "T309121694490650235",
        "merchantTransTime": "2023-09-12T11:50:50+08:00"
    },
    "localAmount": {
        "currency": "THB",
        "value": "500.00"
    },
    "transAmount": {
        "currency": "HKD"
    },
    "metadata": "This is a metadata"
}'

请求成功时，响应中会包含 transAmount 对象，展示转换后的交易金额和币种。

transAmount 对象详细说明：

fxRateInquiry.status：汇率查询的状态（必填），取值可为 Success 或 Failed。
fxRateInquiry.transAmount：支付经货币转换后的币种和金额（必填）。您需要在步骤 2 的 POST 支付请求中使用相同的币种和金额。

以下是请求成功的响应示例：

{
    "fxRateInquiry": {
        "evoTransInfo": {
            "evoTransID": "daf559621e9f4a9a9be8cd3a992f68b1",
            "evoTransTime": "2023-09-12T11:50:50+08:00"
        },
        "localAmount": {
            "currency": "THB",
            "value": "500.00"
        },
        "localToTransFXRate": {
            "baseCurrency": "THB",
            "date": "20230517",
            "quoteCurrency": "HKD",
            "source": "customization",
            "value": "0.2397226"
        },
        "merchantTransInfo": {
            "merchantTransID": "T309121694490650235",
            "merchantTransTime": "2023-09-12T11:50:50+08:00"
        },
        "status": "Success",
        "transAmount": {
            "currency": "HKD",
            "value": "119.86"
        }
    },
    "metadata": "This is a metadata",
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

您可以从服务端向 EVO Payment 以下接口发起 HTTP POST 请求：

/g2/v1/payment/mer/{sid}/payment

并指定以下额外参数，发起 MCP 支付。

查询参数

参数	是否必填	说明
`merchantTransID`	M	初始汇率查询的 `merchantTransInfo.merchantTransID`。

Body 参数

参数	是否必填	说明
`merchantTransInfo`	M	支付的参考信息，包括唯一的 `merchantTransID`，以及表示您发起请求时间的 `merchantTransTime`。
`transAmount`	M	支付的币种和金额。金额必须符合该币种的最小单位规则，且必须与 `paymentMethod` 中指定的金额相同。
`paymentMethod`	M	使用 `paymentMethod.type` 指定支付方式类型，例如电子钱包或银行卡支付，并携带上一步收集的相关支付信息。
`transInitiator`	M	发起交易的设备信息。
`storeInfo`	O	补充的门店信息。当您的门店在 EVO Payment 中配置了多个 MCC 时必填，用于指明本次支付使用的 MCC。
`tradeInfo`	O	当 `paymentMethod.e-wallet.paymentBrand` 为 Alipay 时必填，用于说明本次支付的详细信息。
`userInfo`	O	买家的详细信息。如能获取请传入，有助于 EVO Payment 进行反洗钱和欺诈检测，并提升支付成功率。
`validTime`	O	当 `paymentMethod.type` 为 e-wallet 时适用，表示订单的有效时间（分钟）。支付只能在该时间之前完成。如有特殊要求，请联系 EVO Payment 客户经理。
`returnURL`	O	用户完成或取消支付后，跳转回您页面的 URL。
`webhook`	O	接收通知的 URL。传入该参数后，支付成功时将收到 EVO Payment 的通知。
`metadata`	O	请求中自定义的参考信息，会在响应中原样返回。除 GET 请求外，响应中的 metadata 与请求报文中的相同；GET 响应中的 metadata 与 POST 请求报文中的相同；通知中也会携带 POST 请求中的 metadata。

以下是将 THB 转换为 USD 发起 MCP 支付的示例：

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment?merchantTransID=T309121694507588860 \
-H 'Content-Type: application/json' \
-H 'DateTime: 2023-09-12T16:33:11+08:00' \
-H 'SignType: SHA256' \
-H 'Authorization: 14d051b801973f1f18819f010bb6c7ab94117716e6d6e6e89a9ca920496f1f0f' \
-H 'MsgID: M202309121694507591175' \
-d '{
    "merchantTransInfo": {
        "merchantTransID": "T309121694507591175",
        "merchantTransTime": "2023-09-12T16:33:11+08:00"
    },
    "localAmount": {
        "currency": "THB",
        "value": "500.00"
    },
    "transAmount": {
        "currency": "USD",
        "value": "15.27"
    },
    "captureAfterHours":"0",
    "paymentMethod": {
        "type": "card",
        "card":{
            "cardInfo":{
                "cardNumber": "4761349999000039",
                "expiryDate": "3112",
                "cvc": "998"
            }
        }
    },
    "transInitiator": {
        "platform": "WEB"
    },
    "metadata": "This is a metadata",
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK"

:::tip[tip]

后续步骤取决于支付响应中是否包含 action 对象。详情请参阅 Payment 章节。

:::

Features

After Payment

Features

Authentication

Tokenization

Quickstart

Payment

After Payment

ZPK

Payment

After Payment

PaymentMethod

FXRateInquiry

Payment

Payout

Capture

Coupon Reversal

Coupon Write-off

Cancel

Refund

ZPK

DataSubmission

Cryptogram

CancelOrRefund

Notification

HealthCheck

TransactionHistoryInquiry

MerchandiseCredit

Linkpay

Retrieve Linkpay

Refund

Retrieve Linkpay Refund

Notification

Cancel or Refund

Multi-Currency Transaction ​

汇率来源设置 ​

汇率查询（FX Rate Inquiry） ​

汇率来源设置 ​

汇率查询请求 ​

多币种定价（MCP） ​

步骤 1：获取转换后的交易金额 ​

Multi-Currency Transaction

汇率来源设置

汇率查询（FX Rate Inquiry）

汇率来源设置

汇率查询请求

多币种定价（MCP）

步骤 1：获取转换后的交易金额