1. Introduction

Electronic Dynamic Currency Conversion (DCC) enables your customers to choose between their preferred currency and your default currency. It's an option that can be enabled on your request.

With DirectLink, the DCC process is split up in two stages:

  1. You request the DCC details, based on the customer's card BIN number
  2. You request the payment with a general DirectLink call, including some extra parameters (to provide the chosen DCC details obtained earlier on)

2. DCC details request via Worldline DCC API

If you want to retrieve the DCC offer for the card number used by the customer, you must use the DCC API. This API will return an XML document containing the DCC values that Worldline retrieved from the DCC provider.

There are a few conditions if you want to use the DCC API:
  • The DirectLink (server-to-server) option needs to be enabled in your account
  • The DCC option needs to be enabled in your account
  • You should be able to support the card brand for which you request the DCC rates; e.g. you can't request DCC rates for a VISA credit card if you don't support VISA payments or if you don't support DCC payments for this card type.

2.1 API URL and parameters

The following URLs are used to call the Worldline DCC API:

  • TEST: https://ogone.test.v-psp.com/ncol/test/getDCCRates.asp
  • PROD: https://secure.ogone.com/ncol/prod/getDCCRates.asp

To receive a valid DCC rate response, the following parameters must be sent to the DCC API:

Field / Format Description

AMOUNT

Numeric

The original amount to be converted (amount x 100)

BIN

6 numbers

The first digits (BIN number) of the customer’s card

CONVCCY

3 alphanumeric characters

The currency the amount should be converted to

CURRENCY

3 alphanumeric characters

The original currency of the amount

ORDERID

Alphanumeric

The merchant's unique order reference

PSPID

-

The PSPID of the merchant

PSWD

-

Password of the API-user

SHASIGN

-

Digest (hashed string) to authenticate the data

USERID

-

Userid for multi-users account

If any of these fields are not properly provided, an error will occur.

Note:

  • Either the BIN or the CONVCCY parameter is mandatory, as it needs to be determined what currency the amount should be converted into. The BIN is mandatory if no CONVCCY is provided. The CONVCCY is mandatory if no BIN was provided, and is ignored otherwise. This means that if both are provided, the BIN will have the priority over the CONVCCY, and the new currency is determined based on this BIN. In any case, we strongly recommend you to use the BIN rather than the CONVCCY parameter.
  • The order reference provided with the ORDERID parameter is a mandatory parameter that must be unique. It is important that this reference will be used later on again when processing the actual transaction, since the DCC rates will be attached to this specific order. The same order reference should be used if several DCC rate queries are done for the same transaction.

2.2 SHA calculation

Below we display how the SHA calculation for the DCC request works. Even though the principle is the same as for the pre-payment SHA, they are not to be confused ; these are two separate processes.

Fields
AMOUNT: 1.50 --> 150
BIN: 411111
CURRENCY: EUR
ORDERID: order00001
PSPID: MyPSPID
PSWD: MySecretPswd51
USERID: MyAPIUser

SHA passphrase (in Technical information):
MySecretSig1875!?

String to hash
AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CURRENCY=EURMySecretSig1875!?
ORDERID=order00001MySecretSig1875!?PSPID=MyPSPIDMySecretSig1875!?PSWD=MySecretPswd51
MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!?

Resulting digest (SHA-1):
EFA8DD0C297CBA45DD7ADBEAF7CA4699C8F3C19B

Note: If you want to provide both the BIN and the CONVCCY parameter, both should be hashed, even though only the BIN will be taken into account in the process.

Fields:
AMOUNT: 1.50 --> 150
BIN: 411111
CONVCCY: JPY
CURRENCY: EUR
ORDERID: order00001
PSPID: MyPSPID
PSWD: MySecretPswd51
USERID: MyAPIUser

SHA passphrase (in Technical information):
MySecretSig1875!?

String to hash:
AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CONVCCY=JPYMySecretSig1875!?
CURRENCY=EURMySecretSig1875!?ORDERID=order00001MySecretSig1875!?PSPID=MyPSPID
MySecretSig1875!?PSWD=MySecretPswd51MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!?

Resulting digest (SHA-1):
3AA6212395739EA34C0853DB060B4B290EAB3422

2.3 API response

The response of the API call is always an XML structured document containing all information needed to proceed to the second stage of the transaction process.

2.3.1 Successful response

If the DCC rates were successfully obtained, the XML will have the following format:

<dccResponse>
<orderid></orderid> -> Merchant's unique order reference (alphanumeric)
<commPerc></commPerc> -> Commission percentage (numeric)
<convAmt></convAmt>
-> Amount after the conversion (x 100)
<convCcy></convCcy>
-> Conversion currency (3 chars)
<reference></reference> -> DCC reference (can be empty)
<exchRate></exchRate> -> Exchange rate (numeric)
<exchRateSource></exchRateSource> -> Source that has provided the DCC rates
<exchRateTS></exchRateTS> -> Timestamp of DCC rates (DateTime)
<marginPerc></marginPerc> -> Margin percentage (numeric)
<valid></valid> -> Validity of the offer (in hours) (numeric)
</dccResponse>

