Budget Control SDK

Version 2.0.11

Budget Control SDK Overview

1.1. What is Budget Control SDK?

1.2. How does Budget Control SDK work?

1.3. Versioning and backward compatibility
Technical overview

2.1. Basic information

2.2. Basic configuration

2.3. Budget Control SDK Setup

2.4. Delivery setup

2.5. Error handling
Budget Control Service

3.1. getInvitation

3.2. initializeRedeemCard (deprecated)

3.3. finalizeRedeemCard (deprecated)

3.4. getVcnDetails

3.5. getCards

3.6. getCardDetails

3.7. getAlerts

3.8. deleteAlert

3.9. acceptTermsAndConditions

3.10. addApproval

3.11. redeemInvitation

3.12. redeemInvitationConfirmationCode

3.13. registerCardEventsListener

3.14. registerTermsAndConditionsEventsListener

3.15. registerApprovalEventsListener
Document changelog

4.1 Version 1.0.0

4.2 Version 1.0.1

4.3 Version 1.0.2

4.4 Version 1.0.3

4.5 Version 1.1.0

4.6 Version 1.1.1

4.7 Version 1.1.2

4.8 Version 2.0.0

4.9 Version 2.0.1

4.10 Version 2.0.2

4.11 Version 2.0.3

4.12 Version 2.0.4

4.13 Version 2.0.5

4.14 Version 2.0.6

4.15 Version 2.0.7)

4.16 Version 2.0.8)

4.17 Version 2.0.9)

4.18 Version 2.0.10

4.19 Version 2.0.11

Budget Control SDK Overview

1.1. What is Budget Control SDK?

Budget Control sdk is a closed framework providing services for business card management.
By using an invitation, you can join the programme and use payment cards assigned to your account by
the administrator.

1.2. How does Budget Control SDK work?

Services provide methods to:

check the card’s budget and spending limits,
send a request to change a card’s limits,
check the list of terms and conditions pending approval,
get details of a virtual payment card.

Budget Control SDK requires Mobile DC as a dependency.
It’s required for the Budget Control SDK to work correctly and handles user’s session and data.
Please read the Mobile DC SDK’s documentation to see more details about the installation and
integration process

In order to incorporate this SDK into your app, see Basic configuration

1.3. Versioning and backward compatibility

SDK is based on semantic versioning.
For example: 1.0.0 ( MAJOR.MINOR.PATCH )

Major version compatibility-breaking changes in SDK public APIs.
It is mandatory to update application code, to use SDK, when this is incremented.
Minor version tracks new, not compatibility-breaking changes in public API of SDK.
It is optional to update application code, when this digit is incremented.
Patch version tracks internal changes in SDK.
No updates in application code are necessary to update to version, which has this number
incremented.

Changes not breaking compatibility:

adding new optional interface to SDK setup
adding new method to any domain
adding new enum value to input or output
adding new field in input or output model

2. Technical overview

This section describes basic information about Budget Control SDK setup and available methods.

2.1. Basic information

2.1.1 Facade

Facade is an entry point to communication with Budget Control SDK.

2.1.2 Multiple facade types

Budget Control SDK provides two public API's with same functionalities, the API's are:

BudgetControlCoroutineService for projects which uses Kotlin programming language and
Coroutines.
BudgetControlStdService for projects which uses Kotlin or Java programming language and
standard Callback.

The difference between the API's is a way of providing data to SDK methods and getting the results
from them.
Input and output as an data models are the same.
This documentation presents I/O types in a Kotlin way as it's easier to mark nullable fields (as
question mark).

2.1.3 Method structure

Every method description has same structure.

Execution type:

Asynchronous - operation could take more time and method is called on thread different than
main. The result of execution is provided in callback (described below).
Synchronous - result of operation is provided as method return type.

Method type:

Online - operation requires Internet connection.
Offline - operation can be called without Internet connection.

Input Input parameters with name, type and description.

Output Result delivered by standard Callback with data or result is suspended until the Coroutine
completes <Multiple facade types>.

2.2 Basic configuration

2.2.1 Min SDK Version

The minSdkVersion must be at least 23 (Android 6.0).

2.2.2 Artifactory

SDK is available on Verestro maven repository and can be configured in project using Gradle build
system.

