# Simulate Authorizations

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](https://docs.sudoplatform.com/guides/merchants-and-currencies#list-the-simulator-merchants).

An example implementation of creating a simulated authorization is:

{% tabs %}
{% tab title="TypeScript" %}

```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
}
```

{% endtab %}

{% tab title="Swift" %}

```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
}
```

{% endtab %}

{% tab title="Kotlin" %}

```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
    }
}
```

{% endtab %}
{% endtabs %}

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](https://docs.sudoplatform.com/guides/manage-debits#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:

{% tabs %}
{% tab title="TypeScript" %}

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

{% endtab %}

{% tab title="Swift" %}

```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
}    
```

{% endtab %}

{% tab title="Kotlin" %}

```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
    }
}
```

{% endtab %}
{% endtabs %}

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](https://docs.sudoplatform.com/guides/manage-debits#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](#create-a-simulated-authorization) API.

An example implementation of marking an authorization as expired is:

{% tabs %}
{% tab title="TypeScript" %}

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

{% endtab %}

{% tab title="Swift" %}

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

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}
{% endtabs %}

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.