Dynamic Currency Conversion
The Dynamic Currency Conversion (DCC) service is implemented prior to the authorization actually taking place and through an AcceptorCurrencyConversion exchange. The Gateway will forward the conversion request to the DCC provider and will reply with and AcceptorCurrencyConversionResponse message to the terminal (host) after receiving the response from the provider. If the card is eligible for DCC, the currency conversion response will convey all information required to present the DCC offer on the terminal display. The cardholder will be given the option to decline the DCC and continue the transaction in merchant currency or to accept the conversion and continue the transaction in its own card currency. In case of DCC acceptance, the subsequent authorisation message will include transaction amount in card currency together with all conversion details returned in the corresponding AcceptorCurrencyConversionResponse message.
DCC is supported for Visa and MasterCard only.
DCC will be applicable to following transaction types:
- Purchase
- Purchase with Tip
- Purchase with Cashback
- Preauthorisation management transactions
DCC can also be used for preauthorisations. While receiving the postauthorisation the Gateway will always check if DCC was applied on the initial preauthorisation and if the DCC rate is still valid. If the DCC rate applied to the initial preauthorisation is still valid, then it will also be applied to the postauthorisation and send to the authorisation system.
If the DCC rate applied to the initial preauthorisation is expired, then the Gateway will request a new DCC rate on your behalf. This is a valid behavior as the cardholder has agreed during the initial preauthorisation that DCC will be applied to the entire preauthorisation chain.
You can also offer other options, e.g. if the cardholder is present during postauthorisation.
Please note that the majority of these options can only be used if you perform a balance inquiry before sending the postauthorisation. Otherwise, the terminal is not aware if DCC was applied to the initial preauthorisation and if the DCC rate is still valid.
The Gateway will include the DCC related info into the balance inquiry response.
Scenarios for DCC combined with preauthorisations
| Scenario | Expected behavior during completion |
|---|---|
| Opt-out from valid DCC rate | If you want to offer opt-out from DCC while performing the postauthorisation, then you need to send `CcyConvsRslt element with AccptdByCrdhldr=false in AccptrCmpltnAdvc. |
| Apply DCC rate (pre-condition: DCC rate is still valid) | If you want IPG to apply the DCC rate that was used on the initial preauthorisation, then you need to send CcyConvsRslt element with AccptdByCrdhldr=true in AccptrCmpltnAdvc. |
| Request a new DCC rate (DCC rate can be still valid or expired) | If you want to offer a new DCC rate to the cardholder, then you need to send another AccptrCcyConvsReq to the Gateway. Afterwards, the DCC rate from the AccptrCcyConvsRspn can be included by sending CcyConvsRslt element with AccptdByCrdhldr=true in AccptrCmpltnAdvc. |
| Request a new DCC rate (DCC rate can be still valid or expired) | If you want to offer a new DCC rate to the cardholder, then you need to send another AccptrCcyConvsReq to the Gateway. Afterwards, the DCC rate from the AccptrCcyConvsRspn can be included by sending CcyConvsRslt element with AccptdByCrdhldr=true in AccptrCmpltnAdvc. |
| DCC rate declined by cardholder | If you want to offer a new DCC rate to the cardholder, then you need to send another AccptrCcyConvsReq to the Gateway. If cardholder doesn't accept the new DCC rate, then you need to send CcyConvsRslt element with AccptdByCrdhldr=false in AccptrCmpltnAdvc. |
| Opt-out in case DCC rate is expired | If DCC is expired and no new DCC rate is required, then you need to send CcyConvsRslt element with AccptdByCrdhldr=false in AccptrCmpltnAdvc. |
| IPG/CAP requests new DCC rate on behalf of merchant | If DCC is expired and you expect the Gateway to request a new DCC rate on your behalf, then CcyConvsRslt element shouldn't be present in AccptrCmpltnAdvc at all. |
Message Layout
AcceptorCurrencyConversionRequestV04 - caaa.016.001.04
| Tag | Description | Presence |
|---|---|---|
Hdr/MsgFctn | Identifies the type of transaction. DCCQ - CurrencyConversionRequest | m |
Hdr/RcptPty/RmotAccs/AccsCd | One-time code. Currently only used for BLIK payments | o |
Envt/Mrchnt/LctnCtgy | Use value 'NMDC' in case the address is a service location (as needed due to Mastercard mandate AN6022). Otherwise, use value 'FIXD' or don't send this element at all | o |
Envt/Mrchnt/LctnAndCtct/PstlAdr/... | .../AdrLine street house-number,city,zip-code or house-number,street,city,zip-code Mapped to below values, if //AdrLine are not given. or .../StrtNm .../BldgNb .../TwnNm .../PstCd .../Ctry .../AddtlCtctInf | o |
Envt/POI/Cpblties/CardRdngCpblties | For terminals supporting contactless single-tap PIN requests, include one additional occurrence with value "OTHR". nexo does not support a dedicated value for this capability yet, but it is expected to be added to future releases. | o |
Envt/POI/Cpblties/CrdhldrVrfctnCpblties | See NEXO MDR | |
Envt/POI/Cpblties/OnLineCpblties | See NEXO MDR | o |
Envt/POI/Cmpnt/Tp | Only components with type "TERM" and "DVCE" are evaluated. | o |
Envt/POI/Cmpnt/Id/SrlNb | Terminal serial number | o |
Envt/POI/Cmpnt/StdCmplc/Issr | Only standard compliance entries with Issr=GBIC are evaluated. | o |
Envt/POI/Cmpnt/StdCmplc/Id | Terminal approval number Used for GIRO-Card transactions. | o |
Envt/Card/PrtctdCardData/CnttTp | EVLP | o |
Envt/Card/PrtctdCardData/... EnvlpdData/Rcpt/KEK | see chapter 'Protected Card Data in NEXO message' - contains keys used for encryption | o |
Envt/Card/PrtctdCardData/... EnvlpdData/NcrptdCntt | see chapter 'Protected Card Data in NEXO message' - contains encyrpted content of plain card data | o |
Envt/Card/IssrBIN | First 6/8 digits (depending on card number length) are needed to identify card in currency conversion solution | m |
Envt/Card/CardCtryCd | ISO 3166 – 1, alphanumeric or numeric | o |
Envt/Card/CardCcyCd | ISO 3166 – 1, alphanumeric or numeric | o |
Envt/Card/CardBrnd | Contains brand of the card with one of: A-Amex B-BCMC C-Carte Bancaire (France) CONECS - Conecs lunch card (France) D-Diners E-Maestro F-EFTPOS (Australia) G-Giro J-JCB K – BLIK (Poland) L-ELV (Germany) M-Mastercard MOBILEPAY - MobilePay N-VISA Electron P-VPAY SWISH - Swish U-UPI V-Visa VIPPS - Vipps X-Flexecash | m |
Envt/Card/PmtAcctRef | Token value. Only used when payment is initiated with Token number (manually read or received from ECR) instead of card data. Other Card subfields must not be present in this case. | o |
Envt/PmtTkn/TknRqstr/PrvdrId | Identifies the provider of the token: IPG, IPGTA. Not required in request message. | o |
Cntxt/PmtCntxt/AttndncCntxt | Merchant was (not) present. If AttndncCntxt=UATT, then terminal needs to send as well. | o |
Cntxt/PmtCntxt/CardDataNtryMd | For Payment with Token - CDFL. For other payments, value indicates the entry mode of the card data (TAGC, PHYS, BRCD, MGST, CICC, DFLE, CTLS, ECTL) | m |
Cntxt/PmtCntxt/FllbckInd | Indicates a problem with the chip FFLB - FallbackAfterFailure SFLB - FallbackAfterSuccess NFLB - NoFallback | o |
Cntxt/PmtCntxt/TxChanl | Type of the communication channels used by the cardholder to the acceptor system. Only below values will be considered: MAIL - Mail order TLPH -Telephone order | o |
Cntxt/SaleCntxt/SaleID | Identification of the sale system. Should not be populated on stand-alone terminals, only on terminals integrated with sale systems. | o |
Cntxt/SaleCntxt/SaleRefNb | Transaction identifier assigned by the sale system. Referred to as Merchant Reference 1. Maximum size 15. | o |
Cntxt/SaleCntxt/CshrId | Identification of the cashier who initiated the transaction on the sale system. Should not be populated on stand-alone terminals, only on terminals integrated with sale systems. | o |
Tx/TxCaptr | FALSE | m |
Tx/TxTp | CRDP - Card payment DEFR - Deferred Payment RESA - Reservation RFND - Refund | m |
Tx/AddtlSvc | DCCV - DCC | o |
Tx/MrchntCtgyCd | Merchant category code | m |
Tx/SaleRefId | Required in Pre-authorization messages (initial and update). IPG will ignore the value and generate its own pre-authorization ID which will be returned in the same tag and also in RcptTxId. | o |
Tx/TxId/TxRef | Reference-ID of transaction. Used as trace-number, format 999999 Format: Max6Numeric Other length: e.g. for pre-authorizations done with an alternative payment method (APM): Max35Alpha-Numeric or 12 digits with leading zeroes | m |
Tx/TxId/TxDtTm | Date & time of transaction | m |
Tx/InitrTxId | Merchant Reference 1. | o |
Tx/RcncltnId | Reconciliation ID, this transaction belongs to. | m |
Tx/TxDtls/TtlAmt | Total amount in merchant currency. DCC: Total amount in target currency (copied from dcc_response.Tx/CcyConvsRslt/ConvsDtls/RsltgAmt) | m |
Tx/TxDtls/AmtQlfr | INCR - Incremental amount for reservation DECR - Decremental amount for reservation RESD - total reserved amount | o |
Tx/TxDtls/DtldAmt/ AmtGoodsAndSvcs | Amount of purchased goods or services. Should only be included when it is different than the total amount. For DCC: amount in target currency | o |
Tx/TxDtls/DtldAmt/Grtty | Gratuity amount. Should only be included when gratuity (tip) is included in total amount. For DCC: amount in target currency | o |
Tx/TxDtls/DtldAmt/CshBck | Cashback amount. For DCC: amount in target currency | o |
Tx/TxDtls/VldtyDt | Reservation validity date. Will be present in initial and update reservation. | o |
Tx/TxDtls/AcctTp | Type of cardholder account used for the transaction. Values: CHCK, CRDT, CDBT, SVNG etc. (more possible values) In case of Default value, this tags will not be present. | o |
Tx/TxDtls/ICCRltdData | EMV-data according to EMVCo spec | o |
Tx/MrchntRefData | Merchant Reference 2 | o |
SctyTrlr/AuthntcdData | MAC . May be disabled or set to optional by a parameter configured in our gateway. If set to optional, a message without MAC is accepted and the response will not contain a MAC. | m |
AcceptorCurrencyConversionResponseV04- caaa.017.001.04
| Tag | Description | Presence |
|---|---|---|
Hdr/MsgFctn | Identifies the type of transaction. | m |
Tx/TxId/TxRef | Copied from request | m |
Tx/TxId/TxDtTm | Copied from request | m |
Tx/SaleRefId | Copied from request | o |
Tx/InitrTxId | Copied from request | o |
Tx/RcncltnId | Copied from request | o |
Tx/RcptTxId | ID for this transaction generated by IPG. Will be used in subsequent related pre-authorization management transactions. Format: Max35Text For client (reseller) specific formatting: check with your client support contact | o |
Tx/TxDtls/Ccy | Copied from request | m |
Tx/TxDtls/TtlAmt | Copied from request | m |
Tx/TxDtls/VldtyDt | Reservation validity date. Will be present in initial reservation, update reservation and balance enquiry | o |
Tx/TxDtls/AcctTp | Type of cardholder account used for the transaction. Values: CHCK, CRDT, CDBT, SVNG etc. (more possible values) In case of Default value, this tags will not be present. | o |
Tx/ICCRltdData | EMV data from authorization system. | o |
`CcyConvsRslt/Rslt | ODCC - Allowed Dynamic currency conversion may be offered to the cardholder. DCCA - Assumed Transaction authorised with dynamic currency conversion. ICRD - InvalidCard The card is not valid for dynamic currency conversion. IMER - InvalidMerchant The card acceptor has not been recognised. IPRD - InvalidProduct Dynamic currency conversion service cannot be offered for this card product. IRAT - NoRate Exchange rates are not available. NDCC - NotAvailable Dynamic currency conversion is not available for other reason. REST - Restriction Conversion accepted for the requested amount exclusively. CATG - Catalogue Conversion accepted for a range of amounts. | m |
CcyConvsRslt/ConvsDtls/... TrgtCcy/AlphaCd | Alpha currency code (ISO 4217, 3 alphanumeric characters) of target (cardholder billing) currency. | o |
CcyConvsRslt/ConvsDtls/... TrgtCcy/NmrcCd | Numeric currency code (ISO 4217, 3 numeric characters) of target (cardholder billing) currency. | o |
CcyConvsRslt/ConvsDtls/... TrgtCcy/Dcml | Maximal number of digits after the decimal separator for the target (cardholder billing) currency. | o |
CcyConvsRslt/ConvsDtls/... RsltgAmt | Amount converted in the target currency, including additional charges. | o |
CcyConvsRslt/ConvsDtls/... XchgRate | Exchange rate, expressed as a percentage, applied to convert the original amount into the resulting amount. | o |
CcyConvsRslt/ConvsDtls/... QtnDt | Quotation date - Date and time at which the exchange rate has been quoted. | o |
CcyConvsRslt/ConvsDtls/... VldUntil | Validity limit of the exchange rate. | o |
CcyConvsRslt/ConvsDtls/... SrcCcy/AlphaCd | Alpha currency code (ISO 4217, 3 alphanumeric characters) of source (merchant) currency. | o |
CcyConvsRslt/ConvsDtls/... SrcCcy/NmrcCd | Numeric currency code (ISO 4217, 3 numeric characters) of source (merchant) currency. | o |
CcyConvsRslt/ConvsDtls/... SrcCcy/Dcml | Maximal number of digits after the decimal separator for the source (merchant) currency. | o |
CcyConvsRslt/ConvsDtls/... OrgnlAmt/ActlAmt | Amount to be converted | o |
CcyConvsRslt/ConvsDtls/... OrgnlAmt/ComssnDtls/Amt | Commission expressed as an amount of money. | o |
CcyConvsRslt/ConvsDtls/... OrgnlAmt/MrkUpDtls/Rate | Commission expressed as a percentage. | o |
Tx/Rspn | APPR - approved DECL - declined PART - partially approved | m |
SctyTrlr/AuthntcdData | MAC . May be disabled or set to optional by a parameter. If set to optional, a message without MAC is accepted and the response will not contain a MAC. | o |
In case of an accepted DCC offer, the transaction must contain the following amounts/currencies:
This applies to sale/preauthorization transactions (AcceptorAuthorizationRequest) as well as to Completions (AcceptorCompletionAdvice)
| Tag | Description | Presence |
|---|---|---|
TxDtls/TtlAmt | Total amount of transaction in foreign/card currency (including all detailed amounts). | m |
TxDtls/DtldAmt/CshBck | Cashback amount in original/merchant currency. | c |
TxDtls/DtldAmt/Grtty | Tip amount in original/merchant currency. | c |
TxDtls/CcyConvsRslt/RsltgAmt | The complete amount of the transaction in foreign/card currency (equal to TtlAmt) In case of preAuth completion, this is the amount which has to be transferred, not the reserved amount. | m |
TxDtls/CcyConvsRslt/OrgnlAmt/ActlAmt | The complete amount of the transaction in the original/merchant currency. In case of preAuth completion, this is the amount which has to be transferred, not the reserved amount. | m |
Updated 2 months ago