Username and password are provided by Verestro.

    maven {   
       credentials {   
          username "<enter_username_here>"   
          password "<enter_password_here>"   
       }   
       url "https://artifactory.verestro.com/artifactory/android-release/"  
    }}  ```    
#### 2.2.3 SDKs version  

Budget Control SDK is available in two versions: debug and release.    
The difference between version is debug allows to use application with debugger connected.    
Samples below.  

For release version, used on production environment in application uploaded to Google Play:  

```gradle  dependencies {   
    implementation 'pl.upaid.module:mobiledc:{version}'   
    implementation 'com.verestro.sdk:bc:${version}'  
}  ```    
For debugging purposes:  

```gradle  dependencies {  
    implementation 'pl.upaid.module:mobiledc:{version}-debug'    implementation 'com.verestro.sdk:bc:debug-${version}'}  ```  

#### 2.2.1 Source code obfuscation and optimization  

As SDK is written in Kotlin language we recommend to add following code to gradle configuration:  

```gradle  android {  ...   
     kotlinOptions {   
        freeCompilerArgs = [   
           '-Xno-param-assertions',   
           '-Xno-call-assertions',   
           '-Xno-receiver-assertions'   
       ]   
    }    
packagingOptions { exclude '/kotlin_metadata/**' } ...  
}  ```    
Then use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8  
instead Proguard in gradle.properties file:  

```gradle  android.enableR8=true  ```    
### 2.3 Budget Control SDK Setup  

Available configuration methods:  

- BudgetControlCoroutineApi.init(configuration: Configuration)  
- BudgetControlStdApi.init(configuration: Configuration)  

#### 2.3.1 Input  

**`Configuration`**  

| Parameter     | Type          | Description         |  |---------------|---------------|---------------------|  | configuration | Configuration | Configuration model |  

**`Configuration`**  

| Parameter             | Type                               | Description                   |  |-----------------------|------------------------------------|-------------------------------|  
| url                   | String                             | API hostname URL              |  
| certificateHashes     | List\<String>                      | API hostname Pin SHA256       |  
| notificationsListener | BudgetControlNotificationsListener | Remote notifications listener |  

#### 2.3.2 Sample  

**`BudgetControlCoroutineApi`**  

```kotlin  fun init(configuration: Configuration) {  
    BudgetControlCoroutineApi.init(configuration)}

BudgetControlStdApi

    BudgetControlStdApi.init(configuration)}

2.4 Delivery setup

Antaca SDK uses push notifications for asynchronous communication. On the application side you need
to register the FCM
service,
and then pass the message to the MDC SDK through the process method in the onMessageReceive
method (after verifying
the message source - sender id).
See the Technical documentation MDC SDK for more details.
After initial setup register the appropriate event listener using the corresponding method on the
facade.

2.5 Error handling

SDK returns errors by BcSdkException, which could be catched by application and shown on UI with
detailed message.

Table below describes general exception types.

| Exception type | Exception class | Description | |----------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Backend | BcSdkException | Provides additional validation or error on backend side. Application should get reason code and show suitable message or made action. Message should be never shown to user. Could be logged for error reporting and for developers. List of available exceptions in table below |

BcSdkException

| Exception | Parameters | Description | |-------------------------------|-----------------------------|-----------------------------------------| | HttpApiException | code: Int, message: String? | HTTP API exception. | | TechnicalException | message: String? | Technical exception. | | NoSessionException | | User is unauthorized - session expired. | | RequestCancelled | | Request was canceled. | | UnknownHostException | | Unknown host. | | UnknownErrorStatus | status: String? | An unknown error occurred. | | InvalidInvitationCode | | Invalid invitation code. | | ResourceNotFound | | Resource not found. | | InvalidId | | Invalid id. | | ApprovalRequestExist | | Approval request exist. | | CardAssignedToAnotherUser | | Card assigned to another user. | | NoCertificatePinningException | | No certificate pinning. | | ValidationException | | Contains list of ValidationError. |
ValidationException

| Parameter | Type | Description | |------------------|------------------------|----------------|
| validationErrors | List<ValidationError> | List of errors |

ValidationError

| Parameter | Type | Description | |--------------|-----------------------|-------------------------|
| errorReason | ValidationErrorReason | Validation error reason |
| errorMessage | String | Error message |

ValidationErrorReason

| Reason | Description | |-----------------|-------------------|
| InvalidDateTo | Invalid date to |
| InvalidDateFrom | Invalid date form |
| InvalidAmount | Invalid amount |
| Unknown | Unknown |

3 Budget Control Service

3.1 getInvitation

This method provides invitation code from Budget Control backend.

3.1.1 Input

InvitationData

| Parameter | Type | Description |
|----------------|----------------|---------------------------| | invitationData | InvitationData | Get invitation data model |

InvitationData

| Parameter | Type | Description | |----------------|--------|--------------------------------------------------------------------------------| | invitationCode | String | Invitation code that will be required for initialize user registration process |

3.1.2 Output

3.1.2.1 Success

InvitationResult

| Parameter | Type | Description | |---------------|------------------|-----------------------------| | getInvitation | InvitationResult | Get invitation result model |

InvitationResult

| Parameter | Type | Description | |------------|-----------------|------------------| | invitation | InvitationModel | Invitation model |

InvitationModel

| Parameter | Type | Description | |--------------------|--------------------------------|---------------------------------------------| | invitationCode | String | Invitation code |
| phonePrefix | String | Phone prefix |
| phoneNumber | String | User's phone number |
| email | String | User's email |
| termsAndConditions | List<TermsAndConditionsModel> | List of terms and conditions to be accepted |

