On This Page

Visa Currency Conversion Implementation Guide

This section describes how to use this guide and where to find further information.
Audience and Purpose
This document is for Visa Acceptance Platform merchants who want to implement Currency Conversion as part of their Visa Acceptance Platform solution.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional processor-specific versions of this guide and additional technical documentation.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.11.01

Initial release.

Terminology

Dynamic Currency Conversion (DCC)
Service where the payment application performs a DCC eligibility and currency conversion service request during checkout, prior to an individual transaction authorization. If the transaction is eligible for DCC, the price is converted from the local pricing currency to the cardholder's billing currency for eligible transactions and the consumer is presented with a choice to pay in the merchant's local pricing currency or in the billing currency of their credit card.
DCC billing currency
Currency in which a card is denominated and in which transactions are posted in the cardholder’s account.
DCC capture service
The DCC capture of an authorized DCC transaction. A capture can be cancelled.
DCC markup
The commission added to the transaction price at the time of the currency conversion.
DCC offer
The display of pricing options to the cardholder. The DCC offer must include disclosures as per Visa and Mastercard rules for DCC transactions. For example, an offer should identify the price in both the local pricing currency and the billing currency of the credit card, the exchange rate used to do the conversion, and any markups.
DCC offer service
The DCC qualification and currency conversion service.
DCC payment amount
Amount of the transaction in the cardholder’s billing currency. The DCC payment amount is calculated using the wholesale exchange rate including the DCC markup.
DCC refund
The DCC refund of a captured DCC transaction which results in a refund to the customer. This can be full or partial refund. A refund can also be cancelled.
Exchange rate
Factor used to convert an amount in one currency to an amount in another currency. The exchange rate used for the DCC service is a wholesale exchange rate including a DCC markup.
Local pricing currency
The currency that a merchant uses for pricing your goods and in which transactions are typically submitted for processing.
Margin rate percentage
DCC markup.
Multi-currency pricing (MCP)
Service where a website is repriced in the currency of the cardholder.
Original amount
Amount of the transaction in your local pricing currency.

Introduction to Visa Currency Conversion

Dynamic Currency Conversion (DCC) enables you to offer international customers their choice of payment currency when their billing currency differs from your local pricing currency. To use DCC, you and your acquiring bank must both be able to accept the cardholder's billing currency.
Visa and Mastercard both support currency conversion. These card networks regulate DCC to ensure that cardholders are aware of conversion rates and markups at the time of DCC transactions.

Dynamic Currency Conversion (DCC)

Dynamic Currency Conversion (DCC) makes international commerce more convenient for customers. For example, consider this scenario:
  1. A European cardholder uses a card billed in Euros (EUR) to purchase a box of chocolates priced at 150.00 in Australian dollars (AUD) from an online merchant based in Australia.
  2. At checkout, the merchant offers the cardholder the option to pay in the EUR currency.
  3. The merchant uses DCC to convert the transaction amount from 150.00 AUD to 109.04 EUR.
  4. The merchant presents the converted transaction amount in the EUR currency to the cardholder. The exchange rate of 0.73 (1 AUD = 0.73 EUR) includes a 3% DCC markup over the wholesale exchange rate. The merchant must disclose the 3% markup to the cardholder.
  5. The cardholder chooses DCC and agrees to pay 109.04 EUR for the box of chocolates.

Multi-Currency Pricing (MCP)

Multi-currency pricing (MCP) enables you to display charges and process transactions in multiple currencies based on the cardholder's location or preference. You can use MCP to manage revenue streams in a variety of currencies for any international industry including e-commerce, SaaS, travel, and finance.
MCP is not currently available. For more information about this feature and its planned release, reach out to your
Cybersource
 representative.

Requirements and Limitations

This section describes the prerequisites, limitations, and acquirer-specific best practices of DCC.

Requirements

Contact your acquirer to register for this feature. Contact your
Cybersource
 account representative and customer service in order to have your account configured to use this feature.
You must meet the payment card company rules for DCC. This includes:
  • Providing your customers with detailed receipts that show the amount in the local pricing currency, the amount in the DCC billing currency, the exchange rate used to convert the order amount, and the DCC markup.
  • Requiring your customers to sign an acknowledgement that they had the choice to pay in the local pricing currency or their card's billing currency, that their choice is final, and that they understand the currency conversion service is offered by you and not by Visa.
  • Fulfilling any other requirements set by your acquirer.

Limitations

When you use DCC for an order, you cannot split the order into multiple shipments.
Cybersource
 cannot perform interchange optimization for orders that use DCC.
Do not request a combination of these services in the same DCC API request:
  • Authorization
  • Capture
  • Credit

Testing

Before you go live with DCC, you should test your integration in our sandbox environment using our DCC simulator. In order to use the sandbox environment for DCC cases, you must have your account configured for DCC service. Contact your
Cybersource
 representative for more information.

