Menu

Dynamic Currency Conversion (DCC)

Introduction

This section describes the changes you must make to the WPG XML API to submit DCC eCom payments. Read it together with theWPG developer guide. The Worldpay Dynamic Currency Conversion product supports both Point of Sale DCC and Electronic DCC for eCommerce.

We provide information on what data elements to submit for a DCC payment to WPG to meet card-scheme current and future compliance requirements. This section does not cover any of the other associated changes, for example to the WPG reports.

Data Requirements

Here are the data items you must include in a payment request that includes DCC. This ensures that the request is compliant and can send the necessary information to Visa and Mastercard.

Note: The data requirements listed as 'mandatory' below are only mandatory if the customer has accepted DCC.

The data requirements are:

  • Date of transaction (day of month, month and year) (mandatory)
  • Original transaction amount (before the DCC was made) (mandatory)
  • Original transaction currency code (before the DCC was made) (mandatory)
  • Currency conversion rate used for the DCC conversion (mandatory)
  • DCC Status - provides evidence of the cardholder choice. For example, if DCC was offered to the cardholder but the cardholder declined, or if DCC could not be offered due to a technical reason. See theStatus Valuestable below.

These data items are included in a dynamicCurrencyConversion element in the WPG payment XML, as described below.

XML element: dynamicCurrencyConversion

Add the dynamicCurrencyConversion XML element under the order element to supply the data needed to meet the Visa and Mastercard requirements. Sample XML for when DCC is used:

Copied!
<dynamicCurrencyConversion status="accepted">
    <dynamicCurrencyConversionData exchangeRate="1.225671">       
        <amount value="100" currencyCode="GBP" exponent="2"/>        
        <date dayOfMonth="16" month="3" year="2020"/>    
    </dynamicCurrencyConversionData>
</dynamicCurrencyConversion>

This table describes the individual elements and attributes:

Elements/Attributes

Element/AttributeContentsComments
statusThe DCC status which provides evidence of customer choice.See theStatus Valuestable below.
exchangeRateCurrency conversion rateMust be 7 digits or 7 digits plus the decimal character. This ensures there is no inadvertent rounding up or down by our systems. If the exchange rate has more than 7 digits, then normal rounding rules apply.

Example valid values: 1234567 or 234567.8 or 1.234567
Example invalid value: 12345678
amount valueValue of transaction in original currency
amount currencyCodeCurrency code of original currency
dateDate of transactionBased on UTC. The date element must only contain dayOfMonth, month and year attributes. Any time components are ignored.

Status Values

Include a status to ensure we can meet all current and future scheme rules without the need to make further changes.

DCC Status ValueMeaning
acceptedDCC Accepted. Required; seeNotes on Status Valuesbelow.
rejectedByCustomerDCC offered, but declined by the customer. Required; seeNotes on Status Valuesbelow.
serviceUnavailableDCC Service is unavailable.
lessThanMinimumValueDCC amount is less than the minimum limit.
unsupportedLocalCardDCC is not available for the payment card – it is a local card.
unsupportedCardDCC is not available for the payment card – the card is unsupported.
noInformationAvailableNo information is available. Required; seeNotes on Status Valuesbelow.

Notes on Status Values

At least one of these is required whenever DCC is offered and the customer accepts/rejects the transaction:

  • accepted or
  • rejectedByCustomer or
  • noInformationAvailable

The status values serviceUnavailable, lessThanMinimumValue, unsupportedLocalCard and unsupportedCard are used when DCC was not offered because this level of data is available. If not, then in these scenarios noInformationAvailable must be sent.

DCC not used

If DCC has not been used (for example, the customer did not want DCC, or DCC was not available) then you must omit the dynamicCurrencyConversionData element. For example, if the customer has declined the DCC, the XML is as follows:

Copied!
<dynamicCurrencyConversion status="rejectedByCustomer" />

You must include the dynamicCurrencyConversionData element if the status is accepted. In all other cases omit the element.

paymentService DTD - Dynamic Currency Conversion

This example is an excerpt from a DTD (Document Type Definition) file.

The paymentService can have the following child elements:

  • submit: merchants submit information to the payment service like orders or batches
  • modify: merchants send modify requests to modify orders or batches
  • inquiry: merchants can inquire the status of orders or batches
  • reply: the payment service will always respond with a reply message. Only the payment service can send reply messages
  • notify: when the payment service sends merchants information about the status of an order, or order - or transfer reports, the notify element is used.

The dynamicCurrencyConversion element is one of the child elements of the submit element. These child elements are:

Copied!
ELEMENT order 
description, 
amount,
risk?,
orderContent?,
paymentMethodMask | paymentDetails | payAsOrder ),
shopper?,
shippingAddress?,
billingAddress?,
branchSpecificExtension?,
redirectPageAttribute?,
paymentMethodAttribute*,
echoData?,
statementNarrative?,
hcgAdditionalData?,
thirdPartyData?,
resultURL?,
shopperAdditionalData?,
approvedAmount?,
mandate?,
authorisationAmountStatus?,
dynamic3DS?,
(createToken|createTokenApproval)?,
orderLines?,
subMerchantData?,
dynamicMCC?,
dynamicInteractionType?,
primeRoutingRequest?,
riskData?,
additional3DSData?,
exemption?,
shippingMethod?,
productSku?,
FraudSightData?,
deviceSession?,
dynamicCurrencyConversion?)
| (info3DSecure,
session)
For combo cards only: this a debit or credit card transaction.
Copied!
<!ELEMENT comboCard EMPTY>
<!ATTLIST comboCard type (debit|credit) #REQUIRED>

<!ELEMENT localDateTimeAtPOS (date)>

<!ELEMENT session EMPTY>

<!ATTLIST session  shopperIPAddress NMTOKEN  #IMPLIED
                   id               NMTOKEN  #IMPLIED >

<!ELEMENT deviceSession (sessionId)>

<!ELEMENT dynamicCurrencyConversion (dynamicCurrencyConversionData?) >

<!ATTLIST dynamicCurrencyConversion status ( accepted |
rejectedByCustomer |
serviceUnavailable |
lessThanMinimumValue |
unsupportedLocalCard |
unsupportedCard |
noInformationAvailable) #REQUIRED

<!ELEMENT dynamicCurrencyConversionData (amount, date) >

<!ATTLIST dynamicCurrencyConversionData exchangeRate NMTOKEN #REQUIRED >