Budget Control SDK

Version 1.1.1

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. 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
Document changelog

4.1 Version 1.0.0

4.2 Version 1.0.1

4.3 Version 1.0.2

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.upaid.pl/artifactory/libs-release-local/"
	}
}

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.
Debug version is ended with appendix "-debug" in version name.
Samples below.

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

    
  

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

For debugging purposes:

    
  

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

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

2.3.2 Sample

BudgetControlCoroutineApi

    
  

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

BudgetControlStdApi

    
  

    
fun init(configuration: Configuration) {  
	BudgetControlStdApi.init(configuration)
}

2.4 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.
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.
UnknownApprovalStatus		Unknown approval status
UnknownTimeUnit		An unknown time unit - available 3 types DAILY, WEEKLY, MONTHLY.
ValidationException		Contains list of ValidationError.
ParseValidationErrorException		Error occurs while validation exception parsing.

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

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

    
  

    
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

PeriodicLimitModel

Parameter	Type	Description
limitMinor	Long	Card limit to be used
timeUnit	TimeUnitModel	Time unit

TimeUnitModel

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

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
UnknownTimeUnit		An unknown time unit - available 3 types DAILY, WEEKLY, MONTHLY

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	String	Notification type
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	Approval status
lastFourDigits	CharArray	Last four digits of user card
currencyCode	String	Currency code (ISO 4217, three letter code)

ApprovalStatus

Reason	Description
ACCEPTED	Approval status accepted
REJECTED	Approval status rejected

PeriodicLimitModel

Parameter	Type	Description
limitMinor	Long	Card limit to be used
timeUnit	TimeUnitModel	Time unit

TimeUnitModel

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

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
UnknownApprovalStatus		Unknown approval status
UnknownTimeUnit		An unknown time unit - available 3 types DAILY, WEEKLY, MONTHLY

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	Time unit

TimeUnit

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

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
UnknownTimeUnit		An unknown time unit - available 3 types DAILY, WEEKLY, MONTHLY

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

4. Document changelog

4.1. Version 1.0.0

Created Budget Control SDK

4.2 Version 1.0.1

Update Koin version from 2.1.5 to 2.1.6
Remove gradlePluginPortal

4.3 Version 1.0.2

Refactor Configuration model
Add certificate pinning
Add hostname verification

Version. 1.0.3

Create and update documentation

Version. 1.1.0

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

Version. 1.1.1

Disables pinning and obfuscation for debug

Version. 1.1.2

Updates documentation

Budget Control SDK

Table of Contents