Currency Conversion Use Cases

Currency conversion enables you to dynamically convert prices from your local pricing currency to the cardholder's currency.
This section covers the procedure for a DCC credit card transaction. This section also covers the fields you will need for these DCC API calls:
  • DCC offer
  • DCC authorization
  • DCC capture
  • DCC refund

DCC Credit Card Transaction

To process a DCC credit card transaction, follow these steps.
  1. Send a DCC offer request.

    Step Result

    Receive the DCC offer response.
  2. Determine if the purchase is eligible for DCC.

    ADDITIONAL INFORMATION

    If the purchase is not eligible for DCC or DCC processing is not available, proceed with the order in your local pricing currency. Do not perform the rest of this DCC procedure.
    If the purchase is eligible for DCC, proceed to the next step.
  3. Query the customer about using DCC to pay.

    ADDITIONAL INFORMATION

    If the purchase is eligible for DCC, you must get permission from the customer to proceed.
    In your query, explain that the order is a candidate for DCC. Provide sufficient information for the customer to understand the total cost and make an informed decision. This includes:
    • The price in your local pricing currency and in the customer’s billing currency, including currency symbols.
    • The exchange rate used to convert from the local pricing currency to the billing currency.
    • Information about additional commissions and fees that the customer must pay.
    Contact your bank to learn more about the relevant payment card company rules and which information must be included.

    ADDITIONAL INFORMATION

    In addition to the information required by payment card company rules and your acquirer, you may also include additional information to help the customer understand DCC. This includes:
    • What DCC is
    • How DCC works
    • How the DCC price is calculated

    ADDITIONAL INFORMATION

    End your query by asking if the customer would like to complete the order in the card's billing currency or in your local pricing currency.
    To meet payment card company rules, you must present the customer with an active choice. This means that the customer must actively choose DCC. The DCC may not be performed by default.
    Since the cardholder must explicitly choose to use DCC for the purchase, there are additional requirements you must meet in order to use DCC for recurring or subscription payments. Contact your acquirer for more information.

    Step Result

    Customer chooses the currency for the order.
  4. Display a confirmation page.

    ADDITIONAL INFORMATION

    You can also send a transaction receipt to the customer.
    The confirmation page and the receipt must include the DCC information required by the payment card company.
    If the customer declines to use DCC, proceed with the order in your local pricing currency. Do not perform the rest of this DCC procedure.
    If the customer chooses to use DCC, proceed to the next step.
  5. Authorize the DCC payment.

    ADDITIONAL INFORMATION

    If you and your acquirer use
    Visa Platform Connect
     (VPC) for processing, the
    orderInformation.amountDetails.originalAmount
     value must be in your local pricing currency. All other amounts for the order must be in the DCC payment currency. This includes the total DCC payment amount as well as any tax amounts, surcharge amounts, Level II amounts, and airline data amounts that you send to
    Cybersource
    .
    For partial captures and refunds, use the exchange rate that you received in the DCC response to convert these amounts from your local pricing currency to the cardholder’s billing currency.

DCC Offer

A DCC offer creates a new offer record in your system. Request the DCC Offer service to determine the eligibility of the transaction for DCC and to convert the price from the local payment currency to the DCC billing currency for eligible transactions.

Header Fields

DCC Offer calls require these header fields:
Authorization
keyId

Endpoint

Test:
POST
https://apitest.cybersource.com
/vas/v1/currencyconversion
Production:
POST
https://api.cybersource.com
/vas/v1/currencyconversion

Required Fields for DCC Offer POST Request

Optional Fields for DCC Offer POST Request

orderInformation.currencyConversion.type
This field is required when MCP is enabled.
Default value:
  • DCC
    : Dynamic Currency Conversion
Possible values:
  • KEYED
    : may refer to MOTO on a terminal, MOTO on a virtual terminal, or eCommerce.
  • SWIPED
  • CONTACT
  • CONTACTLESS

REST Example: DCC Offer POST

