Budget Control SDK
Version 2.0.9
Table of Contents
-
1.1. What is Budget Control SDK?
-
2.1. Basic information
2.2. Basic configuration
2.4. Delivery setup
2.5. Error handling
-
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.10. addApproval
3.11. redeemInvitation
3.12. redeemInvitationConfirmationCode
3.13. registerCardEventsListener
-
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)
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.
repositories {
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:
dependencies {
implementation 'pl.upaid.module:mobiledc:{version}'
implementation 'com.verestro.sdk:bc:${version}'
}
For debugging purposes:
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:
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:
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
fun init(configuration: Configuration) {
BudgetControlCoroutineApi.init(configuration)
}
BudgetControlStdApi
fun init(configuration: Configuration) {
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
Asynchronous. Online.
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
Success callback with InvitationResult model.
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 |
| 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
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 | |
| InvalidInvitationCode | Invalid invitation code |
3.1.3 Sample
Standard Callback
fun getInvitation(invitationData: InvitationData) {
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
suspend fun getInvitation(invitationData: InvitationData): InvitationResult =
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
Success callback with InitializeRedeemCardResult model.
InitializeRedeemCardResult
InitializeRedeemCardResult is an empty class.
3.2.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.2.3 Sample
Standard Callback
fun initializeRedeemCard(redeemCardData: RedeemCardData) {
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
suspend fun initializeRedeemCard(redeemCardData: RedeemCardData): InitializeRedeemCardResult =
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
Success callback with FinalizeRedeemCardResult model.
FinalizeRedeemCardResult
FinalizeRedeemCardResult is an empty class.
3.3.2.2 Failure
Failure callback with throwable.
3.3.3 Sample
Standard Callback
fun finalizeRedeemCard(
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
suspend fun finalizeRedeemCard(
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
Success callback with VcnDetailsResult model.
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
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.4.3 Sample
Standard Callback
fun getVcnDetails(vcnDetailsData: VcnDetailsData) {
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
suspend fun getVcnDetails(vcnDetailsData: VcnDetailsData): VcnDetailsResult =
BudgetControlCoroutineApi
.BudgetControlCoroutineService
.getVcnDetails(vcnDetailsData = vcnDetailsData)
3.5 getCards
Asynchronous. Online.
Provides user cards from Budget Control backend.
3.5.1 Input
No input parameters.
3.5.2 Output
3.5.2.1 Success
Success callback with CardsResult model.
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
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.5.3 Sample
Standard Callback
fun getCards() {
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
suspend fun getCards(): CardsResult =
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
Success callback with CardDetailsResult model.
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
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.6.3 Sample
Standard Callback
fun getCardDetails(cardDetailsData: CardDetailsData) {
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
suspend fun getCardDetails(cardDetailsData: CardDetailsData): CardDetailsResult =
BudgetControlCoroutineApi
.BudgetControlCoroutineService
.getCardDetails(cardDetailsData = cardDetailsData)
3.7 getAlerts
Asynchronous. Online.
Provides user alerts from Budget Control backend.
3.7.1 Input
No input parameters.
3.7.2 Output
3.7.2.1 Success
Success callback with AlertsResult model.
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
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.7.3 Sample
Standard Callback
fun getAlerts() {
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
suspend fun getAlerts(): AlertsResult =
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
Success callback with DeleteAlertResult model.
DeleteAlertResult
DeleteAlertResult is an empty class.
3.8.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.8.3 Sample
Standard Callback
fun deleteAlert(deleteAlertData: DeleteAlertData) {
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
suspend fun deleteAlert(deleteAlertData: DeleteAlertData): DeleteAlertResult =
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
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
suspend fun acceptTermsAndConditions(issuerData: IssuerData): AcceptTermsAndConditionsResult =
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
AddApprovalResult is an empty class.
3.10.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 | |
| ApprovalRequestExist | Approval request exist | |
| CardAssignedToAnotherUser | Card assigned to another user |
3.10.3 Sample
Standard Callback
fun addApproval(addApprovalData: AddApprovalData) {
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
suspend fun addApproval(addApprovalData: AddApprovalData): AddApprovalResult =
BudgetControlCoroutineApi
.BudgetControlCoroutineService
.addApproval(addApprovalData = addApprovalData)
3.11 redeemInvitation
Asynchronous. Online.
Initialize reedem card process.
3.11.1 Input
RedeemInvitationData
| Parameter | Type | Description |
|---|---|---|
| invitationCode | String | Invitation code that will be required to initialize invitation acceptance process |
3.11.2 Output
3.11.2.1 Success
Success callback with RedeemInvitationResult model.
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
Failure callback with throwable.
BcSdkException
| Exception | Description |
|---|---|
| ResourceNotFound | Resource not found |
3.11.3 Sample
Standard Callback
fun redeemInvitation(redeemInvitationData: RedeemInvitationData) {
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
suspend fun redeemInvitation(redeemInvitationData: RedeemInvitationData): RedeemInvitationResult =
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
Success callback with RedeemInvitationConfirmationCodeResult model. RedeemInvitationConfirmationCodeResult is an empty class.
3.12.2.2 Failure
Failure callback with throwable.
3.12.3 Sample
Standard Callback
fun redeemInvitationConfirmationCode(
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
suspend fun redeemInvitationConfirmationCode(
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
fun registerCardEventsListener(
cardEventsListener: CardApiEventsListener
) {
BudgetControlStdApi
.budgetControlStdService
.registerCardEventsListener(cardEventsListener = cardEventsListener)
}
Kotlin Coroutines
fun registerCardEventsListener(
cardEventsListener: CardApiEventsListener
) {
BudgetControlCoroutineApi
.budgetControlCoroutineService
.registerCardEventsListener(cardEventsListener = cardEventsListener)
}
3.14 registerTermsAndConditionsEventsListener
Synchronous. Online.
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
fun registerTermsAndConditionsEventsListener(
termsAndConditionsEventsListener: TermsAndConditionsEventsListener
) {
BudgetControlStdApi
.budgetControlStdService
.registerTermsAndConditionsEventsListener(termsAndConditionsEventsListener = termsAndConditionsEventsListener)
}
Kotlin Coroutines
fun registerTermsAndConditionsEventsListener(
cardEventsListener: TermsAndConditionsEventsListener
) {
BudgetControlCoroutineApi
.budgetControlCoroutineService
.registerTermsAndConditionsEventsListener(termsAndConditionsEventsListener = termsAndConditionsEventsListener)
}
3.15 registerApprovalEventsListener
Synchronous. Online.
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
fun registerApprovalEventsListener(
approvalEventsListener: ApprovalEventsListener
) {
BudgetControlStdApi
.budgetControlStdService
.registerApprovalEventsListener(approvalEventsListener = approvalEventsListener)
}
Kotlin Coroutines
fun registerApprovalEventsListener(
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
initializeRedeemCardandfinalizeRedeemCardhave 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
registerCardEventsListenermethod through whichCardEventsListenercan be registered. - Added
registerTermsAndConditionsEventsListenermethod through whichTermsAndConditionsEventsListenercan be registered. - Added
registerApprovalEventsListenermethod through whichApprovalEventsListenercan 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
UNKNOWNvalue. - Changed type field from
StringtoNotificationTypefortypefield fromNotificationModel. - Renamed model
TimeUnitModeltoTimeUnitandApprovalStatusModeltoApprovalStatus.
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,UnknownTimeUnitandParseValidationErrorExceptionexceptions.
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.