TermsAndConditionsModel

| Parameter | Type | Description | |-----------|--------|----------------| | id | String | Id of T&C |
| header | String | Header of T&C |
| content | String | Content of T&C |

3.1.2.2 Failure

BcSdkException

| Exception | Parameters | Description | |-----------------------|-----------------------------|----------------------------------------| | HttpApiException | code: Int, message: String? | HTTP API exception | | TechnicalException | message: String? | Technical exception | | NoSessionException | | User is unauthorized - session expired | | RequestCancelled | | Request was canceled | | UnknownErrorStatus | status: String? | An unknown error occurred |
| ResourceNotFound | | Resource not found | | InvalidId | | Invalid id |
| InvalidInvitationCode | | Invalid invitation code |

3.1.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .getInvitation(            invitationData = invitationData,            callback = object : ApiCallback<InvitationResult> {                override fun onSuccess(response: InvitationResult) {                    /*TODO: do something with get invitation result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .getInvitation(invitationData = invitationData) ```  

### 3.2 initializeRedeemCard (deprecated)  

```  Asynchronous. Online.    

Initialize reedem card process.

3.2.1 Input

RedeemCardData

Parameter	Type	Description
redeemCardData	RedeemCardData	Redeem card data model

RedeemCardData

| Parameter | Type | Description | |----------------|--------|-----------------------------------------------------------------------------------|
| invitationCode | String | Invitation code that will be required to initialize invitation acceptance process |

3.2.2 Output

3.2.2.1 Success

InitializeRedeemCardResult

3.2.2.2 Failure

BcSdkException

| Exception | Parameters | Description | |--------------------|-----------------------------|----------------------------------------| | HttpApiException | code: Int, message: String? | HTTP API exception | | TechnicalException | message: String? | Technical exception | | NoSessionException | | User is unauthorized - session expired | | RequestCancelled | | Request was canceled | | UnknownErrorStatus | status: String? | An unknown error occurred |
| ResourceNotFound | | Resource not found | | InvalidId | | Invalid id |

3.2.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .initializeRedeemCard(            redeemCardData = redeemCardData,            callback = object : ApiCallback<InitializeRedeemCardResult> {                override fun onSuccess(response: InitializeRedeemCardResult) {                    /*TODO: do something with response*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .initializeRedeemCard(redeemCardData = redeemCardData) ```  

### 3.3 finalizeRedeemCard (depracated)  

```  Asynchronous. Online.    

Finalize redeem card.

3.3.1 Input

FinalizeRedeemCardData

| Parameter | Type | Description |
|------------------------|------------------------|---------------------------------| | finalizeRedeemCardData | FinalizeRedeemCardData | Finalize redeem card data model |

FinalizeRedeemCardData

Parameter	Type	Description
invitationCode	String	Invitation code that will be required to initialize invitation acceptance process
confirmationCode	String	One time password (sent via SMS )

3.3.2 Output

3.3.2.1 Success

FinalizeRedeemCardResult

FinalizeRedeemCardResult is an empty class.

3.3.2.2 Failure

3.3.3 Sample

Standard Callback

    finalizeRedeemCardData: FinalizeRedeemCardData) {  
    BudgetControlStdApi        .BudgetControlStdService        .finalizeInvitationAcceptance(            finalizeRedeemCardData = finalizeRedeemCardData,            callback = object : ApiCallback<FinalizeRedeemCardResult> {                override fun onSuccess(response: FinalizeRedeemCardResult) {                    /*TODO: do something with response*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    finalizeRedeemCardData: FinalizeRedeemCardData): FinalizeRedeemCardResult =  
    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .finalizeInvitationAcceptance(finalizeRedeemCardData = finalizeRedeemCardData) ```  

**`BcSdkException`**  

| Exception          | Parameters                  | Description                            |  |--------------------|-----------------------------|----------------------------------------|  | HttpApiException   | code: Int, message: String? | HTTP API exception                     |  | TechnicalException | message: String?            | Technical exception                    |  | NoSessionException |                             | User is unauthorized - session expired |  | RequestCancelled   |                             | Request was canceled                   |  | UnknownErrorStatus | status: String?             | An unknown error occurred              |  
| ResourceNotFound   |                             | Resource not found                     |  | InvalidId          |                             | Invalid id                             |  

### 3.4 getVcnDetails  

```  Asynchronous. Online.    

Provide vcn details from Budget Control backend. When communicating with the API, the encrypted PAN number is used. Decryption on the sdk side.  
Sensitive data processed in arrays and should be cleared after use.

3.4.1 Input

VcnDetailsData

Parameter	Type	Description
vcnDetailsData	VcnDetailsData	Get vcn details data model

VcnDetailsData

| Parameter | Type | Description |
|-----------|------|-----------------| | cardId | Long | Card identifier |

3.4.2 Output

3.4.2.1 Success

VcnDetailsResult

Parameter	Type	Description
getVcnDetails	VcnDetailsResult	Get vcn details result model

VcnDetailsResult

Parameter	Type	Description
vcnDetails	VcnDetailsModel	Vcn details model

VcnDetailsModel

Parameter	Type	Description
pan	CharArray	Card number
expireDate	CharArray	Card expire date
cvc	CharArray	Card verification code

3.4.2.2 Failure

BcSdkException

3.4.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .getVcnDetails(            vcnDetailsData = vcnDetailsData,            callback = object : ApiCallback<VcnDetailsResult> {                override fun onSuccess(response: VcnDetailsResult) {                    /*TODO: do something with vcn details result , clear sensitive data by using clear() method*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .getVcnDetails(vcnDetailsData = vcnDetailsData) ```  

### 3.5 getCards  

```  Asynchronous. Online.    

Provides user cards from Budget Control backend.

3.5.1 Input

3.5.2 Output

3.5.2.1 Success

CardsResult

| Parameter | Type | Description | |-----------|-------------|------------------------| | getCards | CardsResult | Get cards result model |

CardsResult

| Parameter | Type | Description | |-----------|------------------|--------------------| | cards | List<CardModel> | List of user cards |

CardModel

| Parameter | Type | Description | |----------------------|---------------|--------------------------------------------------------| | id | Long | Card id |
| lastFourDigits | String? | Last four digits of user card |
| samsungPay | Boolean | Flag indicating support for Samsung Pay |
| applePay | Boolean | Flag indicating support for Apple Pay |
| mdes | Boolean | flag indicating support for contactless payment |
| googlePay | Boolean | Flag indicating support for Google Pay |
| startDate | String? | Start date of assigning the card for a specific period |
| endDate | String? | End date of assigning the card for a specific period |
| cumulativeLimitMinor | Long | Card limit to be used |
| currency | CurrencyModel | Currency model |
| hasVcn | Boolean | Flag indicating if card has vcn |

CurrencyModel

Parameter	Type	Description
code	String	Currency code (ISO 4217, three letter code)
numeric	Int	Currency numeric (ISO 4217)

3.5.2.2 Failure

BcSdkException

3.5.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .getCards(            callback = object : ApiCallback<CardsResult> {                override fun onSuccess(response: CardsResult) {                    /*TODO: do something with get cards result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .getCards() ```  

### 3.6 getCardDetails  

```  Asynchronous. Online.    

Provides user card details from Budget Control backend.

3.6.1 Input

CardDetailsData

| Parameter | Type | Description |
|-----------------|-----------------|-----------------------------| | cardDetailsData | CardDetailsData | Get card details data model |

CardDetailsData

| Parameter | Type | Description |
|-----------|------|-----------------| | cardId | Long | Card identifier |

3.6.2 Output

3.6.2.1 Success

CardDetailsResult

| Parameter | Type | Description | |----------------|-------------------|-------------------------------| | getCardDetails | CardDetailsResult | Get card details result model |

CardDetailsResult

| Parameter | Type | Description | |-------------|------------------|----------------------| | cardDetails | CardDetailsModel | Details of user card |

CardDetailsModel

| Parameter | Type | Description | |-----------------------|--------------------------|-----------------------------------------------------------------| | id | Long | Card id |
| budgetMinor | Long | User's balance |
| cumulativeMinor | Long | Card limit to be used |
| periodicLimits | List<PeriodicLimitModel | List of limits to be used in a specific time |
| currency | CurrencyModel | Currency model |
| pendingApproval | PendingApprovalModel? | Pending approval of data change assignment |
| isGooglePaySupported | Boolean | Flag information about Google Pay support |
| isSamsungPaySupported | Boolean | Flag information about Samsung Pay support |
| lastFourDigits | CharArray | Last four digits of user card |
| hasVcn | Boolean | Flag indicating if card has vcn |
| endDate | String | End date of assigning the card for a specific period |
| startDate | String | Start date of assigning the card for a specific period |
| isOneTimeVcn | Boolean | Flag information about if card is one time use |
| cardType | CardType | Deprecated. Card provider type |
| cardTypeValue | CardTypeValue | Value class encapsulating sample type as a [value] String field |

PeriodicLimitModel

Parameter	Type	Description
limitMinor	Long	Card limit to be used
timeUnit	TimeUnit	Deprecated. Time unit
timeUnitValue	TimeUnitValue	Value class encapsulating sample type as a [value] String field

TimeUnit (deprecated)

Time	Description
DAILY	Daily limit time unit
WEEKLY	Weekly limit time unit
MONTHLY	Monthly limit time unit
UNKNOWN	Unknown time unit type

TimeUnitValue

Value	Description	Supporting const
daily	Daily limit time unit	TimeUnitValue.DAILY
weekly	Weekly limit time unit	TimeUnitValue.WEEKLY
monthly	Monthly limit time unit	TimeUnitValue.MONTHLY

CardType (deprecated)

Type	Description
VISA	Visa card type
MC	Mastercard card type
EMPTY	Undefined card type

CardTypeValue

Value	Description	Supporting const
visa	Visa card type	CardTypeValue.VISA
mc	Mastercard card type	CardTypeValue.MC
empty	Undefined card type	CardTypeValue.EMPTY

CurrencyModel

Parameter	Type	Description
code	String	Currency code (ISO 4217, three letter code)
numeric	Int	Currency numeric (ISO 4217)

PendingApprovalModel

Parameter	Type	Description
endDate	String	End date of assigning the card for a specific period
cumulativeLimitMinor	Int	Card limit to be used
periodicLimits	List<PeriodicLimitModel>	List of limits to be used in a specific time

3.6.2.2 Failure

BcSdkException

3.6.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .getCardDetails(            cardDetailsData = cardDetailsData,            callback = object : ApiCallback<CardDetailsResult> {                override fun onSuccess(response: CardDetailsResult) {                    /*TODO: do something with get card details result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .getCardDetails(cardDetailsData = cardDetailsData) ```  

### 3.7 getAlerts  

```  Asynchronous. Online.    

Provides user alerts from Budget Control backend.

3.7.1 Input

3.7.2 Output

3.7.2.1 Success

AlertsResult

| Parameter | Type | Description | |-----------|--------------|-------------------------| | getAlerts | AlertsResult | Get alerts result model |

AlertsResult

| Parameter | Type | Description | |-----------|-------------|-------------------------------------| | alerts | AlertsModel | List with different types of alerts |

AlertsModel

| Parameter | Type | Description | |--------------------------|--------------------------------------|-------------------------------------------------------------------| | issuerTermsAndConditions | List<IssuerTermsAndConditionsModel> | List of terms and conditions to be approved for a specific issuer |
| notifications | List<NotificationModel> | List of notifications |

IssuerTermsAndConditionsModel

| Parameter | Type | Description | |--------------------|--------------------------------|------------------------------| | issuer | IssuerModel | Issuer model |
| termsAndConditions | List<TermsAndConditionsModel> | List of terms and conditions |

IssuerModel

| Parameter | Type | Description | |-----------|--------|-------------| | id | String | Issuer id |
| name | String | Issuer name |

TermsAndConditionsModel

| Parameter | Type | Description | |-----------|--------|----------------| | id | String | Id of T&C |
| header | String | Header of T&C |
| content | String | Content of T&C |

NotificationModel

| Parameter | Type | Description | |---------------------|---------------------------|-----------------------------------------------------------------| | id | String | Id of notification |
| header | String | Header of notification |
| content | String | Content of notification |
| type | NotificationType | Deprecated. Notification type |
| typeValue | NotificationTypeValue | Value class encapsulating sample type as a [value] String field |
| createdAt | String | Creation date of the notification |
| notificationDetails | NotificationDetailsModel? | Notification details model |

NotificationDetailsModel

| Parameter | Type | Description | |----------------------|---------------------------|-----------------------------------------------------------------| | cumulativeLimitMinor | String | Card limit to be used |
| endDate | Long | End date of assigning the card for a specific period |
| periodicLimits | List<PeriodicLimitModel> | List of limits to be used in a specific time |
| approvalStatus | ApprovalStatus | Deprecated. Approval status |
| approvalStatusValue | ApprovalStatusValue | Value class encapsulating sample type as a [value] String field |
| lastFourDigits | CharArray | Last four digits of user card |
| currencyCode | String | Currency code (ISO 4217, three letter code) |

ApprovalStatus (deprecated)

Reason	Description
ACCEPTED	Approval status accepted
REJECTED	Approval status rejected
CANCELLED	Approval status cancelled
PREPARED	Approval status prepared
UNKNOWN	Unknown approval status model

ApprovalStatusValue

Value	Description	Supporting const
delivered	Approval status accepted	ApprovalStatusValue.DELIVERED
rejected	Approval status rejected	ApprovalStatusValue.REJECTED
cancelled	Approval status cancelled	ApprovalStatusValue.CANCELLED
prepared	Approval status prepared	ApprovalStatusValue.PREPARED

PeriodicLimitModel

Parameter	Type	Description
limitMinor	Long	Card limit to be used
timeUnit	TimeUnit	Deprecated. Time unit
timeUnitValue	TimeUnitValue	Value class encapsulating sample type as a [value] String field

TimeUnit (deprecated)

Time	Description
DAILY	Daily limit time unit
WEEKLY	Weekly limit time unit
MONTHLY	Monthly limit time unit

TimeUnitValue

Value	Description	Supporting const
daily	Daily limit time unit	TimeUnitValue.DAILY
weekly	Weekly limit time unit	TimeUnitValue.WEEKLY
monthly	Monthly limit time unit	TimeUnitValue.MONTHLY

NotificationType (deprecated)

Time	Description
ASSIGN_CARD	Notification of assign card
REMOVE_CARD	Notification of card removal
NEW_TERMS_AND_CONDITIONS	Notification of new terms and conditions
MOBILE_REQUEST_ACCEPTED	Notification of mobile request accepted
MOBILE_REQUEST_REJECTED	Notification of mobile request rejected
BEFORE_CARD_EXPIRATION	Notification of before card expiration
UNKNOWN	Unknown notification type

NotificationTypeValue

Value	Description	Supporting const
ASSIGN_CARD	Notification of assign card	NotificationTypeValue.ASSIGN_CARD
REMOVE_CARD	Notification of card removal	NotificationTypeValue.REMOVE_CARD
NEW_T&C	Notification of new terms and conditions	NotificationTypeValue.NEW_TERMS_AND_CONDITIONS
MOBILE_REQUEST_ACCEPTED	Notification of mobile request accepted	NotificationTypeValue.MOBILE_REQUEST_ACCEPTED
MOBILE_REQUEST_REJECTED	Notification of mobile request rejected	NotificationTypeValue.MOBILE_REQUEST_REJECTED
BEFORE_CARD_EXPIRATION	Notification of before card expiration	NotificationTypeValue.BEFORE_CARD_EXPIRATION

3.7.2.2 Failure

BcSdkException

3.7.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .getAlerts(            callback = object : ApiCallback<AlertsResult> {                override fun onSuccess(response: AlertsResult) {                    /*TODO: do something with get alerts result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .getAlerts() ```  

### 3.8 deleteAlert  

```  Asynchronous. Online.    

Delete alert with given alert id.

3.8.1 Input

DeleteAlertData

| Parameter | Type | Description |
|-----------------|-----------------|-------------------------| | deleteAlertData | DeleteAlertData | Delete alert data model |

DeleteAlertData

| Parameter | Type | Description |
|-----------|--------|----------------------| | alertId | String | Id of deleting alert |

3.8.2 Output

3.8.2.1 Success

DeleteAlertResult

3.8.2.2 Failure

BcSdkException

3.8.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .deleteAlert(            deleteAlertData = deleteAlertData,            callback = object : ApiCallback<DeleteAlertResult> {                override fun onSuccess(response: DeleteAlertResult) {                    /*TODO: do something with delete alert result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .deleteAlert(deleteAlertData = deleteAlertData) ```  

### 3.9 acceptTermsAndConditions  

```  Asynchronous. Online.    

Accept terms and conditions with given issuer id.  ```   
#### 3.9.1 Input  

**`IssuerData`**  

| Parameter  | Type       | Description        |  |------------|------------|--------------------|  | issuerData | IssuerData | Issuer Data model. |    
**`IssuerData`**  

| Parameter | Type   | Description        |  |-----------|--------|--------------------|  | issuerId  | String | Issuer identifier. |  

#### 3.9.2 Output  

##### 3.9.2.1 Success  

```  Success callback with AcceptTermsAndConditionsResult model.  ```    
**`AcceptTermsAndConditionsResult`**  

```  AcceptTermsAndConditionsResult is an empty class. ```    
##### 3.9.2.2 Failure  

```  Failure callback with throwable.  ```    
**`BcSdkException`**  

| Exception          | Parameters                  | Description                            |  |--------------------|-----------------------------|----------------------------------------|  | HttpApiException   | code: Int, message: String? | HTTP API exception                     |  | TechnicalException | message: String?            | Technical exception                    |  | NoSessionException |                             | User is unauthorized - session expired |  | RequestCancelled   |                             | Request was canceled                   |  | UnknownErrorStatus | status: String?             | An unknown error occurred              |  
| ResourceNotFound   |                             | Resource not found                     |  | InvalidId          |                             | Invalid id                             |  

#### 3.9.3 Sample  

**`Standard Callback`**  

```kotlin  fun acceptTermsAndConditions(issuerData: IssuerData) {  
    BudgetControlStdApi        .BudgetControlStdService        .acceptTermsAndConditions(            issuerData = issuerData,            callback = object : ApiCallback<AcceptTermsAndConditionsResult> {                override fun onSuccess(response: AcceptTermsAndConditionsResult) {                    /*TODO: do something with accept t&c result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .acceptTermsAndConditions(issuerData = issuerData) ```    
### 3.10 addApproval  

```  Asynchronous. Online.    

Add approval request to change the assigned card limits.  ```   
#### 3.10.1 Input  

**`AddApprovalData`**  

| Parameter       | Type            | Description             |  
|-----------------|-----------------|-------------------------|  
| addApprovalData | AddApprovalData | Add approval data model |  

**`AddApprovalData`**  

| Parameter            | Type                      | Description                                          |  
|----------------------|---------------------------|------------------------------------------------------|  | cardId               | Long                      | Card identifier                                      |  
| endDate              | String                    | End date of assigning the card for a specific period |  
| cumulativeLimitMinor | Long                      | Card limit to be used                                |  
| periodicLimits       | List\<PeriodicLimitModel> | List of limits to be used in a specific time         |  

**`PeriodicLimitModel`**  

| Parameter     | Type          | Description                                                     |  
|---------------|---------------|-----------------------------------------------------------------|  
| limitMinor    | Long          | Card limit to be used                                           |  
| timeUnit      | TimeUnit      | Deprecated. Time unit                                           |  
| timeUnitValue | TimeUnitValue | Value class encapsulating sample type as a [value] String field |  

**`TimeUnit (deprecated)`**  

| Periodic | Description             |  
|----------|-------------------------|  
| DAILY    | Daily limit time unit   |  
| WEEKLY   | Weekly limit time unit  |  
| MONTHLY  | Monthly limit time unit |  

**`TimeUnitValue`**  

| Value   | Description             | Supporting const      |  
|---------|-------------------------|-----------------------|  
| daily   | Daily limit time unit   | TimeUnitValue.DAILY   |  
| weekly  | Weekly limit time unit  | TimeUnitValue.WEEKLY  |  
| monthly | Monthly limit time unit | TimeUnitValue.MONTHLY |  

#### 3.10.2 Output  

##### 3.10.2.1 Success  

```  Success callback with AddApprovalResult model.

AddApprovalResult

3.10.2.2 Failure

BcSdkException

| Exception | Parameters | Description | |---------------------------|-----------------------------|----------------------------------------| | HttpApiException | code: Int, message: String? | HTTP API exception | | TechnicalException | message: String? | Technical exception | | NoSessionException | | User is unauthorized - session expired | | RequestCancelled | | Request was canceled | | UnknownErrorStatus | status: String? | An unknown error occurred |
| ResourceNotFound | | Resource not found | | InvalidId | | Invalid id |
| ApprovalRequestExist | | Approval request exist | | CardAssignedToAnotherUser | | Card assigned to another user |

3.10.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .addApproval(            addApprovalData = addApprovalData,            callback = object : ApiCallback<AddApprovalResult> {                override fun onSuccess(response: AddApprovalResult) {                    /*TODO: do something with add approval result*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .addApproval(addApprovalData = addApprovalData) ```  

### 3.11 redeemInvitation  

```  Asynchronous. Online.    

Initialize reedem card process.

3.11.1 Input

RedeemInvitationData

3.11.2 Output

3.11.2.1 Success

RedeemInvitationResult

| Parameter | Type | Description | |------------------|-----------------------|-------------------------|
| redeemInvitation | RedeemInvitationModel | Redeem Invitation model |

RedeemInvitationModel

| Parameter | Type | Description | |-------------|--------|---------------------|
| phonePrefix | String | Phone prefix |
| phoneNumber | String | User's phone number |

3.11.2.2 Failure

BcSdkException

| Exception | Description | |------------------|--------------------|
| ResourceNotFound | Resource not found |

3.11.3 Sample

Standard Callback

    BudgetControlStdApi        .BudgetControlStdService        .redeemInvitation(            redeemInvitationData = redeemInvitationData,            callback = object : ApiCallback<RedeemInvitationResult> {                override fun onSuccess(response: RedeemInvitationResult) {                    /*TODO: do something with response*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    BudgetControlCoroutineApi        .BudgetControlCoroutineService        .redeemInvitation(redeemInvitationData = redeemInvitationData) ```  

### 3.12 redeemInvitationConfirmationCode  

```  Asynchronous. Online.    

Finalize redeem card.

3.12.1 Input

RedeemInvitationConfirmationCodeData

Parameter	Type	Description
invitationCode	String	Invitation code that will be required to initialize invitation acceptance process
confirmationCode	String	One time password (sent via SMS )

3.12.2 Output

3.12.2.1 Success

3.12.2.2 Failure

3.12.3 Sample

Standard Callback

    redeemInvitationConfirmationCodeData: RedeemInvitationConfirmationCodeData) {  
    BudgetControlStdApi        .budgetControlStdService        .redeemInvitationConfirmationCode(            redeemInvitationConfirmationCodeData = redeemInvitationConfirmationCodeData,            callback = object : ApiCallback<RedeemInvitationConfirmationCodeResult> {                override fun onSuccess(response: RedeemInvitationConfirmationCodeResult) {                    /*TODO: do something with response*/                }                override fun onFailure(error: Throwable) {                    /*TODO: something went wrong*/                }            }        )}