Request
{
  "clientReferenceInformation": {
    "code": "REF-101-USD-909",
    "partner": {
      "developerId": "123456",
      "solutionId": "123456"
    },
    "applicationName": "REST API",
    "applicationVersion": "1.23.44",
    "applicationUser": "Bob"
  },
  "paymentInformation": {
    "card": {
      "number": "41111111111"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "originalAmount": "100.00",
      "originalCurrency": "USD"
    },
    "currencyConversion": {
      "type": "DCC"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "12345678",
    "entryMode": "CONTACT"
  }
}
Response
{
  "clientReferenceInformation": {
    "code": "REF-101-USD-909"
  },
  "id": "6843379070056369304008",
  "submitTimeUtc": "2023-05-17T22:47:57Z",
  "status": "PENDING",
  },
  "orderInformation": {
    "currencyConversion": {
      "type": "DCC",
      "reconciliationId": "ABC123",
      "offer": [
        {
          "originalAmount": "100.00",
          "originalCurrency": "USD",
          "amount": "157.00",
          "currency": "AUD",
          "exchangeRate": "1.57",
          "marginRate": "3.0",
          "rateSource": "Wholesale Exchange Rate",
          "exchangeRateTimeUtc": "2023-05-17T23:47:57Z",
          "exchangeRateExpirationTimeUtc": "2024-05-18T22:47:57Z",
          "exchangeRateInverted": true,
          "rateId": "009F303309AF07234520190628143445"
        }
      ],
      "disclaimer": "SAMPLE ONLY: I have been offered a choice of currencies and choose to pay in the selected currency above. Dynamic Currency Conversion (DCC) is provided by the <MERCHANT>."
    }
  }
}

DCC Authorization

A DCC authorization authorizes the amount for the transaction. The payment response includes the status of the request. It also includes processor-specific information when the request is successful, and error information when the request is unsuccessful.
See the Payments Developer Guide for more information.

Required Fields for DCC Authorization

In addition to the normal fields required for a regular authorization, these fields are required when DCC has been offered and the cardholder has chosen to pay in their billing currency.
orderInformation.amountDetails.currencyConversion.indicator
Set this field to
1
 when cardholders opt to use DCC.
Required for FDI Global transactions.
Required for FDI Global transactions.
Required for VPC transactions.
Required for VPC transactions.

Example: DCC Authorization

Request for
Visa Platform Connect
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "paymentInformation": {
    "card": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "157.00",
      "currency": "AUD",
      "exchangeRate": "1.57",
      "exchangeRateTimeStamp": "20251108 12:12",
      "originalAmount": "100.00",
      "originalCurrency": "USD",
      "currencyConversion": {
        "indicator": "1",
        "reconciliationId": "ABC123",
        "id": "6843379070056369304008"
      }
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1 Market St",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@cybs.com",
      "phoneNumber": "4158880000"
    }
  }
}
Response for
Visa Platform Connect
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7625574701416008504806/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7625574701416008504806"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7625574701416008504806/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "7625574701416008504806",
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "157.00",
      "currency": "AUD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "type": "001"
    },
    "card": {
      "type": "001"
    }
  },
  "processorInformation": {
    "systemTraceAuditNumber": "866090",
    "merchantNumber": "123456789",
    "approvalCode": "831000",
    "merchantAdvice": {
      "code": "01",
      "codeRaw": "M001"
    },
    "responseDetails": "ABC",
    "networkTransactionId": "016153570198200",
    "retrievalReferenceNumber": "531123866090",
    "consumerAuthenticationResponse": {
      "code": "2",
      "codeRaw": "2"
    },
    "transactionId": "016153570198200",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "7625574701416008504806",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-11-07T23:17:50Z"
}
Request for
FDC Nashville Global
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "paymentInformation": {
    "card": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "USD",
      "foreignAmount": "157.00",
      "foreignCurrency": "AUD",
      "exchangeRate": "1.57",
      "exchangeRateTimeStamp": "20251108 12:12",
      "currencyConversion": {
        "indicator": "1"
      }
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1 Market St",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@cybs.com",
      "phoneNumber": "4158880000"
    }
  }
}
Response for
FDC Nashville Global
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/7625543558656491904805/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/7625543558656491904805"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/7625543558656491904805/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "7625543558656491904805",
  "issuerInformation": {
    "responseRaw": "0110322000000E10000200000000000001570011072225553898395333383745484F43544357433833313030303030000159004400223134573031363135303730333830323039344730363400103232415050524F56414C0006564943524320"
  },
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "100.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "type": "001"
    },
    "card": {
      "type": "001"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "01411543"
  },
  "processorInformation": {
    "merchantNumber": "000846649116882",
    "approvalCode": "831000",
    "networkTransactionId": "016150703802094",
    "transactionId": "016150703802094",
    "responseCode": "00",
    "avs": {
      "code": "Y",
      "codeRaw": "Y"
    }
  },
  "reconciliationId": "S387EHOCTCWC",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2025-11-07T22:25:55Z"
}

DCC Capture

A DCC capture request indicates an accepted order. This request is sent when a DCC transaction is successfully authorized.
When processing a capture, apply the
same exchange rate
 used at the time of payment authorization. Ensure the captured amount does
not exceed
 the originally authorized amount.
See the Payments Developer Guide for more information.

Required Fields for DCC Capture

In addition to the normal fields required for a regular capture, these fields are required when DCC has been offered and the cardholder has chosen to pay in their billing currency.

Example: DCC Capture

