1. Features
Merchant Connect API
latest
  • latest
  • HASE
  • Version Record
  • Integration Guide
    • EC Payment
      • Merchant API
        • Overview
        • Payment
        • Payment Methods
        • Response code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
        • Features
          • Account Status Inquiry (ASI)
          • COF
          • Multi-Currency Transaction
          • Recurring
          • Smart Routing
          • Transaction Retry
          • Payout
          • Authentication
            • 3D Secure
            • FIDO Authentication
            • Authentication only
            • Authorization only
          • Tokenization
            • Gateway Tokenization
            • Create a gateway token
            • Network Tokenization
            • Pay with gateway token
            • Manage token
            • Network Token update notification
            • Card Based Network Token
    • In-store Payment
      • Merchant API（QR）
        • Payment
          • CPM
          • MPM
          • MPM static QR code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
      • Merchant API (Card)
        • ZPK
          • ZPK
        • Payment
          • Payment
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
  • API Explorer
    • API Rules
    • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
    • FXRateInquiry
      • FXRateInquiry
      • FXRateInquiry
    • Payment
      • Payment
      • Payment
      • Payment
    • Payout
      • Payout
      • Payout
    • Capture
      • Capture
      • Capture
    • Cancel
      • Cancel
      • Cancel
    • Refund
      • Refund
      • Refund
    • Cryptogram
      • Cryptogram
      • Cryptogram
    • Cancel or Refund
      • Cancel or Refund
      • Cancel or Refund
    • Notification
      • Notification for PaymentMethod
      • Notification for Payment
      • Notification for Capture
      • Notification for Cancel
      • Notification for Refund
      • Notification for DataSubmission
      • Notification for MPM Static QR Code
      • Notification for Token Status Update
      • Notification for Settlement
      • Notification for Reversal
      • Notification for Cryptogram
      • Notification for Payout
    • Appendix
      • Result Code
      • Payment Brands
      • Payment Method Variant
      • Currency list
      • Country and region list
      • Product Code
    • HealthCheck
      • HealthCheck
    • Coupon Write-off
      • Coupon Write-off
    • Coupon Reversal
      • Coupon Reversal
    • ZPK
      • ZPK
latest
  • latest
  • HASE
  1. Features

Multi-Currency Transaction

It is only applicable to EC Scenario.
In online transactions, merchants often deal with users from different countries. When a transaction occurs, users typically prefer to use their local currency for the transaction. Therefore, EVO Cloud offers two features, FX Rate Inquiry and Multi-Currency Price (MCP), to meet the needs of merchants.

FX rate source setting#

In the EVO Cloud portal, you can configure the sources of FX Rate used for each scenario. The rate sources are divided into two categories: EVO Cloud FX Rate and Acquirer FX Rate.
Under the EVO Cloud FX Rate, you can further specify rates for different card schemes, including Visa, Mastercard, and JCB. Additionally, EVO Cloud supports automatic selection of the Priority FX Rate. For more information, please refer to the EVO Cloud Portal User Manual.
If you have configured the rate source as Acquirer FX Rate, please note that after setting up the exchange rates in the EVO Cloud portal, you may need to wait for up to 5 minutes before the rates can be used in API calls.

FX Rate Inquiry#

The service enables the merchant to receive a daily FX rate and use it to re-quote its products. The acquirer can define the FX rate source or setup the customized FX Rate and markup.

FX rate source setting#

In the EVO Cloud portal, you can configure the sources of exchange rates used for FX Rate Inquiry. The rate sources are divided into two categories: EVO Cloud FX Rate and Acquirer FX Rate. Under the EVO Cloud Rates FX Rate, you can further specify rates for different card schame, including Visa, Mastercard, and JCB. Additionally, EVO Cloud supports automatic selection of the Priority FX Rate. For more information, please refer to the EVO Cloud Portal User Manual.

FX rate inquiry request#

From your server, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/FXRateInquiry
and specify the additional parameters below.
ParameterRequiredDescription
baseCurrencyMCode of the currency that is being converted from.
quoteCurrencyMCode of the currency that is being converted to.
If the rate source is EVO Cloud FX Rate, you can query the FX rates for any two currency pairs. However, if the rate source is Acquirer Rate, you will need to configure the corresponding rates within the EVO Cloud portal before you can access them via the API.
Here is an example of requesting the API without any query parameter:
The response includes the FX Rate in a localToTransFXRate object, containing the following fields:
1.
baseCurrency: The code of the currency that is being converted from.
2.
quoteCurrency: The code of the currency that is being converted to.
3.
date: The value of the FX rate, accurate to 7 decimal places.
4.
value: The date for the exchange rate processing.
For more details, see the EVO Cloud API Specification.
Here is an example of the response:

Multi-Currency Price (MCP)#

Step 1: Get the converted transaction amount#

From your server, you can make an HTTP POST request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/FXRateInquiry
and specify the additional parameters below.
ParameterRequiredDescription
merchantTransInfoMThe reference for the FX Rate Inquiry, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request.
transAmountMThe currency after conversion for the payment. The value must follow the currency's minor unit.
localAmountMThe currency and value before conversion for the payment. The value must follow the currency's minor unit.
If the rate source is EVO Cloud FX Rate, you can query the FX rates for any two currency pairs. However, if the rate source is Acquirer Rate, you will need to configure the corresponding rates within the EVO Cloud portal before you can access them via the API.
Here is an example of get converted transaction from THB to HKD:
If the request is successful, you will receive a response with a transAmount object that shows the converted transaction amount and currency.
Details about the transAmount Object:
1.
fxRateInquiry.status: The status of the FX Rate Inquiry (required). The value can be Success or Failed.
2.
fxRateInquiry.transAmount: The currency and value after currency conversion for the payment (required). You need to use the same currency and value in the POST payment in Step 2.
Here is an example of a successful response:
From your server, you can make an HTTP POST request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/payment
and specify the additional parameters below to make a MCP payment.
Query Parameters
ParameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the initial FX Rate Inquiry.
Body Parameters
ParameterRequiredDescription
merchantTransInfoMThe reference for the payment, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request.
transAmountMThe currency and value of the payment. The value must follow the currency's minor unit. This value must be the same as the value specified in paymentMethod.
paymentMethodMUse paymentMethod.type to specify different payment method types, such as e-wallet or card payment, with the relevant payment information collected in the previous step.
transInitiatorMInformation about the device that initiates the transaction.
storeInfoOSupplemental store information. Required when your store is assigned multiple MCCs in EVO Cloud to indicate which MCC you are using for this payment.
tradeInfoORequired when paymentMethod.e-wallet.paymentBrand is Alipay to indicate detailed information about this payment.
userInfoODetailed information about the buyer. Specify this if available to help EVO Cloud with laundering and fraud detection, and to increase payment success rates.
validTimeOApplied when paymentMethod.type is e-wallet to indicate the effective time (in minutes) of the order. The payment can only be executed before this time. Contact your EVO Cloud account manager for special requirements.
returnURLOThe URL to redirect your customer back to after they complete or cancel the payment.
webhookOThe URL to receive notifications. Specify this to get notifications from EVO Cloud after the payment succeeds.
metadataOSelf-defined reference information specified in the request, echoed back in the response. The metadata in the response is the same as in the request message, except for GET requests. In the GET response, it matches the POST request message metadata. Notifications will also carry the same metadata from the POST request.
Here is an example of making a THB convert to USD MCP payment
tip
Your next steps depend on whether the payment response contains an action object. See chapter Payment for more details.
Previous
COF
Next
Recurring
Built with