Merchants and Currencies

The Virtual Cards Simulator comes pre-configured with a number of merchants and currency conversion rates.

The Virtual Cards Simulator comes pre-configured with a number of merchants that have a variety of characteristics that allow you to simulate different transactions. It also contains a small number of currency conversion rates.

Some merchants have specific behaviors that will cause particular decline codes to be generated when an authorization is requested. The returned SimulatorMerchant objects have a description field that provides a brief description of any special behavior of that merchant.

List the Simulator Merchants

The merchants that are defined in the simulator can be fetched by calling the getSimulatorMerchants API.

There are only a small number of merchants defined in the simulator, so this API does not require the results to be paged.

An example implementation of listing the merchants is:

TypeScript

try {
  const result = await simulatorClient.listSimulatorMerchants()
} catch (error) {
  // Handle error
}

Swift

do {
    let response = try await simulatorClient.getSimulatorMerchants()
    // Find a hotel or motel
    let hotel = try response.get().first { $0.mcc == "7011" }
} catch let error {
    // Handle/notify the user of error
}

Kotlin

launch {
    try {
        val merchants = withContext(Dispatchers.IO) {
            simulatorClient.getSimulatorMerchants()
        }
        // Find a hotel or motel
        val hotel = merchants.find { it.mcc == "7011" }
    } catch (e: GetSimulatorMerchantsException) {
        // Handle/notify the user of exception
    }
}

If an exception occurs, the error or exception will contain a description of the fault that caused the exception.

List the Simulator Conversion Rates

The currency conversion rates that are defined in the simulator can be fetched by calling the getSimulatorConversionRates API.

There are only a small number of conversion rates defined in the simulator, so this API does not require the results to be paged.

An example implementation of listing the conversion rates is:

TypeScript

try {
  const rates = await simulatorClient.listSimulatorMerchants()
  const usd = rates.find((r) => { r.currency == "USD" })
  const aud = rates.find((r) => { r.currency == "AUD" })
  if (usd && aud) {
    const usdToAud = Number(aud.amount) / Number(usd.amount)
    console.log(`USD to AUD ${usdToAud}`)
  }
} catch (error) {
  // Handle error
}

Swift

do {
    let response = try await simulatorClient.getSimulatorConversionRates()
    let rates = try response.get()
    let usd = rates.first { $0.currency == "USD" }
    let aud = rates.first { $0.currency == "AUD" }
    if usd != nil && aud != nil {
        let usdToAud = Double(aud!.amount) / Double(usd!.amount)
        print("USD to AUD \(usdToAud)")
    }
} catch let error {
    // Handle/notify the user of error
}

Kotlin

launch {
    try {
        val rates = withContext(Dispatchers.IO) {
            simulatorClient.getSimulatorConversionRates()
        }
        // Find the rate of USD to AUD
        val usd = rates.find { it.currency == "USD" }
        val aud = rates.find { it.currency == "AUD" }
        val usdToAud = aud.amount.toDouble() /
            usd.amount.toDouble() 
        println("USD to AUD $usdToAud")
    } catch (e: GetSimulatorConversionRatesException) {
        // Handle/notify the user of exception
    }
}

The list of CurrencyAmount classes returned contain the currency code and the conversion rate amount expressed as an Int. To convert between two currencies find the CurrencyAmount class for each currency, convert the amount to a Double then divide the two rates. If an exception occurs, the error or exception will contain a description of the fault that caused the exception.