Request for
Visa Platform Connect
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "157.00",
      "currency": "AUD",
      "exchangeRate": "1.57",
      "originalAmount": "100.00",
      "originalCurrency": "USD"
    }
  }
}
Response for
Visa Platform Connect
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/captures/7625576567396098504806/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/captures/7625576567396098504806"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "7625576567396098504806",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "157.00",
      "currency": "AUD"
    }
  },
  "reconciliationId": "7625574701416008504806",
  "status": "PENDING",
  "submitTimeUtc": "2025-11-07T23:20:56Z"
}
Request for
FDC Nashville Global
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "USD",
      "foreignAmount": "157.00",
      "foreignCurrency": "AUD",
      "exchangeRate": "1.57",
      "exchangeRateTimeStamp": "20251108 12:12"
    }
  }
}
Response for
FDC Nashville Global
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/captures/7625562821436326504806/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/captures/7625562821436326504806"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "7625562821436326504806",
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "USD"
    }
  },
  "reconciliationId": "76706982",
  "status": "PENDING",
  "submitTimeUtc": "2025-11-07T22:58:02Z"
}

DCC Refund

A DCC refund request refunds a captured DCC offer. These requests are used for both full and partial refunds.
When processing a refund, apply the
same exchange rate
 used at the time of payment authorization. Ensure the refunded amount does
not exceed
 the originally captured amount.
See the Payments Developer Guide for more information.

Required Fields for DCC Refund

In addition to the normal fields required for a regular refund, these fields are required when DCC has been offered and the cardholder has chosen to pay in their billing currency.

Example: DCC Refund

Request for
Visa Platform Connect
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "157.00",
      "currency": "AUD",
      "exchangeRate": "1.57",
      "originalAmount": "100.00",
      "originalCurrency": "USD"
    }
  }
}
Response for
Visa Platform Connect
{
  "_links": {
    "void": {
      "method": "POST",
      "href": "/pts/v2/refunds/7625571873626990704805/voids"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/refunds/7625571873626990704805"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "7625571873626990704805",
  "orderInformation": {
    "amountDetails": {
      "currency": "AUD"
    }
  },
  "reconciliationId": "7624789441456188503813",
  "refundAmountDetails": {
    "currency": "AUD",
    "refundAmount": "157.00"
  },
  "status": "PENDING",
  "submitTimeUtc": "2025-11-07T23:13:07Z"
}
Request for
FDC Nashville Global
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "USD",
      "foreignAmount": "157.00",
      "foreignCurrency": "AUD",
      "exchangeRate": "1.57",
      "exchangeRateTimeStamp": "20251108 12:12"
    }
  }
}
Response for
FDC Nashville Global
{
  "_links": {
    "self": {
      "href": "/pts/v2/refunds/4963014779006178301545",
      "method": "GET"
    },
    "void": {
      "href": "/pts/v2/refunds/4963014779006178301545/voids",
      "method": "POST"
    }
  },
  "id": "4963014779006178301545",
  "submitTimeUtc": "2017-06-01T071757Z",
  "status": "200",
  "reconciliationId": "39571012D3DFEKS0",
  "statusInformation": {
    "reason": "SUCCESS",
    "message": "Successful transaction."
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "orderInformation": {
    "amountDetails": {
      "currency": "USD"
    }
  },
  "refundAmountDetails": {
    "currency": "USD",
    "refundAmount": "100.00"
  }
}

Error Handling

This section provides information about error messages and how to handle duplicate cases.

Error Reasons

When your acquirer sends an error reason to
Cybersource
,
Cybersource
 responds to you with one of these messages.
BIN_UNKNOWN
The BIN is unknown or not recognized.
CARD_TYPE_NOT_ACCEPTED
The card type is not accepted by the payment processor.
CURRENCY_MATCH
The currency specified matches the existing currency.
CURRENCY_NOT_ALLOWED
The specified currency is not allowed for this transaction.
CURRENCY_NOT_CONFIGURED
The specified currency is not configured for currency conversion.
DUPLICATE_REQUEST
A duplicate currency conversion request was detected.
EXCHANGE_RATE_NOT_FOUND
Exchange rate information is not available for the specified currency pair.
INVALID_ACQUIRER
The acquirer information is invalid.
INVALID_AMOUNT
The specified amount is invalid for this currency conversion.
INVALID_CARD
Invalid card number for this currency conversion.
INVALID_CURRENCY
The currency specified is invalid.
INVALID_MERCHANT_CONFIGURATION
There is a problem with your currency conversion merchant configuration.
INVALID_TERMINAL
The terminal is invalid.
LOOKUP_FAILED
The lookup operation failed.
NOT_ELIGIBLE
The operation is not eligible for this currency conversion account or transaction.
PROCESSOR_ERROR
Error – General system failure.
SERVICE_DISABLED
The requested currency conversion is currently disabled.
UNKNOWN
An unknown error occurred.