DCC

DCC

Dynamic Currency Conversion (DCC) allows international consumers to choose whether to pay in local currency or their domestic currency. You can use the fx rate inquiry API to obtain the exchange rate between the transaction currency and the settlement currency.

The main process is as follows:

1. First, you need to initiate the POST FXRateInquiry API to check if the consumer's card supports DCC. Your request must include, but not limited to, the following parameters. For detailed field information, refer to the API documentation:
   • paymentMethod.type：Indicates the payment method. For card transactions, use card.
   • paymentMethod.card：Object contains the consumer's card information and terminal details. Required when paymentMethod.type is card.
   • transAmount： Object contains the transaction amount and currency in local currency.
   • merchantTransInfo：Object contains the merchant's order number.

DCC FXRateInquiry Example

curl 'https://bkk-online-uat.everonet.com/g2/v0/payment/acq/10130014/evo.offline.FXRateInquiry' \
-H 'Authorization: 7128d742d70768f76d7ece970cf34e005ca5432425d86e92421778b2646d0fad' \
-H 'DateTime: 20240306120038+0800' \
-H 'SignType: SHA256' \
-H 'Content-Type: application/json' \
-H 'MsgID: M20240306120038749' \
-d '{
    "merchantTransInfo": {
        "merchantTransID": "T20240306120038749",
        "merchantTransTime": "2024-03-06T12:00:38+08:00"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4012001037141112"
            }
        }
    },
    "transAmount": {
        "currency":"HKD",
        "value":"1.00"
    }
}'

2. Check the FXRateInquiry.status field in the EVO Cloud response. If the value is Success, it indicates that the consumer's card supports DCC. Additionally, you will receive, but not limited to, the following fields. For detailed field information, refer to the API documentation:

   • FXRateInquiry.DCCBillingAmount：Object contains the transaction amount and currency in the card billing currency.
   • FXRateInquiry.DCCBillingFXRate：Object contains the exchange rate information used to convert the transaction currency to the billing currency, including Markup.

3. When you initiate the payment using the POST Payment API, you need to include the following additional fields to indicate that this is a DCC Payment:

   • origMerchantTransInfo.merchantTransID：The order number from the original exchange rate inquiry request, which must match the merchantTransInfo.merchantTransID field you provided in step 1.
   • DCCBillingAmount：Object contains the transaction amount and currency in the card billing currency. The amount and currency must match the values in the FXRateInquiry.DCCBillingAmount object received in step 2.
   • transAmount：Object contains the transaction amount and currency in the local currency. It must match the values in the transAmount object provided in step 1.

   TIP

   Both payment and pre-authorization transactions support DCC

Example

curl 'https://hkg-online-uat.everonet.com/g2/v0/payment/acq/10130014/evo.offline.payment' \
-H 'Authorization: 3e1302773cfac47d4ed6fed4778ca5599e3632718a0a42ddeaeb7018b381fb40' \
-H 'DateTime: 20240306141103+0800' \
-H 'SignType: SHA256' \
-H 'Content-Type: application/json' \
-H 'MsgID: M20240306141103794' \
-d '{
    "origMerchantTransInfo":{
        "merchantTransID":"T20240306141044528"
    },
    "DCCBillingAmount":{
        "currency":"USD",
        "value":"0.12"
    },
    "merchantTransInfo": {
        "merchantTransID": "T20240306141103794",
        "merchantTransTime": "2024-03-06T14:11:03+08:00"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "posEntryMode":"manual",
            "pinFlag":false,
            "termReadability":"5",
            "cardInfo": {
                "cardNumber": "4012001037141112"
            }
        }
    },
    "transAmount": {
        "currency":"HKD",
        "value":"1.00"
    },
    "autoCapture": true,
    "pspInfo": {
        "mcc": "5499",
        "sponsorCode": "441378",
        "merchantID": "202106305812001",
        "terminalID":"00000001",
        "merchantName": "Test",
        "storeID": "202106305812001",
        "storeName": "Test Store",
        "street": "Test street",
        "city": "MYS",
        "postCode": "202000",
        "nation": "MYS"
    }
}'

4. Check the payment.status field in the EVO Cloud response. If the value is Captured, the transaction is successful. Otherwise, check the result.code and result.message to determine the reason for the failure.
5. If you do not receive a response from EVO Cloud, you need to call GET Payment to query the transaction result. Upon receiving the query response, also check the payment.status field to determine the result, as described in step 4. If the transaction fails, use payment.failureCode and payment.failureReason to find the reason of the failure.
6. If you included a webhook in your request, you can also get the transaction result through asynchronous notifications. Similarly, use the payment.status field to determine the result, as described in step 4.
7. Present the payment result to the consumer.