The timestamp of when the DCC rates were fetched, are provided in the default XML DateTime datatype, which is the following form “YYYY-MM-DDThh:mm:ss”, where:

  • YYYY indicates the year
  • MM indicates the month
  • DD indicates the day
  • T indicates the start of the required time section
  • hh indicates the hour
  • mm indicates the minute
  • ss indicates the second

2.3.2 Erroneous response

If something went wrong during the processing of the DCC API call, or for any technical reason (e.g. the DCC provider is not reachable, the data provided is not correct, etc.) an error occurs through the XML response. An erroneous DCC API call has the following format:

<dccResponse>
<error>
<code></code> -> Error code (numeric)
<desc></desc>
-> Error description (string)
</error>

</dccResponse>

3. DCC Payment request

After you've obtained the possible DCC details and displayed this to the customer, the customer should have the choice whether or not to use it, e.g. pay in his own currency (a conversion happens between his own card currency and the merchant's (your) currency) or pay in your default currency (no currency conversion will be done).

Below we explain the case when the customer has chosen to pay in his own currency, which means he will make use of the proposed currency conversion. This is the most advanced case since you will be required to add additional parameters to the DirectLink request, in order to provide the chosen DCC values.

In both cases though (DCC accepted or not), you're obliged to provide a common additional parameter which is the DCC indicator. This DCC indicator indicates whether or not the customer accepted the DCC proposal.

3.1 Parameters

The parameters that the merchant has to provide are the following:

Field / Format / * if mandatory Description

DCC_COMMPERC

Numeric

Commission percentage

DCC_CONVAMOUNT*

Numeric

Converted amount

DCC_CONVCCY*

Alphanumeric, max. 3

Converted currency

DCC_EXCHRATE*

Numeric

Exchange rate

DCC_EXCHRATETS*

[yyyy-mm-dd hh:mm:ss]

Exchange rate date

DCC_INDICATOR*

0 or 1

DCC indicator (indicates whether or not the customer accepted the DCC proposal).

Possible values:
  • 0: Customer pays in the merchant’s currency (no conversion done)
  • 1: Customer pays in his own currency (conversion is accepted)
This parameter is always mandatory to indicate DCC was used for this transaction.

DCC_MARGINPERC*

Numeric

Margin percentage

DCC_REF

Alphanumeric, max. 80

Reference of the DCC

DCC_SOURCE*

Alphanumeric, max. 32

Exchange rate source

DCC_VALID*

Numeric

Exchange rate validity (expressed in hours)

ORDERID* (**)

Alphanumeric

Merchant's order reference

(** The ORDERID should match the one used during the DCC API call. If the ORDERID is not provided or does not match the one used during an API call, the transaction will be blocked.)

All of these values are provided through the Worldline DCC API when doing the DCC request (stage 1).

3.2 Expired DCC offer validity

Every DCC offer has its own validity time, which can be calculated by adding the DCC_VALID parameters (validity period expressed in hours) to the datetime value provided in DCC_EXCHRATETS. If we detect that a DCC offer was provided alongside the transaction which had already expired, there are two possible outcomes, depending on your configuration. Note that this is only relevant in case the customer accepted the DCC offer (DCC_INDICATOR = 1). If he did not accept the DCC offer it is of no importance to Worldline to review the validity of the declined offer.

The first case occurs when you've configured to block the transaction when the DCC offer has expired. Worldline then simply does so, and the general error number 50001111 is returned.

In the second case we do not block the transaction. Instead we retrieve a new DCC offer ourselves. For this we make use of the currency and amount provided to us in the original transaction, and this offer will automatically be accepted (note that the rates may be different from the expired ones you've sent).

3.3 Possible errors

Error ID
Description
50001111
General error code
50001118
Unknown or inactive PSPID
50001122
Invalid or inactive currency
50001120
Unknown currency code
50001144
Acquirer not found based on input
50001146
DCC configuration not found for PSPID + Brand
50001184
SHA mismatch
30131001
Invalid amount

There are a few possible issues when a merchant uses DCC in DirectLink. All of them speak for themselves but since we use a general error code (50001111) for some of them, some explanation is required.

Possible errors:

  • The validity of the DCC offer expired. This is calculated based on DCC_EXCHRATETS plus DCC_VALID (expressed in hours).
  • An incorrect value is used in one of the fields, e.g. DCC_INDICATOR should be 0 or 1, DCC_EXCHRATETS should be a well formatted date, DCC_CONVAMOUNT should be numeric, etc.
  • The DCC parameters provided by the merchant do not match the ones that were retrieved through the DCC API call
  • The brand of the requested card does not match the one provided in the BRAND parameter
  • The DCC option is not enabled in the merchant’s account
  • The card provided is not eligible for DCC transactions
  • Invalid currency provided through DCC_CONVCCY