Simulate Authorizations

Simulate a request from a merchant to authorize a charge to a virtual card.

An authorization is a request by a merchant for permission to charge a virtual card up to a fixed amount at some time in the near future.

Create a Simulated Authorization

A simulated authorization is created by calling the simulate authorization API and supplying the amount and virtual card details.

The amount supplied as input is expressed as a multiple of the smallest unit of currency the merchant accepts. For example if the currency is US dollar then the amount is the number of US cents. The merchantId is the identifier of a merchant defined in the simulator. The merchants are listed with the getSimulatorMerchants method. See List the Simulator Merchants.

An example implementation of creating a simulated authorization is:

TypeScript

try {
  const result = await simulatorClient.simulateAuthorization({
    pan: "4242424242424242",
    amount: 4200,
    merchantId: "000000001",
    expiry: { mm: "2", yyyy: "2024" },
    billingAddress: undefined,
    csc: "123",
  })
} catch (error) {
  // Handle error
}

Swift

do {
    let authInput = SimulateAuthorizationInput(
        pan: "4242424242424242",
        amount: 4200,
        merchantId: "000000001",
        expiry: Expiry(mm: 2, yyyy: 2024),
        billingAddress: nil,
        csc: "123"
    )
    let response = try await simulatorClient.simulateAuthorizationWithInput(
        authInput
    )
    if (response.approved) {
        // Authorization has been approved
    } else {
        // Handle the authorization being declined
        // see result.declineReason for why
    }
} catch let error {
    // Handle/notify the user of error
}

Kotlin

val authInput = SimulateAuthorizationInput(
    cardNumber = "4242424242424242",
    amount = 4200, 
    merchantId = "000000001", 
    securityCode = "123",
    expirationMonth = 2,
    expirationYear = 2024
)
launch {
    try {
        val authorization = withContext(Dispatchers.IO) {
            simulatorClient.simulateAuthorization(authInput)
        }
        if (authorization.isApproved) {
            // Authorization has been approved
        } else {
            // Handle the authorization being declined
            // see authorization.declineReason for why
        }
    } catch (e: AuthorizationException) {
        // Handle/notify the user of exception
    }
}

This API call returns an authorization that may have been approved or declined. If the authorization has been approved the merchant will be able to charge the virtual card by creating a simulated debit. See Create a Simulated Debit. If the authorization was declined the declineReason of the response will provide an explanation of why. If an exception occurs, the error or exception will contain a description of the fault that caused the exception.

Increase the Value of an Authorization

The amount of a simulated authorization can be increased by calling the simulate incremental authorization API and supplying the identifier of the authorization and the amount by which it will be increased.

The amount supplied as input is expressed as a multiple of the smallest unit of currency the merchant accepts. For example if the currency is US dollar then the amount is the number of US cents. The authorizationId is the identifier of the original authorization being modified that was created by a call to the simulateAuthorization method.

An example implementation of creating a simulated incremental authorization is:

TypeScript

try {
  const result = await simulatorClient.simulateIncrementalAuthorization({
    authorizationId: authorization.id,
    amount: 2400,
  })
} catch (error) {
  // Handle error
}

Swift

do {
    let incAuthInput = SimulateIncrementalAuthorizationInput(
        amount: 2400,
        authorizationId: authorization.id
    )
    let response = try await simulatorClient.simulateIncrementalAuthorizationWithInput(
        incAuthInput
    )
    if (response.approved) {
        // Authorization increment has been approved
    } else {
        // Handle the authorization increment being declined
        // see result.declineReason for why
    }
} catch let error {
    // Handle/notify the user of error
}    

Kotlin

val incAuthInput = SimulateIncrementalAuthorizationInput(
    authorizationId = authorization.id,
    amount = 2400
)
launch {
    try {
        val authorization = withContext(Dispatchers.IO) {
            simulatorClient.simulateIncrementalAuthorization(incAuthInput)
        }
        if (authorization.isApproved) {
            // Authorization increased has been approved
        } else {
            // Handle the authorization increase being declined
            // see authorization.declineReason for why
        }
    } catch (e: AuthorizationException) {
        // Handle/notify the user of exception
    }
}

This API call returns an authorization that may have been approved or declined. If the authorization has been approved the merchant will be able to charge the virtual card more than permitted by the original authorization by creating a simulated debit. See Create a Simulated Debit. If the incremental authorization was declined the declineReason of the response will provide an explanation of why. If an exception occurs, the error or exception will contain a description of the fault that caused the exception.

Simulate the Expiry of an Authorization

An authorization can be marked as expired by calling the simulate authorization expiry API. The authorizationId is the identifier of the original authorization being modified that was created by a call to the Create a Simulated Authorization API.

An example implementation of marking an authorization as expired is:

TypeScript

try {
  const result = await simulatorClient.simulateAuthorizationExpiry({
    authorizationId: authorization.id,
  })
} catch (error) {
  // Handle error
}

Swift

do {
    let response = try await simulatorClient.simulateAuthorizationExpiryWithId(
        authorizationId
    )
    // Authorization is expired
} catch let error {
    // Handle/notify the user of error
}

Kotlin

launch {
    try {
        withContext(Dispatchers.IO) {
            simulatorClient.simulateAuthorizationExpiry(authorizationId)
        }
        // Authorization is expired
    } catch (e: AuthorizationException) {
        // Handle/notify the user of exception
    }
}

This API call returns a response that contains the identifier of the expiry request, which is of little interest. If an exception occurs, the error or exception will contain a description of the fault that caused the exception.