Kotlin Coroutines

    redeemInvitationConfirmationCodeData: RedeemInvitationConfirmationCodeData): RedeemInvitationConfirmationCodeResult =  
    BudgetControlCoroutineApi        .budgetControlCoroutineService        .redeemInvitationConfirmationCode(redeemInvitationConfirmationCodeData = redeemInvitationConfirmationCodeData) ```  

**`BcSdkException`**  

| Exception        | Parameters | Description        |  |------------------|------------|--------------------|  
| ResourceNotFound |            | Resource not found |    
### 3.13 registerCardEventsListener  

```  Synchronous. Online.    

Register CardEventsListener.

3.12.1 Input

CardEventsListener

Parameter	Type	Description
CardEventsListener	Interface	Listener containing methods for responding to card events.

3.12.2 Sample

Standard Callback

    cardEventsListener: CardApiEventsListener) {  
    BudgetControlStdApi        .budgetControlStdService        .registerCardEventsListener(cardEventsListener = cardEventsListener)}

Kotlin Coroutines

    cardEventsListener: CardApiEventsListener) {  
    BudgetControlCoroutineApi        .budgetControlCoroutineService        .registerCardEventsListener(cardEventsListener = cardEventsListener)}

3.14 registerTermsAndConditionsEventsListener

Register TermsAndConditionsEventsListener.

