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.
| Parameter | Required | Description |
|---|---|---|
baseCurrency | M | Code of the currency that is being converted from. |
quoteCurrency | M | Code 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:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/FXRateInquiry? baseCurrency=USD"eCurrency=IDR paymentMethod \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE"The response includes the FX Rate in a localToTransFXRate object, containing the following fields:
baseCurrency: The code of the currency that is being converted from.quoteCurrency: The code of the currency that is being converted to.date: The value of the FX rate, accurate to 7 decimal places.value: The date for the exchange rate processing.
For more details, see the EVO Cloud API Specification.
Here is an example of the response:
1.{
2. "fxRateInquiry": {
3. "localToTransFXRate": {
4. "baseCurrency": "IDR",
5. "date": "20230912",
6. "quoteCurrency": "USD",
7. "value": "0.0000688"
8. }
9. },
10. "result": {
11. "code": "S0000",
12. "message": "Success"
13. }
14.}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.
| Parameter | Required | Description |
|---|---|---|
merchantTransInfo | M | The reference for the FX Rate Inquiry, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
transAmount | M | The currency after conversion for the payment. The value must follow the currency's minor unit. |
localAmount | M | The 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:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/evo.e-commerce.FXRateInquiry \
2.-H 'Content-Type: application/json' \
3.-H 'DateTime: 2023-09-12T11:50:50+08:00' \
4.-H 'SignType: SHA256' \
5.-H 'Authorization: e3a1623b09dd71ef4c400f222e88a38e87810451231f2ba5a64cc16e16cac148' \
6.-H 'MsgID: M202309121694490650235' \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "T309121694490650235",
10. "merchantTransTime": "2023-09-12T11:50:50+08:00"
11. },
12. "localAmount": {
13. "currency": "THB",
14. "value": "500.00"
15. },
16. "transAmount": {
17. "currency": "HKD"
18. },
19. "metadata": "This is a metadata"
20.}'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:
fxRateInquiry.status: The status of the FX Rate Inquiry (required). The value can beSuccessorFailed.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:
1.{
2. "fxRateInquiry": {
3. "evoTransInfo": {
4. "evoTransID": "daf559621e9f4a9a9be8cd3a992f68b1",
5. "evoTransTime": "2023-09-12T11:50:50+08:00"
6. },
7. "localAmount": {
8. "currency": "THB",
9. "value": "500.00"
10. },
11. "localToTransFXRate": {
12. "baseCurrency": "THB",
13. "date": "20230517",
14. "quoteCurrency": "HKD",
15. "source": "customization",
16. "value": "0.2397226"
17. },
18. "merchantTransInfo": {
19. "merchantTransID": "T309121694490650235",
20. "merchantTransTime": "2023-09-12T11:50:50+08:00"
21. },
22. "status": "Success",
23. "transAmount": {
24. "currency": "HKD",
25. "value": "119.86"
26. }
27. },
28. "metadata": "This is a metadata",
29. "result": {
30. "code": "S0000",
31. "message": "Success"
32. }
33.}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
| Parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial FX Rate Inquiry. |
Body Parameters
| Parameter | Required | Description |
|---|---|---|
merchantTransInfo | M | The reference for the payment, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
transAmount | M | The 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. |
paymentMethod | M | Use 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. |
transInitiator | M | Information about the device that initiates the transaction. |
storeInfo | O | Supplemental store information. Required when your store is assigned multiple MCCs in EVO Cloud to indicate which MCC you are using for this payment. |
tradeInfo | O | Required when paymentMethod.e-wallet.paymentBrand is Alipay to indicate detailed information about this payment. |
userInfo | O | Detailed information about the buyer. Specify this if available to help EVO Cloud with laundering and fraud detection, and to increase payment success rates. |
validTime | O | Applied 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. |
returnURL | O | The URL to redirect your customer back to after they complete or cancel the payment. |
webhook | O | The URL to receive notifications. Specify this to get notifications from EVO Cloud after the payment succeeds. |
metadata | O | Self-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
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment?merchantTransID=T309121694507588860 \
2.-H 'Content-Type: application/json' \
3.-H 'DateTime: 2023-09-12T16:33:11+08:00' \
4.-H 'SignType: SHA256' \
5.-H 'Authorization: 14d051b801973f1f18819f010bb6c7ab94117716e6d6e6e89a9ca920496f1f0f' \
6.-H 'MsgID: M202309121694507591175' \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "T309121694507591175",
10. "merchantTransTime": "2023-09-12T16:33:11+08:00"
11. },
12. "localAmount": {
13. "currency": "THB",
14. "value": "500.00"
15. },
16. "transAmount": {
17. "currency": "USD",
18. "value": "15.27"
19. },
20. "captureAfterHours":"0",
21. "paymentMethod": {
22. "type": "card",
23. "card":{
24. "cardInfo":{
25. "cardNumber": "4761349999000039",
26. "expiryDate": "3112",
27. "cvc": "998"
28. }
29. }
30. },
31. "transInitiator": {
32. "platform": "WEB"
33. },
34. "metadata": "This is a metadata",
35. "webhook": "https://YOUR_COMPANY.com/WEBHOOK"TIP
Your next steps depend on whether the payment response contains an action object. See chapter Payment for more details.
