DCC

DCC (Dynamic Currency Conversion) is a technological solution that allows customers to perform transactions using a bank card when travelling abroad. These transactions can be in any currency other than the domestic currency of the country in which the transaction takes place. This includes payments, reversals, captures, and refunds.

Some merchant customers pay for goods and services in the currency of the merchant. In order to process payments in the customer's preferred currency, a DCC service must be used. This service allows payments to be processed in the customer's card currency.

DCC functionality works only for non-local JCC cards (the customer's bank card differs from the currency used for payment for the merchant's order).

Below is the description of possible scenarios of using DCC.

Scenarios

Redirect Payment using DCC

The below scheme describes the scenario of using DCC when the card data are collected on the side of Payment Gateway. In this scenario, the currency of the customer's bank card differs from the currency used for payment for the merchant's order.

1. The customer has added items to their shopping cart and proceeds to payment by clicking on the appropriate element on the merchant's page.
2. The merchant performs standard order registration process by sending register.do request.
3. Payment Gateway verifies the merchant's details and permissions, sends a unique order number and a link to the payment page.
4. The merchant redirects the customer to the payment page.
5. The customer enters the card data or selects a stored credential.
6. Payment Gateway interacts with DCC service to calculate conversion for currency of the customer’s card.
7. Payment Gateway displays the DCC payment option on the payment page.
8. The customer chooses the payment option in the currency of their card, including DCC conversion calculation, and clicks on the payment button.
9. Payment Gateway performs the payment.
10. Payment Gateway redirects the customer to the final page.
11. The customer clicks the Back to shop element.
12. The customer is redirected to the merchant's website.
13. The customer’s browser requests the payment result.
14. The merchant requests payment status by sending the getOrderStatusExtended.do request.
15. The Payment Gateway returns the order information.
16. The merchant displays the payment result to the customer.

Direct Payment using DCC

The below scheme describes the scenario of using DCC when the merchant has its own payment page to collect card data natively through its web site. In this scenario, the currency of the customer's bank card differs from the currency used for payment for the merchant's order.

1. The customer has added items to their shopping cart and proceeds to payment by clicking on the appropriate element on the merchant's page.
2. Online store redirects the customer to the payment page.
3. The customer enters the card data or selects a stored credential.
4. The merchant sends the DCC calculation request calculate.do to the Payment Gateway specifying the amount, currency, and (optionally) merchantLogin.
5. Payment Gateway interacts with DCC Server to calculate conversion for currency of the customer’s card and assigns a dccUuid calculation identifier to the original DCC data calculation request.
6. Payment Gateway stores the calculation under the generated dccUuid identifier and transmits the result of the calculation to the online store in the dccData block.
7. The online store displays an additional payment option in the currency of the customer's card, including DCC conversion calculation.
8. The customer chooses the payment option in the currency of their card, including DCC conversion calculation, and clicks on the payment button.
9. The merchant sends instantPayment.do request passing DCC data received in the dccData block on step 6.
10. Payment Gateway performs 3DS authentication of the customer using the currency of the DCC conversion calculation and performs the payment.
11. Payment Gateway sends the payment result to the Online Store.
12. Online Store redirects the customer to the final page.
13. The customer clicks the Back to shop element.
14. The customer is redirected to the merchant's website.
15. The customer’s browser requests the payment result.
16. The merchant requests payment status by sending the getOrderStatusExtended.do request.
17. Payment Gateway returns the order information.
18. The merchant displays the payment result to the customer.

Reversal using DCC

The below scheme describes the scenario of reversal for a two-phase order payed with DCC. To make partial reversals, you need to have a special permission.

1. The merchant initiates reversal by sending the reverse.do request to the Payment Gateway and specifying the reversal amount.

   If the currency parameter is specified in the request, this currency is used for the reversal. If the currency is not specified, the original currency of the order is used by default.

2. Payment Gateway interacts with DCC Server to calculate conversion for currency using dccUuid parameter of the initial payment.

3. Payment Gateway sends the reversal result to the merchant.

Capture using DCC

The below scheme describes the scenario of completion of a two-phase order payed with DCC (capture of the funds).

1. The merchant initiates capture by sending the deposit.do request to the Payment Gateway and specifying the capture amount.

   If the currency parameter is specified in the request, this currency is used for the capture. If the currency is not specified, the original currency of the order is used by default.

2. Payment Gateway interacts with DCC Server to calculate conversion for currency using dccUuid parameter of the initial payment.

3. Payment Gateway sends the capture result to the merchant.

Refund using DCC

The below scheme describes the scenario of refund for an order payed with DCC.

1. The merchant initiates a refund by sending the refund.do request to the Payment Gateway and specifying the refund amount.

   If the currency parameter is specified in the request, this currency is used for the refund. If the currency is not specified, the original currency of the order is used by default.

2. Payment Gateway interacts with DCC Server to calculate conversion for currency using dccUuid parameter of the initial payment.

3. Payment Gateway sends the refund result to the merchant.

API calls

DCC calculate

To calculate and recieve DCC data use the https://gateway-test.jcc.com.cy/payment/rest/dcc/calculate.do request.

When sending request, you should use header: Content-Type: application/json

Request parameters

Response parameters

Below are the parameters of the object in dccData array.

Examples

Request example

curl --request POST \
  --url https://gateway-test.jcc.com.cy/payment/rest/dcc/calculate.do \
  --header 'content-type: application/json' \
  --data '{
    "pan":"4000001111111118",
    "amount":"1000000",
    "currency": "978",
    "merchantLogin":"test_merchant_login", 
    "language":"en", 
    "username": "test_user", 
    "password": "test_user_password"
}'

Response example

{
    "errorCode": 0,
    "dccUuid": "bc42df3d-75ad-40bc-8249-4997fc8f914a",
    "originalAmount": 1000000,
    "dccData": [
        {
            "dccAmount": 1518300,
            "dccAmountFormatted": "15183.00",
            "dccCurrencyCode": 702,
            "dccCurrencyCodeAlpha": "SGD",
            "dccConversionRate": "0.6586",
            "dccDirectConversionRate": "1.5183",
            "dccFeePercentage": "3.00",
            "additionalParams": {}
        }
    ]
}