3.12.1 Input

TermsAndConditionsEventsListener

Parameter	Type	Description
TermsAndConditionsEventsListener	Interface	Listener containing methods for responding to terms and conditions events.

3.12.2 Sample

Standard Callback

    termsAndConditionsEventsListener: TermsAndConditionsEventsListener) {  
    BudgetControlStdApi        .budgetControlStdService        .registerTermsAndConditionsEventsListener(termsAndConditionsEventsListener = termsAndConditionsEventsListener)}

Kotlin Coroutines

    cardEventsListener: TermsAndConditionsEventsListener) {  
    BudgetControlCoroutineApi        .budgetControlCoroutineService        .registerTermsAndConditionsEventsListener(termsAndConditionsEventsListener = termsAndConditionsEventsListener)}

3.15 registerApprovalEventsListener

Register ApprovalEventsListener.

3.12.1 Input

ApprovalEventsListener

Parameter	Type	Description
ApprovalEventsListener	Interface	Listener containing methods for responding to approval events.

3.12.2 Sample

Standard Callback

    approvalEventsListener: ApprovalEventsListener) {  
    BudgetControlStdApi        .budgetControlStdService        .registerApprovalEventsListener(approvalEventsListener = approvalEventsListener)}

Kotlin Coroutines

    approvalEventsListener: ApprovalEventsListener) {  
    BudgetControlCoroutineApi        .budgetControlCoroutineService        .registerApprovalEventsListener(approvalEventsListener = approvalEventsListener)}

