Search…
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
Swift
Kotlin
1
try {
2
const result = await simulatorClient.simulateAuthorization({
3
pan: "4242424242424242",
4
amount: 4200,
5
merchantId: "000000001",
6
expiry: { mm: "2", yyyy: "2024" },
7
billingAddress: undefined,
8
csc: "123",
9
})
10
} catch (error) {
11
// Handle error
12
}
Copied!
1
let authInput = SimulateAuthorizationInput(
2
pan: "4242424242424242",
3
amount: 4200,
4
merchantId: "000000001",
5
expiry: Expiry(mm: 2, yyyy: 2024),
6
billingAddress: nil,
7
csc: "123"
8
)
9
simulatorClient.simulateAuthorizationWithInput(authInput) { result in
10
switch result {
11
case .success(response):
12
if (response.approved) {
13
// Authorization has been approved
14
} else {
15
// Handle the authorization being declined
16
// see result.declineReason for why
17
}
18
case .failure:
19
// Handle/notify the user of exception
20
}
21
}
Copied!
1
val authInput = SimulateAuthorizationInput(
2
cardNumber = "4242424242424242",
3
amount = 4200,
4
merchantId = "000000001",
5
securityCode = "123",
6
expirationMonth = 2,
7
expirationYear = 2024
8
)
9
launch {
10
try {
11
val authorization = withContext(Dispatchers.IO) {
12
simulatorClient.simulateAuthorization(authInput)
13
}
14
if (authorization.isApproved) {
15
// Authorization has been approved
16
} else {
17
// Handle the authorization being declined
18
// see authorization.declineReason for why
19
}
20
} catch (e: AuthorizationException) {
21
// Handle/notify the user of exception
22
}
23
}
Copied!
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
Swift
Kotlin
1
try {
2
const result = await simulatorClient.simulateIncrementalAuthorization({
3
authorizationId: authorization.id,
4
amount: 2400,
5
})
6
} catch (error) {
7
// Handle error
8
}
Copied!
1
let incAuthInput = SimulateIncrementalAuthorizationInput(
2
amount: 2400,
3
authorizationId: authorization.id
4
)
5
simulatorClient.simulateIncrementalAuthorizationWithInput(incAuthInput) { result in
6
switch result {
7
case .success(response):
8
if (response.approved) {
9
// Authorization increment has been approved
10
} else {
11
// Handle the authorization increment being declined
12
// see result.declineReason for why
13
}
14
case .failure:
15
// Handle/notify the user of exception
16
}
17
}
Copied!
1
val incAuthInput = SimulateIncrementalAuthorizationInput(
2
authorizationId = authorization.id,
3
amount = 2400
4
)
5
launch {
6
try {
7
val authorization = withContext(Dispatchers.IO) {
8
simulatorClient.simulateIncrementalAuthorization(incAuthInput)
9
}
10
if (authorization.isApproved) {
11
// Authorization increased has been approved
12
} else {
13
// Handle the authorization increase being declined
14
// see authorization.declineReason for why
15
}
16
} catch (e: AuthorizationException) {
17
// Handle/notify the user of exception
18
}
19
}
Copied!
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
Swift
Kotlin
1
try {
2
const result = await simulatorClient.simulateAuthorizationExpiry({
3
authorizationId: authorization.id,
4
})
5
} catch (error) {
6
// Handle error
7
}
Copied!
1
simulatorClient.simulateAuthorizationExpiryWithId(authorizationId) { result in
2
switch result {
3
case .success:
4
// Authorization is expired
5
case .failure:
6
// Handle/notify the user of exception
7
}
8
}
Copied!
1
launch {
2
try {
3
withContext(Dispatchers.IO) {
4
simulatorClient.simulateAuthorizationExpiry(authorizationId)
5
}
6
// Authorization is expired
7
} catch (e: AuthorizationException) {
8
// Handle/notify the user of exception
9
}
10
}
Copied!
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.
Last modified 14d ago