Last update 20/04/2016

2. DCC details request via Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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
Description
Format
AMOUNT
The original amount to be converted (amount x 100)
Numeric
BIN
The first digits (BIN number) of the customer’s card
6 numbers
CONVCCY
The currency the amount should be converted to
3 alphanumeric characters
CURRENCY
The original currency of the amount
3 alphanumeric characters
ORDERID
The merchant's unique order reference
Alphanumeric
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>

 

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data