DCC service methods

Method	Description
`init()`	Initializes the SDK with the DHS base URL.
`getDccOffer()`	Checks whether DCC is available for a transaction.
`getDccRate()`	Requests the current DCC rate for a specified currency.
`getDccChoice()`	Displays the cardholder choice screen and captures input.
`notifyPaymentComplete()`	Sends the transaction result to Fexco analytics.
`getDccReceiptString()`	Returns the DCC receipt string for printing or display.
`cancel()`	Cancels the current interaction with the DCC app.

init()

Call init() with the DHS base URL before calling any other method. The DCC app establishes the connection to the Fexco DHS and returns the result via DccInitCallback. See Environments for the correct URL for your environment.

dccService.init(
    "YOUR_DHS_BASE_URL",
    object : DccInitCallback {
        override fun onSuccess() {
            // Proceed with getDccOffer() or getDccRate().
        }
        override fun onFailure(error: DccError) {
            // Check the DHS URL and device network connectivity.
        }
    }
)

getDccOffer()

Use getDccOffer() to check DCC eligibility before displaying the cardholder choice screen. If the call succeeds and a DCC offer is available, pass the returned DccOffer to getDccChoice().The timeoutInMilliseconds parameter controls how long the SDK waits for a network response. The example uses 10,000 milliseconds (10 seconds).

dccService.getDccOffer(
    DccTransaction(
        "YOUR_DCC_ACQUIRER_ID",
        "UNIQUE_TRANSACTION_ID",
        "YOUR_TERMINAL_ID",
        "YOUR_MERCHANT_ID",
        "CARD_BIN",
        "BASE_AMOUNT",
        10000L
    ),
    object : DccOfferCallback {
        override fun onNoOfferAvailable() {
            // No DCC offer available. Proceed with local currency.
        }
        override fun onOfferAvailable(dccOffer: DccOffer) {
            // DCC offer available. Call getDccChoice() next.
        }
        override fun onError(error: DccError) {
            // Handle the error.
        }
    }
)

getDccRate()

Use getDccRate() for top-up and completion transactions where the latest exchange rate for a known foreign currency is required. Provide the ISO 4217 three-letter currency code in the transaction object (for example, USD or EUR). See Currency codes for a reference.

dccService.getDccRate(
    DccTransaction(
        "YOUR_DCC_ACQUIRER_ID",
        "UNIQUE_TRANSACTION_ID",
        "YOUR_TERMINAL_ID",
        "YOUR_MERCHANT_ID",
        "ISO_CURRENCY_CODE",
        "BASE_AMOUNT",
        10000L
    ),
    object : DccRateCallback {
        override fun onNoRateAvailable() {
            // No rate available for the specified currency.
        }
        override fun onRateAvailable(dccOffer: DccOffer) {
            // Rate available. Proceed with authorization.
        }
        override fun onError(error: DccError) {
            // Handle the error.
        }
    }
)

getDccChoice()

Use getDccChoice() after a successful getDccOffer() call. Pass the DccOffer from the offer callback and a timeout, in milliseconds, that controls how long the choice screen stays open before it closes automatically.

dccService.getDccChoice(
    DccChoiceConfiguration(
        1,         // Screen set identifier.
        dccOffer,  // DccOffer from getDccOffer() callback.
        30000L     // Timeout in milliseconds before auto-close.
    ),
    object : DccChoiceCallback {
        override fun onDCCOfferAccept(dccChoice: DccChoice) {
            // Cardholder accepted DCC. Proceed with authorization.
        }
        override fun onDCCOfferReject() {
            // Cardholder declined. Proceed with local currency.
        }
        override fun onError(error: DccError) {
            // Handle the error. Check DccError.reason for "On timeout".
        }
    }
)

notifyPaymentComplete()

Call notifyPaymentComplete() after every transaction, regardless of the authorization result. This method sends analytics data to Fexco and does not affect the payment outcome.

dccService.notifyPaymentComplete(
    TransactionResult(
        "UNIQUE_TRANSACTION_ID",
        dccTransactionType,
        cardEntryMode,
        authResult,
        "AUTH_CODE",
        "YOUR_SOFTWARE_NAME",
        "YOUR_SOFTWARE_VERSION",
        "CASHIER_ID"
    ),
    object : NotifyPaymentCompleteCallback {
        override fun onSuccess() {
            // Analytics data sent.
        }
        override fun onFailure(error: DccError) {
            // Analytics failed. The transaction result is not affected.
        }
    }
)

getDccReceiptString()

Use getDccReceiptString() to get the DCC receipt text after a transaction. Pass the transaction type as a string using TransactionType.name and the foreign currency alpha code.Supported transaction types are SALE, REFUND, COMPLETION, and PREAUTH. All other transaction types return an empty string.

val receiptString = dccService.getDccReceiptString(
    TransactionType.SALE.name,              // e.g. "SALE", "REFUND"
    dccChoice.dccForeignCurrencyAlphaCode   // e.g. "USD", "EUR"
)

if (receiptString.isNotEmpty()) {
    // Display or print the receipt string.
}

The dccReceiptString field on DccChoice is still populated for backward compatibility, but it always returns sale receipt text regardless of transaction type. Use getDccReceiptString() for all new integrations.

cancel()

Use cancel() to stop the current interaction with the DCC app at any point. Any active callback receives an error with the reason "Canceled".

dccService.cancel()

File formats

Android app

Codes and standards