4. Document changelog

4.1. Version 1.0.0

Created Budget Control SDK.

4.2 Version 1.0.1

Updated Koin version from 2.1.5 to 2.1.6.
Removed gradlePluginPortal.

4.3 Version 1.0.2

Refactored Configuration model.
Added certificate pinning.
Added hostname verification.

4.4 Version. 1.0.3

Created and updated documentation.

4.5 Version. 1.1.0

Added new methods to card redemption : redeemInvitation, redeemInvitationConfirmationCode.
Methods initializeRedeemCard and finalizeRedeemCard have been deprecated.

4.6 Version. 1.1.1

Disabled pinning and obfuscation for debug.

4.7 Version. 1.1.2

Updated documentation.

4.8 Version. 2.0.0

Added registerCardEventsListener method through which CardEventsListener can be registered.
Added registerTermsAndConditionsEventsListener method through
which TermsAndConditionsEventsListener can be
registered.
Added registerApprovalEventsListener method through which ApprovalEventsListener can be
registered.

4.9 Version 2.0.1

Updated koin to version 3.5.3.
Updated java to 17.
Updated compile and target android version.

4.10 Version 2.0.2

Updated enum models with default UNKNOWN value.
Changed type field from String to NotificationType for type field
from NotificationModel.
Renamed model TimeUnitModel to TimeUnit and ApprovalStatusModel to ApprovalStatus.

4.11 Version 2.0.3

Marked all enum fields in SDK result models with @Deprecated.
Added corresponding value class fields for all deprecated fields.
Deleted UnknownApprovalStatus, UnknownTimeUnit and ParseValidationErrorException exceptions.

4.12 Version 2.0.4

Improved SDKs deploying.

4.13 Version 2.0.5

Added UnknownHostException.

4.14 Version 2.0.6

Internal changes have been introduced to improve build process.

4.15 Version 2.0.7

Update koin to version 4.0.4
Update java to 21
Update compile and target android version

4.16 Version 2.0.8

Internal changes improving SDK delivery process.

4.17 Version 2.0.9

Internal. Updates build utilities.

4.18 Version 2.0.10

Internal changes improving SDK.

4.19 Version 2.0.11

Internal changes. Updated supported token handling.

Budget Control SDK

Table of Contents