# Technical documentation MDC SDK ### Basic abbreviations and definitions
**Field** | **Description** |
---|---|
FCM | Firebase Cloud Messaging |
DC | Data Core |
MDC | Mobile DC module |
MPA | Mobile Payment Application |
UCP | Verestro Cloud Payments |
IBAN | Back Account Number |
JWT | Json Web Token |
JWE | Json Web Encryption |
OTP | One-time password |
```
repositories{
maven {
credentials {
username " |
``` dependencies{ implementation 'pl.upaid.module:mobiledc:{version}' } ``` |
``` dependencies{ implementation 'pl.upaid.module:mobiledc:{version}-debug' } ``` |
```
|
``` dependencies{ implementation 'androidx.work:work-runtime-ktx:2.7.1' } ``` |
```
//AndroidManifest.xml
|
``` //build.gradle android { packagingOptions { jniLibs { useLegacyPackaging false } } } ``` |
``` android { ... kotlinOptions { freeCompilerArgs = [ '-Xno-param-assertions', '-Xno-call-assertions', '-Xno-receiver-assertions' ] } packagingOptions { exclude '/kotlin_metadata/**' } ... } ``` |
``` android.enableR8=true ``` |
```
|
**Format** | **Size** | **Notes** |
---|---|---|
APK | ~15,1 MB | |
Bundle | ~2,5 MB - ~3,6 MB | Ranged size depends on the ABI of the device. SDK contains native libraries used by different ABI. By using a bundle only the necessary version of the native library will be downloaded to a device. |
```
//java sample
cardsService.getAll(
new SuccessDataCallback
|
**Exception type** | **Exception class** | **Description** |
---|---|---|
SDK Validation | ValidationException | Every parameter provided in method is validated locally by SDK. For example, card number is validated with Luhn algorithm Exception object contains field reason with detailed error code |
Backend | BackendException | Provides additional validation or error on backend side Exception object contains field *reasonCode* and *message* 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 raeson in table below |
Internal Sdk | CoreSdkException | Provides additional information about error in SDK Exception object contains field reason and message 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 raeson in table below |
Process related | - | As every process is different some methods could throw specified exception. Types of exception is described in method description |
Network | NetworkConnectionException | Provide information about network connection error. Check table with possible reasons below |
Internal | UnknownException | For unknown errors in SDK process |
**Reason code** | **Description** |
INTERNAL\_ERROR | Error occurred on server |
CRYPTOGRAPHY\_ERROR | Error occurred during cryptography operation |
VALIDATION\_ERROR | Client sent invalid data |
CLIENT\_NOT\_FOUND | Requested client id not found |
CARD\_NO\_OUTSIDE\_RANGE\_BINS | Card number is outside of preconfigured range |
CARD\_KIND\_LIMIT\_REACHED | Card kind limit reached |
CARD\_DELETED | Card was deleted and operation cannot be proceed |
FAIL\_3DS\_VERIFICATION | 3ds verification failed |
FAIL\_AUTHORIZATION | Fail authorization - error from card verification |
TRANSACTION\_DENIED | Transaction denied - error from card verification |
FAIL\_AUTHENTICATION | Invalid username or password |
CARD\_EXPIRED | Card expired |
LIMITS\_EXCEEDED | Limit of transactions has been exceeded |
REJECTED\_BY\_BANK | Current transaction has been rejected by bank - error from card verification |
INSUFFICIENT\_FOUNDS | There is no enough founds on card to complete this transaction |
INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
INVALID\_FCM\_TOKEN | Given FCM token is invalid |
OPERATION\_NOT\_SUPPORTED | Method is not allowed |
CANT\_FIND\_USER | Cannot find user by requested identifier |
CANT\_FIND\_CARD | Cannot find card by requested identifier |
CANT\_FIND\_DEVICE | Cannot find device by requested identifier |
CANT\_FIND\_WPIN | Cannot find wallet pin |
CANT\_FIND\_ADDRESS | Cannot find requested address |
CANT\_FIND\_INVITATION | Cannot find invitation for the requested resource |
RESOURCE\_NOT\_FOUND | Cannot find requested resource |
USER\_IS\_LOCKED | Requested user is locked |
CARD\_IS\_LOCKED | Requested card is locked |
DEVICE\_PERMANENTLY\_LOCKED | Requested device is locked |
DEVICE\_TEMPORARILY\_LOCKED | Requested device is temporary locked |
BAD\_LOGIN\_LIMIT\_REACHED | Number of incorrect login attempts is reached |
BAD\_WPIN\_LIMIT\_REACHED | Requested user is temporary locked |
SMS\_FAILCOUNT\_REACHED | Sms fail count limit reached |
TOO\_MANY\_REQUESTS | Too Many Requests |
CARD\_IS\_ALREADY\_VERIFIED | Requested card has been verified |
USER\_IS\_NOT\_VERIFIED | User is not verified. E.g. User had registered already however did not finish the verification step and is trying to pair/login |
PAYMENT\_ALREADY\_SUCCESS | Requested payment has been already finished |
INVALID\_CARD | Card is invalid for this payment |
USER\_HAS\_NOT\_SET\_A\_PASSWORD | Requested user has not set password |
DEVICE\_LIMIT\_REACHED | Number of device is reached |
BAD\_WPIN | The wallet pin does not match the requested user |
SMS\_LIMIT\_EXCEEDED | Number of sent messages has reached the limit. Please try again later |
FAIL\_COUNT\_LIMIT\_REACHED | Attempt limit has exceeded |
INITIALIZE\_PROCESS\_REQUIRED | Fail count limit has been reached and new process has not been initialized |
INVALID\_AUTHORIZATION\_AMOUNT | Authorization amount is incorrect |
CLIENT\_UNAUTHORIZED | Client of the api is unauthorized(invalid/expired *X-Client-Auth* token) |
USER\_UNAUTHORIZED | User is unauthorized |
VERIFICATION\_FAILED | Requested card could not be verified |
CARD\_NOT\_ENROLLED | Card does not participate in 3ds v2, please use 3ds v1 |
INVALID\_AUTHENTICATION\_ID | Authentication process id does not match card id |
ATTESTATION\_FAILED | The attestation request failed |
ATTESTATION\_PLAY\_INTEGRITY\_REQUIRED | The Play Store app is not installed, or it is not the official version, or it is an old version |
**Reason code** | **Description** |
TRANSACTION\_ATTACHMENT\_STATUS\_APPROVED | Cannot update transaction or store new attachment. Attachment status in transaction is APPROVED |
MAX\_ATTACHMENTS\_COUNT | Maximum number of attachments for given transaction |
MAX\_ATTACHMENT\_SIZE\_EXCEEDED | Maximum attachment size exceeded |
EMPTY\_ATTACHMENT | Empty attachment file |
EMPTY\_ATTACHMENT\_NAME | Empty attachment file name |
NOT\_SUPPORTED\_ATTACHMENT\_FILE\_TYPE | Attachment file type is not supported |
CANT\_FIND\_TRANSACTION\_ATTACHMENT | Cannot find transaction attachment |
Reason code | Description |
---|---|
DEVICE\_NOT\_PAIRED | Device is not paired or trying to call the method without device pairing |
SAFETYNET\_ERROR | An error during device authentication in Google SafetyNet service Deprecated, replaced by ATTESTATION\_API\_ERROR |
PUSH\_INVALID\_SOURCE | Relates to push processing process. Push message should be consumed in another module |
PUSH\_INVALID\_PUSH\_CONTENT | Cannot process push message. The message is invalid or some process failed |
BIOMETRIC\_AUTHENTICATION\_NOT\_ENABLED | Biometric public key is invalid |
BIOMETRIC\_AUTHENTICATION\_ABORTED | Cannot authenticate biometric signature |
KEYSTORE\_IS\_NOT\_SECURE | Keystore is not secure. The device is not secured with PIN, pattern or password |
CANNOT\_GET\_PUBLIC\_KEY | Internal error during SDK processing |
SECURITY\_EVENT\_OCCURRED | Security event occurred during application usage. Data is cleared and the method can't be used. Application is always informed about a security issue with onSecurityIssueAppeared callback initialized in setup() method |
PIN\_AUTHENTICATION\_FAILURE | Provided PIN is invalid |
PIN\_AUTHENTICATION\_FAILURE\_LIMIT\_EXCEEDED | PIN fail count is reached, every next try PIN authentication will finish with this status |
PIN\_AUTHENTICATION\_NOT\_POSSIBLE | PIN authentication is not possible until the user is at least once logged online with PIN |
PIN\_AUTHENTICATION\_INTERNAL\_ERROR | Something went wrong during PIN authentication |
PAIRING\_IS\_ALREADY\_IN\_PROGRESS | Another pairing is now processed |
PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND | No default payment instrument for contactless payment found |
PAYMENT\_INSTRUMENT\_NOT\_FOUND | Payment instrument with this id cannot be found in SDK |
APPLICATION\_PROCESS\_NOT\_KILLED | Application process is not killed after SDK reset |
TOKEN\_NOT\_ACTIVE | Required token status is ACTIVE |
PAYMENT\_INSTRUMENT\_NOT\_FOUND | Token with that id was not found in SDK |
API\_SERVICE\_NOT\_INITIALIZED | API service was not initialized |
DIGITIZATION\_NOT\_STARTED | Digitization of that payment instrument was not started |
ATTESTATION\_API\_ERROR | An error during device authentication in Device Attestation service (Play Integrity) |
**Reason code** | **Description** |
---|---|
UNKNOWN\_HOST | Host is unreachable, check network connection and try again later |
SOCKET\_TIMEOUT | Connection timeout, check network connection and try again later |
UNKNOWN\_HTTP\_ERROR | An unknown HTTP error |
``` ... implementation('com.google.firebase:firebase-messaging:22.0.0') ... ``` |
``` val firebaseOptions = FirebaseOptions .Builder() .setApplicationId(applicationId) .setGcmSenderId(senderId) .setProjectId(projectId) .setApiKey(apiKey) .build() FirebaseApp.initializeApp(this, firebaseOptions) ``` |
``` //init default project FirebaseApp.initializeApp(this, firebaseOptions) //init additional project FirebaseApp.initializeApp(this, firebaseOptionsOther, otherProjectName) ``` |
``` //getting token for default project FirebaseMessaging.getInstance().token .addOnCompleteListener { //handle token } //getting token for additional project val messaging = FirebaseApp.getInstance("other").get(FirebaseMessaging::class.java) messaging.token.addOnCompleteListener { //handle token } ``` |
**Code** | **Meaning** |
---|---|
80a1 | Device is rooted |
80b1 | SDK cannot be used on emulator |
811a | User has installed some harmful application on device |
8a9b | User has attached debugger during SDK usage |
``` //Mobile DC setup configuration for enableAdditionalSecurityChecks val developerOptions = DeveloperOptions() developerOptions.enableAdditionalSecurityChecks = true MobileDcApiConfigurationBuilder() // other require configuration .withOptionalDeveloperOptions(developerOptions) //Sample Application declaration for handing isolated process class SampleApplication : Application { override fun onCreate() { super.onCreate() if (isIsolatedProcess()) { return } //sample methods called in application startKoin() initializeMobileDcModule() initUcpModule() initFirebase() //other methods.. } private fun isIsolatedProcess(): Boolean { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) { android.os.Process.isIsolated() } else { try { val activityManager = getSystemService(ACTIVITY_SERVICE) as ActivityManager activityManager.runningAppProcesses false } catch (securityException: SecurityException) { securityException.message?.contains("isolated", true) ?: false } catch (exception: Exception) { false } } } } ``` |
DN cannot change during certificate renewals and all intermediate certificates should be placed in JWT |
Some data like Token Verification Code can be encrypted using JWE per RFC 7516. |
**JWE header** | **Name** | **Description** |
---|---|---|
alg | RSA-OAEP-256 | Cryptographic algorithm used to encrypt CEK |
enc | A256GCM | Identifies the content encryption algorithm used to perform authenticated encryption |
``` class RsaJweDecrypter { @Throws(Exception::class) fun decrypt(encryptedData: String, privateKey: PrivateKey): ByteArray { val parse = JWEObject.parse(encryptedData) parse.decrypt(RSADecrypter(privateKey)) return parse.payload.toBytes() } } ``` |
Some fields are signed using JWT per RFC 7519. Data signing should be done on **server side**. |
``` {Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature} ``` |
**Name** | **Description** |
---|---|
iat | The time at which the JWT was issued. UNIX Epoch timestamp, in seconds |
jti | JWT ID - unique identifier for the JWT |
**Name** | **Description** |
---|---|
x5c | Parameter contains the X.509 certificates chain ([RFC7515#section-4.1.6](https://tools.ietf.org/html/rfc7515#section-4.1.6)) |
```
class JwtGenerator {
fun generate(
jwtClaimsSet: JWTClaimsSet,
certificates: List |
Some fields are signed on Wallet Server using JWT per RFC 7519. |
``` {Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature} ``` |
**Name** | **Description** |
---|---|
iat | The time at which the JWT was issued. UNIX Epoch timestamp, in seconds |
jti | JWT ID - unique identifier for the JWT |
**Name** | **Description** |
---|---|
kid | fingerprint of public key which's corresponding private key was used to sign data calculated as sha1Hex(publicKeyBytes) |
``` class JWTVerifier { fun verify( signedData: String, rsaPublicKey: RSAPublicKey, iatToleranceSeconds: Long ): JWTClaimsSet { val signedJWT = SignedJWT.parse(signedData) val signatureResult = signedJWT.verify(RSASSAVerifier(rsaPublicKey)) if (!signatureResult) { throw ValidationException("Invalid signature") } val jwtClaimsSet = signedJWT.getJWTClaimsSet() //optionally check iat with tolerance val isIatInAllowedTimeRange = jwtClaimsSet .getIssueTime() .toInstant() .plusSeconds(iatToleranceSeconds) .isAfter(Instant.now()) if (!isIatInAllowedTimeRange) { throw ValidationException("Signed JWT expired") } return jwtClaimsSet } } ``` |
``` keytool -importkeystore -srckeystore cert.jks -destkeystore cert.p12 -srcstoretype jks -deststoretype pkcs12 ``` |
``` openssl pkcs12 -nokeys -in cert.p12 -out cert.pem ``` |
``` openssl x509 -inform der -in deployment_cert.der -out certificate.pem ``` |
**Parameter** | **Type** | **Description** |
---|---|---|
xRateLimitLimit | Int? | Limit of requests until resource will be locked |
xRateLimitRemaining | Int? | Remaining amount of requests |
retryAfter | Int? | Seconds until lock expires |
xRateLimitReset | Long? | Lock expiration timestamp - epoch in seconds |
Asynchronous. Offline. Mobile DC initialization method. Contains all necessary data to configure SDK. Should be called at very beginning of application lifecycle. For example in Android Application::onCreate method. Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished. When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand. **Note:** Please be aware to use this method before usage of any MobileDC methods or another Verestro product. |
**SDK Event Listeners - errors catching** The application should prevent throwing exceptions in MDC SDK Event Listeners described below as it could cause breaking process in SDK. In case of error in application event listener implementation SDK runs this code in try-catch block. |
**Method** | **Parameter** | **Description** | **Validation conditions** |
---|---|---|---|
withApplicationContext | Context | Application context | Not empty |
withWalletSecurityEventListener | WalletSecurityEventListener | Global listener for security events | Not empty |
withOptionalLogger | EventsLogger | Handler for secure logging of sdk events | |
withOptionalDeveloperOptions | DeveloperOptions | Additional options for developers | |
withOptionalMobileDcTransactionEventListener | MobileDcTransactionEventListener | Global listener for all transactions that may occur from our wallet server. If you use this listener you should not do any action on events from UcpConfigurationBuilder.withUcpTransaction(UcpTransactionEventListener) because callbacks may duplicate. |
**Method** | **Parameter** | **Description** | **Validation conditions** |
---|---|---|---|
withApplicationContext | Context | Application context | Not null |
withMobileDcConnection Configuration | MobileDcConnection Configuration | Mobile DC API connection configuration delivered by Verestro | Not empty |
withWalletSecurityEventListener | WalletSecurityEventListener | Global listener for security events | Not empty |
withOptionalWalletPin Configuration | MobileDcWalletPin Configuration | Wallet Pin configuration in SDK | |
withOptionalLogger | EventsLogger | Handler for secure logging of sdk events | |
withOptionalDeveloperOptions | DeveloperOptions | Additional options for developers | |
withOptionalCloudMessaging Configuration | MobileDcCloudMessaging Configuration | Interface for providing cloud messaging configuration like. For now used only for FCM registration token. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
url | String | Url for mobile DC environment in which SDK connect. Depending on the deployment model the Wallet Server can be deployed on the Customer infrastructure or provided by Verestro. Different for development and production environment. For more details please contact Verestro representative. | Not empty |
pinningCertificates | List<String> | List of public key certificate in PEM associated with host server. Certificate is used for certificate pinning during connection to Wallet Server. Certificate is associated with the Wallet Server and like the url its value depends on the deployment model. When used services hosted on Verestro side please contact Verestro representative. | Not empty |
clientId | String | Each customer has a unique client id it's different for development and production environment. ClientId should be provided by Verestro representative. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pinFailCount | Int | Number of possible fails in offline pin verification | Greater then 0 |
**Method** | **Parameters** | **Description** |
---|---|---|
onSecurityIssueAppeared | EventSecurityIssueAppeared (tag: Int, code: Int, message:String) | Information about security issue. Due to security requirements this message isn’t readable for user When using setup(MobileDcApiConfiguration) SDK reports event instantly to server (when internet is available). Could be also catched on application side and reported by client. Some error codes could be properly handled in application [Security processes overview](https://wiki.verestro.com/display/UCP/Security+processes+overview) |
**Method** | **Parameters** | **Description** |
---|---|---|
onEvent | onEvent(eventId:Int) | Callback to trace list of events that occured in SDK (those are secure aliases - event as Integer). You can collect 'em in ordered list and store to be accesible in case of errors/exceptions. |
**Parameter** | **Type** | **Description** |
---|---|---|
allowDebug | Boolean | Determine AndroidManifest *android:debuggable* state in *<application>* scope. When configured as true SDK verifies combination of SDK production(without -debug) version and *android:debuggable*=true. |
enableAdditionalSecurityChecks | Boolean | Enables additional security checks in application required during EMV Security Evaluation. Enabling requires additional action on application side, refer to [Application Isolated Process](https://wiki.verestro.com/display/UCP/Application+Isolated+Process) to get more details. Added in version 2.4.3. |
enableCodeObfuscationCheck | Boolean | Enable additional check if application obfuscates SDK facade classes. Default value is false. |
**Parameter** | **Type** | **Description** |
---|---|---|
cloudMessaging RegistrationToken | CloudMessaging RegistrationProvider | Provides information about Cloud Messaging service. |
**Method** | **Parameters** | **Description** |
---|---|---|
getRegistrationToken | - | Gets actual FCM registration token from application. Used for device registration in new delivey message service with RNS and SSE channels during *login* process. It is applied for devices where SDK before 2.14.6 was used and device is already paired. |
**Parameter** | **Type** | **Description** |
---|---|---|
type | CloudMessagingType | Mandatory. One of: \[FCM, EXTERNAL\]. FCM - Firebase Cloud Messaging EXTERNAL - External token for external source of RNS |
token | String | Registaration token for push notifications |
**Parameter** | **Type** | **Description** |
---|---|---|
onNewTransaction | EventNewTransaction | Plain EventNewTransaction object |
**Parameter** | **Type** | **Description** |
---|---|---|
newTransaction | NewTransaction | Plain NewTransaction object |
**Parameter** | **Type** | **Description** |
---|---|---|
id | Long | The internal transaction id |
clientTransactionId | String | The client id of transaction |
type | String | Transaction type. One of: PURCHASE - purchase in context of payment for goods, REFUND - refund, PAYMENT - in context of peer2peer card payment cardholder receives money, FUNDING - in context of peer2peer card payment cardholder sends money, ATM\_WITHDRAWAL - cash withdrawal in ATM, CASH\_DISBURSEMENT - cash disbursement, ATM\_DEPOSIT - cash deposit in ATM, ATM\_TRANSFER - money transferred with ATM usage, CASHBACK - cashback, FEE - fees related with account, cards etc., LOAN - loan, LOAN\_REPAYMENT - loan repayment, COMMISSION - commission related to some service, TOP\_UP - money received using bank transfer, WITHDRAWAL - withdrawal in context of money transfer to different bank account, INTEREST - fees of loan funding |
amountMinor | Long | The transaction monetary amount in terms of the minor units of the currency. For example, EUR 2.35 will return 235, and BHD -1.345 will return -1345. Negative amounts indicate a refund or payment |
currency | String | The transaction currency. 3-digit ISO 4217 currency code |
merchantName | String? | Optional. The merchant name |
```
var eventsTrace = arrayListOf |
``` class App : Application() { override fun onCreate() { super.onCreate() if (isIsolatedProcess()) { return } //call all required methods } } ``` |
Asynchronous. Online. Adds new address with given parameters. |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
street | CharArray? | Street | - |
number | CharArray? | Number | - |
apartment | CharArray? | Apartment | - |
city | CharArray? | City | - |
isBilling | Boolean? | Is invoice address | - |
isShipping | Boolean? | Is Shipping address | - |
zipCode | CharArray? | Zip code | - |
countryId | Int? | Country identifier | - |
vatNo | CharArray? | Vat number | - |
companyName | CharArray? | Company name | - |
firstName | CharArray? | First name | - |
lastName | CharArray? | Last name | - |
province | CharArray? | Province | - |
district | CharArray? | District | - |
additional | CharArray? | (Optional) Additional field | - |
Success with Long value as addressId / failure callback. |
``` fun addAdress(addAddress: AddAddress) { mobileDcApi .addressesService .addAddress(addAddress, { addressId -> // Address added }, { // Something went wrong // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Gets all addresses for the current user. |
No input parameters. |
Success callback with list of user addresses. |
**Parameter** | **Type** | **Description** |
---|---|---|
addresses | List <Address> | List of user addresses |
**Parameter** | **Type** | **Description** |
---|---|---|
id | Int | Id of the address |
street | CharArray? | Street |
number | CharArray? | Number |
apartment | CharArray? | Apartment |
city | CharArray? | City |
isBilling | Boolean? | Is invoice address |
isShipping | Boolean? | Is Shipping address |
zipCode | CharArray? | Zip code |
country | Country? | Country |
vatNo | CharArray? | Vat number |
companyName | CharArray? | Company name |
firstName | CharArray? | First name |
lastName | CharArray? | Last name |
province | CharArray? | Province |
district | CharArray? | District |
additional | CharArray? | Additional field |
**Parameter** | **Type** | **Description** |
---|---|---|
id | Int | Id of the country |
code | CharArray? | Country code |
currency | CharArray? | Currency code |
currencyNumeric | CharArray? | Numeric currency code |
prefix | CharArray? | Prefix telephone number for a given country |
regexp | CharArray? | The phone number validation rule for a given country |
name | CharArray? | The currency's name |
currencyName | CharArray? | Country |
language | CharArray? | Official language |
``` fun getAll() { mobileDcApi .addressesService .getAll({ // List of addresses }, { throwable -> // Something went wrong // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Update address for the current id. |
**Parameter** | **Type** | **Description** |
---|---|---|
updateAddress | UpdateAddress | An object containing address data to update |
**Parameter** | **Type** | **Description** |
---|---|---|
addressId | Long | Id of the address |
street | CharArray? | Street |
number | CharArray? | Number |
apartment | CharArray? | Apartment |
city | CharArray? | City |
isBilling | Boolean? | Is invoice address |
isShipping | Boolean? | Is shipping address |
zipCode | CharArray? | Zip code |
countryId | Int? | Country identifier |
vatNo | CharArray? | Vat number |
companyName | CharArray? | Company Name |
firstName | CharArray? | First name |
lastName | CharArray? | Last name |
province | CharArray? | Province |
district | CharArray? | District |
additionalField | CharArray? | Additional filed |
Success / Failure callback. |
``` private fun updateAddress(updateAddress: UpdateAddress) { mobileDcApi .addressesService .updateAddress(updateAddress, { //address updated successfully }, { throwable -> // Something went wrong, maybe user data was incorrect // Check exceptions described in Error handling chapter }) } ``` |
Method for delete user address with given address id. |
**Parameter** | **Type** | **Description** |
---|---|---|
addressId | Long | (Required) Unique address id |
Success callback/ Failure callback. |
``` fun deleteAddress(addressId: Long) { mobileDcApi .addressesService .deleteAddress(addressId, { //Success, address deleted }, { //Something went wrong //Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online.
Creates new user wallet account with given parameters.
**Input** NewUser model is required, but most of it's fields are optional. Fields requirement depends on product integration process.**Parameter** | **Type** | **Description** | **Validation coditions** |
---|---|---|---|
newUser | NewUser | An object containing user data | (Required) |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
phone | CharArray? | User's phone number | Phone with country prefix. For pl: 48500500500 |
CharArray? | User's email address | Email format if any value passed | |
firstName | CharArray? | User's first name | |
lastName | CharArray? | User's last name | |
walletPin | CharArray? | User's wallet pin | 4 to 8 digits if passed |
password | CharArray? | User's password | Password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
accepted Marketing | Boolean | True if user accepted marketing agreement, false otherwise | - |
invitationCode | CharArray? | Invitation code used in a specific server configuration | (Conditional/Optional) - depends on specific server configuration |
nip | String? | Taxpayer identification number | Not empty if passed |
accepted Regulations | Boolean? | Information if user has accepted regulations agreement | |
acceptedMarketing Receiving | Boolean? | Information if user has accepted marketing consent |
Success / failure callback.
**Sample**`fun addUser(newUser: NewUser) {` ` ``mobileDcApi` ` ``.userService` ` ``.addUser(newUser, {` ` ``//new user is added successfully` ` ``}, { throwable ->` ` ``// Something went wrong, maybe user data was incorrect` ` ``// Check exceptions described in Error handling chapter` ` ``})` `}` |
Asynchronous. Online. Creates new user wallet account with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
phone | CharArray? | User's phone number | Phone with country prefix. For pl: 48500500500 |
CharArray? | User's email address | Email format if any value passed | |
firstName | CharArray? | User's first name | |
lastName | CharArray? | User's last name | |
walletPin | CharArray? | User's wallet pin | 4 to 8 digits if passed |
password | CharArray? | User's password | Password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
acceptedMarketing | Boolean | True if user accepted marketing agreement, false otherwise | - |
Success / failure callback. |
Asynchronous. Online. Creates new user wallet account if not exist with IBAN in Mobile DC backend. When user already exist calling this method will be also finished with success. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
signedAccountInfo | String | Signed AccountInfo per RFC 7519 generated on Client server side Instruction how to sign data with JWT can be found in [*Data signing and encryption*](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation-mdc-sdk#bkmrk-data-signing-and-enc) chapter | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userId | String | External user id given by the client | Not empty |
iban | String | Bank Account Number | Not empty |
countryCode | String | The country of the financial account Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 | Not empty |
Success callback. Called when new user is created or already exist with passed input data. |
**Parameter** | **Type** | **Description** |
---|---|---|
ibanId | String | Hash (sha256) of provided IBAN |
Failure callback. |
``` class SignedAccountInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .claim("iban", "IN15HIND23467433866365") .claim("countryCode", "IND") .build() val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey) // ... } } ``` |
``` private fun addUserWithIban() { val signedAccountInfo: String = getSignedAccountInfo() mobileDcApi .userService .addUserWithIban(signedAccountInfo, { ibanId -> //user already exist or was added with selected iban }, { //failure, check exceptions, maybe signedAccountInfo is wrong? }) } ``` |
Asynchronous. Online. Update user wallet account with given parameters. Most of it's fields are optional. Fields requirement depends on product integration process. |
**Parameter** | **Type** | **Description** | **Validation coditions** |
---|---|---|---|
updateUser | UpdateUser | An object containing user data to update | (Required) |
**Parameter** | **Type** | **Description** |
---|---|---|
firstName | CharArray? | User's first name |
lastName | CharArray? | User's last name |
acceptedMarketing | Boolean? | True if user accepted marketing agreement, false otherwise |
acceptedRegulations | Boolean? | Accepted regulations agreement |
acceptedMarketingReceiving | Boolean? | Accepted marketing consent |
Success / failure callback. |
``` fun updateUser(updateUser: UpdateUser) { mobileDcApi .userService .updateUser(updateUser, { //user updated successfully }, { throwable -> // Something went wrong, maybe user data was incorrect // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Get data of current user. |
No input parameters. |
Success callback with User model. |
**Parameter** | **Type** | **Description** |
---|---|---|
user | User | User data |
**Parameter** | **Type** | **Description** |
---|---|---|
userId | Long | Id of registered user |
firstName | CharArray? | First name of the user (required depending on server configuration) |
lastName | CharArray? | Last name of the user (required depending on server configuration) |
phone | CharArray? | Phone with country prefix. For pl: 48500500500 (required depending on server configuration) |
CharArray? | Email of the user (required depending on server configuration) | |
birthDate | CharArray? | Birth date in format yyyy-MM-dd |
gender | CharArray? | Gender: \[M, F\] |
acceptTos | CharArray? | Date when user accepted regulations in format yyyy-MM-dd hh:mm:ss |
acceptMarketing | CharArray? | Date when user accepted marketing info in format yyyy-MM-dd hh:mm:ss |
isLocked | Boolean? | True if user is locked, false otherwise |
deactivated | Boolean? | True if user is deactivated, false otherwise |
status | CharArray? | User status: \[ACTIVE, LOCKED, DEACTIVATED\] |
verified | Boolean? | True if user is verified, false otherwise |
kyc | CharArray? | User’s KYC verification status, one of: \[SUCCESS, REJECTED, IN\_PROGRESS\] |
created | CharArray? | Date of creation user in DB |
failCount | Int? | Number of failed authentication attempts |
hasSetPassword | Boolean? | True if user has password set, false otherwise |
lastPasswordChange | CharArray? | Last password change in format yyyy-MM-dd |
lockTo | CharArray? | Time for which user is locked in format Y-m-d H:i:s |
lastActivity | CharArray? | Data of user last activity in format yyyy-MM-dd hh:mm:ss |
country | Country | Country object |
acceptMarketingReceiving | CharArray? | Date when user accepted marketing consent in format yyyy-MM-dd hh:mm:ss |
**Field** | **Type** | **Description** |
---|---|---|
id | Long | Country identifier |
code | CharArray | Country code in accordance with the ISO 3166-2 standard |
prefix | CharArray | Prefix telephone number for a given country |
name | CharArray | Country name |
Failure callback. |
``` fun getUser() { mobileDcApi.userService .getUser({ user -> // Getting user went successfully showUser(user) }, { throwable -> // Something went wrong // Check exceptions described in error handling chapter }) } ``` |
Asynchronous. Online. Activate user account by finalizing registration process with SMS code sent to the phone number provided during new user wallet account creation. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
otp | CharArray | One time password (sent via SMS as a result of successful new user wallet account creation) | Not empty |
Success / failure callback. |
``` fun finalizeUserRegistration(otp: CharArray) { mobileDcApi .userService .finalizeUserRegistration(otp, { // User wallet account was successfully activated }, { throwable -> // Something went wrong. // Check exceptions described in error handling chapter }) } ``` |
Asynchronous. Offline. Authenticates user locally after providing correct pin. Provide method to verify user without connection into Mobile DC. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pin | CharArray | Wallet Pin created during user registration process associated with user account. (see: [addUser (deprecated)](https://wiki.verestro.com/pages/viewpage.action?pageId=67340747)) | Not empty. |
Success / failure callback. |
``` fun authenticateByPin(mobileDcApi: MobileDcApiKotlin, pin: CharArray) { //Wallet Pin created during user registration process associated with user account mobileDcApi .userService .authenticateByPin(pin, { //user is verified }, { throwable -> // Something went wrong, maybe pin is incorrect? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Offline. Method that check if biometric authentication is enabled. **Note:** Authentication could be disabled by system when Android Keystore state changed (eg. User disabled screen lock or add new authentication method). State of biometrics should be checked before every biometrics authentication usage. |
Success callback with status of authentication or failure callback. |
``` fun isBiometricAuthenticationEnabled() { mobileDcApi .userService .isBiometricAuthenticationEnabled({ isBiometricEnabled -> if (isBiometricEnabled) { // Biometric authentication is enabled, process startBiometricAuthentication method } else { // Biometric authentication is disabled, use enableBiometricAuthentication } }, { throwable -> // Something went wrong // Check exceptions }) } ``` |
Asynchronous. Online. Method for enabling device level authentication and updating biometric public key. To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userName | CharArray | Current username | Not empty |
password | CharArray | Current password | Not empty |
biometricAuthType | BiometricAuthType (BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE) | Type of biometrics to enable during device pairing process. | Not null |
Success / failure callback. |
Asynchronous. Offline. Disable possibility to use biometric authentication. |
No input parameters. |
Success / failure callback. |
``` fun disableBiometricAuthentication() { mobileDcApi .userService .disableBiometricAuthentication({ //Biometric authentication cannot be no longer used. Use enableBiometricAuthentication to enable it again }, { //Something went wrong //Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Method for enabling device level authentication and updating biometric public key with Wallet Pin. To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
walletPin | CharArray | Current walletPin | Not empty |
biometricAuthType | BiometricAuthType (BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE) | Type of biometrics to enable during device pairing process. | Not null |
Success / failure callback. |
``` //KeyguardManager example keyguardManager = context.getSystemService(KEYGUARD_SERVICE) fun isDeviceSecure(): Boolean { return keyguardManager.isKeyguardSecure } //if isDeviceSecure return true device is safe and enableBiometricAuthenticationWithWalletPin method can be performed fun enableBiometricAuthenticationWithWalletPin(walletPin: CharArray, biometricAuthType : BiometricAuthType) { mobileDcApi.userService .enableBiometricAuthenticationWithWalletPin(walletPin, biometricAuthType, { // Biometric authentication is enabled. Read startBiometricAuthentication description to authenticate user. }, { throwable -> // Something went wrong // Check exceptions described in Error handling chapter } ) } ``` |
Asynchronous. Offline. Create CryptoObject for biometric authentication. Depends on usage of androidx/android support library an different CryptoObject can be provided by Android SDK. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cryptoObjectType | CryptoObjectType | Enum that defines different types of CryptoObject BIOMETRIC\_PROMPT\_ANDROIDX - androidx/biometric/BiometricPrompt/CryptoObject, FINGERPRINT\_MANAGER\_COMPAT\_ANDROIDX - androidx/core/hardware/fingerprint/FingerprintManagerCompat/CryptoObject, FINGERPRINT\_MANAGER - android/hardware/fingerprint/FingerprintManager/CryptoObject, BIOMETRIC\_PROMPT - android/hardware/biometrics/BiometricPrompt/CryptoObject | Not empty |
Success callback. |
**Parameter** | **Type** | **Description** |
---|---|---|
result | BiometricAuthenticationData | Object containing CryptoObject kept as Object. |
**Parameter** | **Type** | **Description** |
---|---|---|
cryptoObject | Object | Wrapper class for crypto objects supported biometric authentication. |
Failure callback. |
``` mobileDcApi .userService .startBiometricAuthentication(CryptoObjectType.BIOMETRIC_PROMPT_ANDROIDX) { // Creating Object for biometric authentication is done }, { // Something went wrong maybe: private key is not created or not authenticated // Check exceptions } ``` |
``` fun wrapToBiometricAuthenticationResult(biometricAuthenticationData: BiometricAuthenticationData): BiometricAuthenticationResult { val cryptoObject = biometricAuthenticationData.cryptoObject as CryptoObject //Casting to androidx/support version of CryptoObject return BiometricAuthenticationResult( cryptoObject.signature, cryptoObject.cipher, cryptoObject.mac ) } ``` |
``` customViewForBiometricAuthentication = BiometricPrompt fun startAuthentication(){ mobileDcApi .userService .startBiometricAuthentication(CryptoObjectType.BIOMETRIC_PROMPT_ANDROIDX) { biometricAuthenticationData -> verifyAuthentication(wrapToBiometricAuthenticationResult(biometricAuthenticationData)) }, { // Something went wrong maybe: private key is not created or not authenticated // Check exceptions } } fun verifyAuthentication(biometricAuthenticationResult:BiometricAuthenticationResult){ mobileDcApi .userService .authenticateWithBiometric(biometricAuthenticationResult) { // success authentication is done }, { throwable -> // Something went wrong maybe private key is not authenticated? // Check exceptions } ) } val biometricPrompt: BiometricPrompt = BiometricPrompt(activityFragment, executor, object : BiometricPrompt.AuthenticationCallback() { override fun onAuthenticationError( errorCode: Int, errString: CharSequence ) { super.onAuthenticationError(errorCode, errString) Toast.makeText(context,"Authentication error", Toast.LENGTH_SHORT).show() } override fun onAuthenticationSucceeded( result: BiometricPrompt.AuthenticationResult ) { super.onAuthenticationSucceeded(result) Toast.makeText( context, "Authentication succeeded!", Toast.LENGTH_SHORT).show() startAuthentication() } override fun onAuthenticationFailed() { super.onAuthenticationFailed() Toast.makeText( context, "Authentication failed", Toast.LENGTH_SHORT).show() } }) ``` |
Asynchronous. Offline. Starts system biometric authentication. After invoke system waits for a biometric authentication. |
Method can throw BiometricVerificationException. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
biometricAuthenticationResult | BiometricAuthenticationResult | Class wrapper for biometric authentication result (Signature, Cipher, Mac) created in startBiometricAuthentication | Not empty |
Success callback. |
**Parameter** | **Type** | **Description** |
---|---|---|
result | AuthorizationResult | Object containing verification details. |
Parameter | Type | Description |
---|---|---|
timestamp | Long? | Internal information for SDK. |
signedTimestamp | ByteArray? | Internal information for SDK |
errorMessage | String? | Internal information for SDK |
Failure callback. |
``` fun authenticateWithBiometrics(biometricAuthenticationResult: BiometricAuthenticationResult) { mobileDcApi .userService .authenticateWithBiometric(biometricAuthenticationResult, { authorizationResult -> // authentication with biometric is finished with success, use authorizationResult to loginBySignature }, { throwable -> // Something went wrong, was authentication passed? // Check exceptions }) } ``` |
Asynchronous. Online. Authenticates user in Mobile DC backend after providing trusted identity. Creates / refreshes user session. |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
trustedIdentity | String | Trusted identity generated by client | Not empty |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
userId | String | External user id given by the client | Not empty |
Success / failure callback. |
``` class TrustedIdentity { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .build(); val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ``` |
``` fun loginByTrustedIdentity(mobileDcApi: MobileDcApiKotlin, trustedIdentity: String) { //where trustedIdentity should be generated by server and passed to mobile application mobileDcApi .userService .loginByTrustedIdentity(trustedIdentity, { //user is logged }, { throwable -> // Something went wrong, maybe trustedIdentity is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Authenticates user in Mobile DC backend after providing correct pin. Creates / refreshes user session. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pin | CharArray | Wallet Pin created during user registration process associated with user account. (see: [addUser](https://wiki.upaid.pl/display/UCP/addUser)) | Not empty. |
Success / failure callback. |
``` fun loginByPin(mobileDcApi: MobileDcApiKotlin, pin: CharArray) { //Wallet Pin created during user registration process associated with user account mobileDcApi .userService .loginByPin(pin, { //user is logged }, { throwable -> // Something went wrong, maybe pin is incorrect? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Authenticates user in Mobile DC backend after local biometric authentication (startBiometricAuthentication and authenticateWithBiometric methods). Creates / refreshes user session. |
**AuthorizationResult** provided in success callback from authenticateWithBiometric method. |
Success / failure callback. |
``` fun loginBySignature(authorizationResult: AuthorizationResult) { mobileDcApi .userService .loginBySignature(authorizationResult, { // User is authenticated }, { throwable -> // Something went wrong // Check exceptions }) } ``` |
Asynchronous. Online. Changes user's wallet PIN with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
walletPin | CharArray | Current wallet PIN. | Has 4 or 8 digits. |
newWalletPin | CharArray | New wallet PIN. | Has 4 or 8 digits. |
Success / failure callback. |
``` fun changeWalletPin(walletPin:CharArray, newWalletPin:CharArray) { mobileDcApi .userService .changeWalletPin(walletPin, newWalletPin, { //user's Wallet PIN is changed }, { throwable -> // Something went wrong, maybe current PIN is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Resets wallet pin with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL\] | Not empty |
userLogin | CharArray | User identifier. Depends on user identifier type (EMAIL or PHONE) | Depends on user identifier type. For a phone number it's phone number with country prefix. For pl: 48500500500. For email it's a valid email |
newWalletPin | CharArray | New user wallet pin | Only numbers with 4 to 8 digits |
password | CharArray | Current user password | The password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
Success / failure callback. |
``` fun resetWalletPin(userLogin: CharArray, loginType: UserType, newPin: CharArray, password: CharArray) { mobileDcApi .userService .resetWalletPin(userLogin, loginType, newPin, password, { //user's pin is changed }, { throwable -> // Something went wrong, maybe password is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Changes user's password with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
password | CharArray | Current user password | The password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
newPassword | CharArray | New user password | The password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
Success / failure callback. |
``` fun changePassword(password:CharArray, newPassword:CharArray) { mobileDcApi .userService .changePassword(password, newPassword, { //user's password is changed }, { throwable -> // Something went wrong, maybe current password is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Reset user's password with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] | Not empty |
userLogin | CharArray | User identifier. Depends on user identifier type | Not empty, valid email address or phone with country prefix. For pl: 48500500500 |
Success callback with key and optionally with LimitedResourceInfo. |
**Parameter** | **Type** | **Description** |
---|---|---|
key | CharArray | (Required) Initialization key that will be required for finalize reser user password process |
limitedResourceInfo | LimitedRedourceInfo? | Additional paremeter which shows information about rate of APIs limits. |
Failure callback. |
``` fun initializeResetUserPassword(userLoginType: UserType, userLogin: CharArray) { mobileDcApi .userService .initializeResetUserPassword(userLoginType, userLogin, { response -> val key = response // key is necessary to call the finalizeResetUserPassword method. }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Reset user's password with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
initializeResetUserPassword | InitializeResetUserPassword | An object containing user login type and user login | Not empty |
Parameter | Type | Description |
---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] |
userLogin | CharArray | User identifier. Depends on user identifier type |
Success callback with key. |
Parameter | Type | Description |
---|---|---|
key | CharArray | (Required) Initialization key that will be required for finalize reser user password process |
limitedResourceInfo | LimitedResourceInfo? | Additional paremeter which shows information about rate limited APIs. |
Failure callback. |
``` fun initializeResetUserPassword(initializeResetUserPassword: InitializeResetUserPassword) { mobileDcApi .userService .initializeResetUserPassword(initializeResetUserPassword, { response -> val key = response.key // key is necessary to call the finalizeResetUserPassword method. val limitedResourceInfo = response.limitedResourceInfo // limitedResourceInfo contains information about // rate limited APIs, all parameters are nullable }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Set new user password with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] | Not empty |
userLogin | CharArray | User identifier. Depends on user identifier type | Not empty, valid email address or phone with country prefix. For pl: 48500500500 |
key | CharArray | Key from initialize reset user password method | Not empty |
otp | CharArray | One time password (sent via email during initialize password reset process) | Not empty |
newPassword | CharArray | New user password | The password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
Success / failure callback. |
``` fun finalizeResetUserPassword(userLoginType: UserType, userLogin: CharArray, key: CharArray, otp: CharArray, newPassword: CharArray) { mobileDcApi .userService .finalizeResetUserPassword(userLoginType, userLogin, key, otp, newPassword, { // The OTP has been sent }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Change the user's email address to a new one. After confirming the change of the email, the one-time password ( OTP) will be sent to this address. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
CharArray | New email (an OTP will be sent to that address) | Email format |
Success callback with key. |
**Parameter** | **Type** | **Description** |
---|---|---|
key | CharArray | Initialization key that will be required for finalize reset user password process |
Failure callback. |
``` fun initializeEmailUpdate(email: CharArray) { mobileDcApi .userService .initializeEmailUpdate(email, { response -> val key = response // key is necessary to call the finalizeChangeEmail method. }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Set new user email. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
key | CharArray | Key from initialize change email method | Not empty |
otp | CharArray | One time password (sent via email during initialize change email process) | Not empty |
Success / failure callback. |
``` fun finalizeEmailUpdate(key: CharArray, otp: CharArray) { mobileDcApi .userService .finalizeEmailUpdate( key, otp, { // The user's email has been changed }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Method for resend OTP. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] | Not empty |
userLogin | User identifier. Depends on user identifier type | User identifier. Depends on user identifier type | Not empty, valid email address or phone with country prefix. For pl: 48500500500 |
Success / failure callback. |
``` fun resendOtp(userLoginType: UserType, userLogin: CharArray) { mobileDcApi .userService .resendOtp( userLoginType, userLogin, { // OTP has been sent }, { throwable -> // Something went wrong. // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Offline. Cancels user session. |
No input parameters. |
Success / failure callback. |
``` fun logout() { mobileDcApi .userService .logout({ //User session has been canceled. Refresh user session to restore it. }, { //Something went wrong //Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Delete data of current user and reset SDK state when success. The user can be hard or soft deleted depending on project’s configuration. Hard - method used to delete user with deleting data connected to the user (eg. card). Soft - method used to delete user without deleting data connected to the user (eg. card) Usage of this method causes clearing all data related to selected user. |
No input parameters. |
Success/failure callback. |
``` fun deleteUser() { mobileDcApi .userService .deleteUser({ //user is deleted, all data related to user, device cards etc is cleared. SDK is restarted. }, { throwable -> // Something went wrong // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Adds new payment card with given parameters. |
**Parameter** | **Type** | **Description** |
---|---|---|
addCard | AddCard | Card information data. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardNumber | CharArray | Card number | Field cannot be empty, it must contain only digits, a length of exactly 16 digits and the checksum of the digits must be valid |
expirationDate | CharArray | Card expiration date | Field may not be empty and must have a format MM/YY |
description | CharArray | Card description | Not empty |
cardHolder | CardHolder | Card holder data | Not empty |
isDefault | Boolean? | Is default card for user | - |
currency | CharArray? | Currency of card (ISO 4217, three letter code) | - |
visualId | CharArray? | Visual identifier | - |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
firstName | CharArray | First name of card holder | Not empty |
lastName | CharArray | Last name of card holder | Not empty |
Success callback with cardId. |
**Parameter** | **Type** | **Description** |
---|---|---|
cardId | Long | Id of added card |
``` fun addCard(addCard: AddCard){ mobileDcApi .cardsService .addCard(addCard, { cardId -> // Card added }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Adds new payment card with given parameters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardNumber | CharArray | Card number | Field cannot be empty, it must contain only digits, a length of exactly 16 digits and the checksum of the digits must be valid |
expirationDate | CharArray | Card expiration date | Field may not be empty and must have a format MM/YY |
description | CharArray | Card description | Not empty |
firstName | CharArray | Card holder first name | Not empty |
lastName | CharArray | Card holder last name | Not empty |
Success callback with cardId. |
**Parameter** | **Type** | **Description** |
---|---|---|
cardId | Long | Id of added card |
``` fun addCard(cardNumber:CharArray, expirationDate:CharArray, description:CharArray, firstName:CharArray, lastName:CharArray){ mobileDcApi .cardsService .addCard(cardNumber, expirationDate, description, firstName, lastName, { cardId -> // Card added }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Provides user cards from Mobile DC backend. |
No input parameters. |
Success callback with list of user cards. |
**Parameter** | **Type** | **Description** |
---|---|---|
cards | List <Card> | List of user cards |
**Field** | **Type** | **Description** |
---|---|---|
cardId | Long | Card main identifier. Also used as paymentInstrumentId |
lastFourDigits | String | Last four digits of user card |
expirationDate | String | Card expiration date |
isVerified | Boolean | Flag informing about card verification |
cardHolder | CardHolder? | Card holder details |
visualPath | String? | Path to visual of card |
description | String? | Card description |
cardType | CardType (MASTERCARD, VISA, OTHER, UNKNOWN) | Type of card |
isDefault | Boolean | Indicates if card is default user’s card |
source | String? | From which source card has been added |
currency | String? | Currency code (ISO 4217, three letter code) |
visualId | String? | Visual id |
externalId | String? | Card external id |
isLocked | Boolean | Flag which informs if card is locked |
**Field** | **Type** | **Description** |
---|---|---|
firstName | String | Card holder first name |
lastName | String | Card holder last name |
Failure callback. |
``` fun getCards() { mobileDcApi .cardsService .getAll({ cards -> showCardList(cards) }, { // Something went wrong // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Delete card with given card id. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardId | Long | Id of deleting card | Field cannot be empty. |
Success / failure callback. |
``` fun deleteCard(cardId: Long) { mobileDcApi .cardsService .deleteCard(cardId, { //Success }, { //Something went wrong //Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Card verification- initialize 3D Secure. Provides the data needed for the 3D Secure verification process. |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
cardId | Long | Id of added card | Not empty |
Success callback with Initialize3dsResult. |
**Parameter** | **Type** | **Description** |
---|---|---|
initialize3dsResult | Initialize3dsResult | Contains necessary data for 3DS verification |
**Field** | **Type** | **Description** |
---|---|---|
paymentId | CharArray | Internal transaction id |
pageContent | CharArray | Content of webpage to be shown in browser created in application |
```
fun initialize3ds(mobileDcApi: MobileDcApiKotlin, cardId: Long) {
mobileDcApi
.cardsService
.initialize3ds(cardId, { result ->
val paymentId = result.paymentId
val pageContent = result.pageContent
// Check is pageContent not null
if (pageContent != null) {
// Necessary convert from CharArray to ByteArray
val pageContentToByteArray = pageContent.toByteArray()
openWebView(paymentId, pageContentToByteArray)
} else {
// Card verification error
}
}, { throwable ->
// Something went wrong, maybe cardId is invalid?
// Check exceptions described in Error handling chapter
})
}
fun openWebView(paymentId: CharArray, pageContent: ByteArray) {
//Bind your webView
val myWebView = findViewById |
Asynchronous. Online. Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardId | Long | Id of added card | Not empty |
cvc | CharArray | Card verification code | Field cannot be empty, it must contain only digits, a length of exactly 3 digits |
pares | CharArray | Received after successful interaction with webView | Not empty |
paymentId | CharArray | Received after a valid query to Initialize3ds | Not empty |
Success callback with Finalize3dsResult. |
**Parameter** | **Type** | **Description** |
---|---|---|
finalize3dsResult | Finalize3dsResult | Contains data on the needed to carry out the amount verification and the verification value of the cardholder authentication |
**Field** | **Type** | **Description** |
---|---|---|
amountValidation | Boolean | Inform if random quotation should be used to complete card verification |
cavv | CharArray | Cardholder authentication verification value |
``` fun finalize3ds(mobileDcApi: MobileDcApiKotlin, cardId: Long, cvc: CharArray, pares: CharArray, paymentId: CharArray) { mobileDcApi .cardsService .finalize3ds(cardId, cvc, pares, paymentId, { result -> val amountValidation = result.amountValidation val cavv = result.cavv }, { throwable -> // Something went wrong, maybe any field is invalid? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Card verification - initialize 3D Secure. Provides the data needed for the 3D Secure verification process. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
initialize3DSv2 | Initialize3DSv2 | An object containing data for secure verification process. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditaions** |
---|---|---|---|
cardId | Long | Id of the card | Not empty |
challengeUrl | String | Callback url to handle redirect during Challenge (status CHALLENGE\_REQUIRED from response). Check sample implementation below. | Not empty |
browserDetails | BrowserDetails | Object with properties described below | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
timezoneOffset | String | Timezone offset - numeric | Not empty |
userAgent | String | User Agent | Not empty |
acceptHeader | String | Accept Header | Not empty |
screenWidth | String | Screen Width - numeric | Not empty |
screenHeight | String | Screen Height | Not empty |
language | String | Language - IETF BCP 47 | Not empty |
browserIp | String | Browser IP | Not empty |
screenColorDepth | String | Screen Color Depth - numeric | Not empty |
**Success callback with Initialize3DSv2Result** |
**Parameter** | **Type** | **Description** |
---|---|---|
initialize3DSv2Result | Initialize3DSv2Result | Contains necessary data for 3DS verification |
**Field** | **Type** | **Description** |
---|---|---|
status | String | Status returned of operation. Status could be SUCCESS or CHALLENGE\_REQUIRED. For SUCCESS the Card is already verified and no more action is required. For CHALLENGE\_REQUIRED application should show WebView with content from *challengeHtmlFromBase64.* |
authenticationId | String | Card authentication id, used in finalize3DSv2 method. |
acsUrl | String? | ACS (Access Control Server) url. Required for CHALLENGE\_REQUIRED. |
challengeHtmlFormBase64 | String? | 64BASED html code provided ACQ/ASC. This should be displayed to Application User. Required for CHALLENGE\_REQUIRED. |
``` fun initialize3DSv2(mobileDcApi : MobileDcApiKotlin){ mobileDcApi .cardsService .initialize3DSv2(initialize3DSv2, { initialize3DSv2Result -> when (initialize3DSv2Result.status) { "SUCCESS" -> { //3DS success, no more action is required } "CHALLENGE_REQUIRED" -> { showWebView(initialize3DSv2Result.challengeHtmlFormBase64, challengeUrl) } else -> //failure } }, { throwable -> // Something went wrong // Check exceptions described in Error handling chapter }) } //WebView implementation fun showWebView(challengeHtmlFormBase64: String, challengeUrl : String) { val viewPageContent = String(Base64.decode(challengeHtmlFormBase64, Base64.DEFAULT)) val webViewUrlDetectionClient = WebViewUrlDetectionClient(challengeUrl) with(webView) { webViewClient = webViewUrlDetectionClient settings.javaScriptEnabled = true visibility = View.VISIBLE loadData( viewPageContent, "text/html; charset=UTF-8", "utf-8" ) } } //sample WebViewClient implementation for handing redirect on challangeUrl class WebViewUrlDetectionClient(private val challengeUrl: String): WebViewClient() { override fun onPageStarted(view: WebView, url: String, favicon: Bitmap?) { super.onPageStarted(view, url, favicon) if (url.equals(challengeUrl, true)) { //call finalize3DSv2(cardId, initialize3DSv2Result.authenticationId) } } } ``` |
Asynchronous. Online. Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
finalize3DSv2 | Finalize3DSv2 | An object containing data for secure finalization process. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardId | Long | Id of the card. | Not empty |
authenticationId | String | Identifier of verification process from Initialize3DSv2Result | Not empty |
Success callback/ Failure callback. |
``` fun finalize3DS(mobileDcApi : MobileDcApiKotlin) { val finalize3DSv2Input = Finalize3DSv2(cardId, authenticationId) mobileDcApi .cardsService .finalize3DSv2( finalize3DSv2Input, { //3DS finished with success }, { throwable -> // Something went wrong // Check exceptions described in Error handling chapter } ) } ``` |
Method for updating payment card data. |
**Parameter** | **Type** | **Description** |
---|---|---|
updateCard | UpdateCard | An object containing card data to update |
**Parameter** | **Type** | **Description** |
---|---|---|
cardId | Long | Unique card id |
description | CharArray? | Card description |
currency | CharArray? | Card currency (ISO 4217, three letter code format) |
isDefault | Boolean? | Is this card default |
visualId | CharArray? | Card visual identifier |
firstName | CharArray? | Card holder first name - send only when lastName is not blank |
lastName | CharArray? | Card holder last name - send only when firstName is not blank |
Success callback/ Failure callback. |
``` fun updateCard(cardId: Long, description: CharArray?, isDefault: Boolean?, firstName: CharArray?, lastName: CharArray?){ val updateCard = UpdateCard(cardId).apply { this.description = description this.firstName = firstName this.lastName = lastName this.isDefault = isDefault } mobileDcApi .cardsService .updateCard(updateCard) { // Card updated }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter }) } ``` |
Asynchronous. Online. Card verification - verify card after 3ds. |
**Parameter** | **Type** | **Description** |
---|---|---|
verifyCard | VerifyCard | An object containing card data to verify. |
**Parameter** | **Type** | **Description** |
---|---|---|
cardId | Long | Unique card id |
amount | CharArray? | If finalize3ds returns amountValidation set to false should be null otherwise value is amount freezed on the user account during card verification (value between 100 and 200 pennies). |
Success callback/ Failure callback. |
``` fun verifyCard(cardId: Long, amount: CharArray?, amountValidation: Boolean) { val verifyCard: VerifyCard = VerifyCard(cardId).apply { this.amount = if (amountValidation) amount else null } mobileDcApi .cardsService .verifyCard(verifyCard, { //handle success }, { throwable -> //handle failure }) } ``` |
Asynchronous. Online. Pairs device using given password and user identifier. Deprecated, use pairByPassword(PairByPassword) |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] | Not empty |
userLogin | CharArray | User identifier. Depends on user identifier type | Email or Phone with country prefix |
userPassword | CharArray | User password | Password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
fcmToken | CharArray | Token for push notifications | Not empty |
biometricAuthType | BiometricAuthType? | Optional. One of: \[BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE\]. BIOMETRIC\_ONLY - enable only biometric authentication BIOMETRIC\_WITH\_ALTERNATIVE - enable device level authentication If not set any of above don't be enable. |
Success / failure callback. |
``` fun pairByPassword( email: CharArray, //user email password: CharArray, //user password fcmToken: CharArray // saved FCM token from Firebase service ) { mobileDcApi .deviceService .pairByPassword(UserType.EMAIL, email, password, fcmToken, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter } ) } ``` |
Asynchronous. Online. Pairs device using given password and user identifier. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pairByPassword | PairByPassword | An object containing user information to pair device. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userLoginType | UserType | User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\] | Not empty |
userLogin | CharArray | User identifier. Depends on user identifier type | Email or Phone with country prefix |
userPassword | CharArray | User password | Password should be composed of at least 8 characters and include at least 3 out of the following 4 categories: upper-case letter, lower-case letter, special character and digit |
cloudMessaging RegistrationToken | CloudMessaging RegistrationToken | An object containing cloud messaging registration token information | Not empty |
biometricAuthType | BiometricAuthType? | Optional. One of: \[BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE\]. BIOMETRIC\_ONLY - enable only biometric authentication BIOMETRIC\_WITH\_ALTERNATIVE - enable device level authentication If not set any of above don't be enable. | |
externalDeviceId | String? | External device id |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
type | CloudMessagingType | Mandatory. One of: \[FCM, EXTERNAL\]. FCM - Firebase Cloud Messaging EXTERNAL - External token for external source of RNS | Not empty |
token | String | Token for push notifications | Not empty |
Success / failure callback. |
``` val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken = CloudMessagingRegistrationToken( type: CloudMessagingType, //messaging token type token: String // saved cloud messaging token ) val pairByPassword: PairByPassword = PairByPassword( userLoginType: UserType, //user identifier type userLogin: CharArray, //user identifier password: CharArray, //user password cloudMessagingRegistrationToken: CloudMessagingRegistrationToken, //cloud messaging registration token information biometricAuthType: BiometricAuthType?, //Optional biometric authentication type externalDeviceId: String? //Optional external device id ) fun pairByPassword(pairByPassword: PairByPassword) { mobileDcApi .deviceService .pairByPassword(pairByPassword, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter } ) } ``` |
Asynchronous. Online. Binds device to user in Mobile DC backend with Trusted Identity genetated by client server. Deprecated, use pairByTrustedIdentity(PairByTrustedIdentity). |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
trustedIdentity | String | JSON Web Token containing registration data | Not empty |
fcmRegistrationToken | CharArray | FCM Cloud messaging registration token | Not empty |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
userId | String | External user id given by the client | Not empty |
Success / failure callback. |
``` class TrustedIdentity { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .build(); val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ``` |
``` fun pairDeviceByTrustedIdentity( mobileDcApi: MobileDcApiKotlin, trustedIdentity: String ) { val fcmToken = getFcmRegistartionToken() // get saved FCM token from FirebaseMessagingService, or from //FirebaseInsanceId::getToken() mobileDcApi .deviceService .pairByTrustedIdentity( trustedIdentity, fcmToken, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> //some error occured, check exception }) } ``` |
Asynchronous. Online. Binds device to user in Mobile DC backend with Trusted Identity genetated by client server. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pairByTrustedIdentity | PairByTrustedIdentity | An object containing user information to pair device. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
trustedIdentity | String | JSON Web Token containing registration data | Not empty |
cloudMessagingRegistrationToken | CloudMessagingRegistrationToken | An object containing cloud messaging registration token information | Not empty |
externalDeviceId | String? | External device id |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
userId | String | External user id given by the client | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
type | CloudMessagingType | Mandatory. One of: \[FCM, EXTERNAL\]. FCM - Firebase Cloud Messaging EXTERNAL - External token for external source of RNS | Not empty |
token | String | Token for push notifications | Not empty |
Success / failure callback. |
``` class TrustedIdentity { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .build(); val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ``` |
``` val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken = CloudMessagingRegistrationToken( type: CloudMessagingType, //messaging token type token: String // saved cloud messaging token ) val pairByTrustedIdentity: PairByTrustedIdentity = PairByTrustedIdentity( trustedIdentity: String, //JSON Web Token containing registration data cloudMessagingRegistrationToken: CloudMessagingRegistrationToken, //cloud messaging registration token information externalDeviceId: String? //Optional external device id ) fun pairByTrustedIdentity(pairByTrustedIdentity: PairByTrustedIdentity) { mobileDcApi .deviceService .pairByTrustedIdentity(pairByTrustedIdentity, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter } ) } ``` |
Asynchronous. Online. Binds device to user in Mobile DC backend using username and password. Deprecated, use pairByTrustedIdentity(PairByExternalCredentials). |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
username | String | User identifier | Not empty |
password | CharArray | User password | Not empty |
fcmRegistrationToken | CharArray | FCM Cloud messaging registration token | Not empty |
biometricAuthType | BiometricAuthType? | Optional. One of: \[BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE\]. BIOMETRIC\_ONLY - enable only biometric authentication BIOMETRIC\_WITH\_ALTERNATIVE - enable device level authentication If not set any of above don't be enable. |
Success / failure callback. |
``` fun pairByExternalCredentials() { val username: CharArray = getCharArrayFromInput() //get username provided by user val password: CharArray = getCharArrayFromInput() //get password provided by user val fcmToken = getFcmToken() // get saved FCM token from Firebase service mobileDcApi .deviceService .pairByExternalCredentials( username, password, fcmToken, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> //some error occured, check exception }) } ``` |
Asynchronous. Online. Binds device to user in Mobile DC backend using username and password. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pairByExternalCredentials | PairByExternalCredentials | An object containing user information to pair device. | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
username | String | User identifier | Not empty |
password | CharArray | User password | Not empty |
cloudMessagingRegistrationToken | CloudMessagingRegistrationToken | FCM Cloud messaging registration token | Not empty |
biometricAuthType | BiometricAuthType? | Optional. One of: \[BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE\]. BIOMETRIC\_ONLY - enable only biometric authentication BIOMETRIC\_WITH\_ALTERNATIVE - enable device level authentication If not set any of above don't be enable. | |
externalDeviceId | String? | External device id |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
type | CloudMessagingType | Mandatory. One of: \[FCM, EXTERNAL\]. FCM - Firebase Cloud Messaging EXTERNAL - External token for external source of RNS | Not empty |
token | String | Token for push notifications | Not empty |
Success / failure callback. |
``` val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken = CloudMessagingRegistrationToken( type: CloudMessagingType, //messaging token type token: String //saved cloud messaging token ) val pairByExternalCredentials: PairByExternalCredentials = PairByExternalCredentials( userName: CharrArray, //username provided by user password: CharrArray, //password provided by user cloudMessagingRegistratinoToken: CloudMessagingRegistrationToken, //cloud messaging registration token information biometricAuthType: BiometricAuthType?, //Optional biometric authentication type externalDevice: String? //Optional external device id ) fun pairByExternalCredentials(pairByExternalCredentials: PairByExternalCredentials) { mobileDcApi .deviceService .pairByExternalCredentials(pairByExternalCredentials, { //device is paired, now you can use this device to manage Mobile DC resources }, { throwable -> // Something went wrong, maybe any field is wrong? // Check exceptions described in Error handling chapter } ) } ``` |
Asynchronous. Offline. Method allow to check is Device already paired with MDC Backend. |
No input parameters. |
Success / failure callback. |
``` fun isDevicePaired() { mobileDcApi .deviceService .isDevicePaired() { // return is device paired state }, {throwable -> // some error occurred, check exception } } ``` |
Asynchronous. Online. Removes all data collected by SDK and binding between user and device in Mobile DC backend. Pairing device to user can be made by <<pairBy...>> methods. |
No input parameters. |
Success / failure callback. |
``` fun unPairDevice() { mobileDcApi .deviceService .unPairDevice({ //device is unPaired, SDK cannot be not longer used //application can remove all data in context of sDKDefaultBackoffStrategy //for use SDK again call pairBy.. method }, { throwable -> //some error occured, check exception }) } ``` |
Asynchronous. Offline. Processes data sent by backend (push notification data). Application should check Verestro senderId in RemoteMessage object (RemoteMessage::from method) to verify sender. Method can throw InvalidPushException in case of invalid push content passed to it. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pushData | Map<String, String> | Data received from notification service in *RemoteMessage* object | Not empty |
Success/failure callback. |
Asynchronous. Offline. Checks Verestro Backend service source of push content. Application should check senderId in RemoteMessage object (RemoteMessage::from method) before passing data to this method. Deprecated, no longer required to use. Use simply method process() for push message providing. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
pushData | Map<String, String> | Data received from notification service in *RemoteMessage* object | Not empty |
Success callback with *source* of push. |
**Parameter** | **Type** | **Description** |
---|---|---|
source | String | Source of push content, where push data should be passed. Possible values: UCP |
Failure callback. |
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map |
Asynchronous. Online. Updates FCM Cloud Messaging registation token. Method should be called when application receive new registration token from FCM service. When updated application should still receive push notifications from Verestro Backend. Application should always retry update FCM Registration token if method failed. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cloudMessagingRegistrationToken | CloudMessagingRegistrationToken | An object containing user information to update registration token | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
type | CloudMessagingType | Mandatory. One of: \[FCM, EXTERNAL\]. FCM - Firebase Cloud Messaging EXTERNAL - External token for external source of RNS | Not empty |
token | String | Registration token | Not empty |
Success / failure callback. |
``` //application should listen for FCM token changes in FirebaseMessagingService::onNewToken method val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken = CloudMessagingRegistrationToken( type: CloudMessagingType, //messaging token type token: String //saved cloud messaging token ) fun updateRegistrationToken(cloudMessagingRegistrationToken: CloudMessagingRegistrationToken) { mobileDcApi .deviceService .isDevicePaired({ isPaired -> //token update is required only if device is already paired if (isPaired) { mobileDcApi .cloudMessagingService .updateRegistrationToken(cloudMessagingRegistrationToken, { //token updated }, { //some error, always retry action until success //when internet or server connection is not reachable try again later }) } }, { //some error }) } ``` |
Asynchronous. Online. Updates Cloud Messaging registation token for selected token type (FCM). Method should be called when application receive new registration token from FCM service. When updated application should still receive push notifications from Verestro Backend. Application should always retry update FCM Registration token if method failed. Deprecated, use updateRegistrationToken. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
fcmToken | String | Registration token received from FCM service | Not empty |
Success / failure callback. |
Asynchronous. Online. Provides transaction history from Mobile DC backend with selected transactions filters. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
filters | TransactionsFilters? | Filters for transactions history. Leave null to get all user's transactions with limit equals 10 | |
nextPage | TransactionsNextPage? | Indicates starting point of downloaded transaction history Pass null for first request or pass object from getTransactionHistory result |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
cardId | String? | Selected card id or null | |
paymentTokenId | String? | Selected paymentTokenId or null Field is available in PaymentInstrument object in UCP module | |
ibanId | String? | Selected iban id or null | |
area | String? | Area of transaction, specific per project (e.g. "UCP"). Could be null in order to avoid filtering by area of transaction. | |
timestampFrom | String? | The date/time (in ISO 8601 extended format) indicating the timestamp from which transactions would be filtered (e.g. "2020-10-10T00:59:00.000000+02:00"). Could be null in order to avoid filtering by indicating the earliest date of transactions. | |
timestampTo | String? | The date/time (in ISO 8601 extended format) indicating the timestamp to which transactions would be filtered (e.g. "2020-10-10T00:59:00.000000+02:00"). Could be null in order to avoid filtering by indicating the latest date of transactions. | |
amountMinorMin | Long? | The transaction minimum monetary amount (inclusive) in terms of the minor units of the currency. For example, for EUR 2.35 client should pass 235, and for BHD -1.345 should pass 1345. Absolute value is taken into consideration. | |
amountMinorMax | Long? | The transaction maximum monetary amount (inclusive) in terms of the minor units of the currency. For example, for EUR 2.35 client should pass 235, and for BHD -1.345 should pass 1345. Absolute value is taken into consideration. | |
amountType | AmountType? | Transaction amount type. One of POSITIVE, NEGATIVE | |
contrahent | TransactionContrahent? | Contrahent data. For transaction type TOP\_UP it means the sender of the transfer. For transaction type OUTGOING\_TRANSFER it means the receiver of the transfer | |
description | String? | Description of transaction | |
status | Set<String>? | List of transaction statuses. Possible values: \[DECLINED, CLEARED, AUTHORIZED, REVERSED\]. For example: status=AUTHORIZED&status=CLEARED | |
limit | Int? | Limit of transactions to get. When not changed default value is 10 |
**Parameter** | **Type** | **Description** | **Validation conditions** |
iban | String | Contrahent International Bank Account Number | |
bic | String | Contrahent Bank Identifier Code | |
name | String | Contrahent name |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
seekId | String | Seek id of next transaction | |
seekTimestamp | String | Seek timestamp of next transaction |
Success callback with list of transactions history. |
**Parameter** | **Type** | **Description** |
---|---|---|
transactionHistory | TransactionHistory | An object containing list of TransactionDetails and TransactionNextPage to show transaction history |
**Parameter** | **Type** | **Description** |
---|---|---|
transactions | List<TransactionDetails> | List of transactions history |
nextPage | TransactionsNextPage? | Object for getting next transactions history items |
**Field** | **Type** | **Description** |
---|---|---|
id | Long | Internal transaction id |
clientTransactionId | String | Client id of transaction |
amountMinor | Long | The transaction monetary count in terms of the minor units of the currency |
currency | String | Currency of the transaction amount. 3-digits ISO 4217 currency code |
type | String | Transaction type. One of: PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER |
status | String | Transaction status. One of: DECLINED, CLEARED, AUTHORIZED, REVERSED |
timestamp | String | The date/time when the transaction occurred. In ISO8601 extended format |
description | String? | Description of transaction |
comment | String? | Comment for the transaction |
cardId | Long? | Card id of transaction |
paymentTokenId | String? | Id of payment token |
cardLastFourDigits | String? | Last four digits of card |
merchantName | String? | The merchant name |
merchantPostalCode | String? | The postal code of the merchant |
merchantTransactionId | String? | Identifier given by merchant for transaction |
transactionCountryCode | String? | The country in which the transaction was performed. Expressed as a 3-letter country code as defined in ISO 3166-1 |
comboCardAccountType | String? | Indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: CREDIT, DEBIT |
issuerResponseInformation | String? | Additional information provided by the issuer for declined transaction. One of: INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION |
transactionChannel | String? | Information about transaction channel. One of: CONTACTLESS, CLOUD, MONEYSEND |
ibanId | String? | Id of iban as *sha256Hex* |
mcc | String? | 4 digits merchant category code |
mccCategory | String? | Category of merchant category code |
originalAmountMinor | Long? | The transaction monetary amount in terms of the minor units of the original currency. For example, EUR 2.35 will return 235, and BHD -1.345 will return -1345. Negative amounts indicate a refund or payment |
originalCurrency | String? | 3-character ISO 4217 original currency code of the transaction |
exchangeRate | Double? | Exchange rate of the original currency into the base currency |
balanceMinorValueAfterTransaction | Long? | Account balance value after transaction in terms of the minor units |
commissionMinorValue | Long? | Commission value in terms of the minor units |
clearingTimestamp | String? | The date/time when the transaction changed status on CLEARED. In ISO 8601 extended format |
contrahent | TransactionContrahent? | Contrahent data. For transaction type TOP\_UP it means the sender of the transfer. For transaction type OUTGOING\_TRANSFER it means the receiver of the transfer |
parentId | Long? | Id of base transaction |
attachmentStatus | String? | Attachment status of transaction. One of: \[EMPTY, INCORRECT, TO\_APPROVE, APPROVED\] |
incorrectAttachmentStatusReason | String? | Reason of INCORRECT attachment status. Required only for this status. One of: \[ATTACHMENT\_UNREADABLE, ATTACHMENT\_INCORRECT, OTHER\] |
categoriesInfo | TransactionCategoriesInfo? | Transaction categories |
walletReference | String? | In the case of a transaction with a digitized card, this field contains information from which xPay was initiated. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
iban | String | Contrahent International Bank Account Number | |
bic | String | Contrahent Bank Identifier Code | |
name | String | Contrahent name |
**Parameter** | **Type** | **Description** | **Validation conditions** |
categories | List<TransactionCategory>? | Transaction categories list |
**Parameter** | **Type** | **Description** | **Validation conditions** |
id | Long | Category id | |
amountMinor | Long | Part of the transaction monetary amount which is related to the given category (minor units of the currency) | |
idName | String | Category name | |
name | String | Category name in the language that was sent in the request header |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
seekId | String | Seek id of next transaction | |
seekTimestamp | String | Seek timestamp of next transaction |
``` //sample filters val lastFiveTransactionForCard = TransactionsFilters() lastFiveTransactionForCard.cardId = "1" lastFiveTransactionForCard.limit = 5 //when not set default is 10 //another sample filters val allTransactionsForUser: TransactionsFilters? = null //another sample filters val lastThreeTransactionsForUser = TransactionsFilters() lastThreeTransactionsForUser.limit = 3 //indicates starting point of transaction history //can be used while loading more history or for paging var nextPage: TransactionsNextPage? = null fun getTransactionsHistory(filters: TransactionsFilters?) { mobileDcApi .transactionsHistoryService .getTransactionsHistory(filters, nextPage, { transactionsHistory -> val transactions = transactionsHistory.transactions showTransactions(transactions) //save nextPage for getting next items nextPage = transactionsHistory.nextPage }, { //something went wrong, check exception }) } ``` |
Asynchronous. Online. Provides transaction details from Mobile DC backend for selected transactionId. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
getTransactionDetails | GetTransactionDetails | Contains id for requested transactionId | transactionId greater than 0 and not null |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
transactionId | Long | Selected id of transaction | Greater than 0 and not null |
Success callback with transaction details. |
**Parameter** | **Type** | **Description** |
---|---|---|
getTransactionDetailsResult | GetTransactionDetailsResult | An object containing details for requested transaction |
**Field** | **Type** | **Description** |
---|---|---|
id | Long | Internal transaction id |
clientTransactionId | String | Client id of transaction |
amountMinor | Long | The transaction monetary count in terms of the minor units of the currency |
currency | String | Currency of the transaction amount. 3-digits ISO 4217 currency code |
type | String | Transaction type. One of: PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER |
status | String | Transaction status. One of: DECLINED, CLEARED, AUTHORIZED, REVERSED |
timestamp | String | The date/time when the transaction occurred. In ISO8601 extended format |
description | String? | Description of transaction |
comment | String? | Comment for the transaction |
cardId | Long? | Card id of transaction |
paymentTokenId | String? | Id of payment token |
cardLastFourDigits | String? | Last four digits of card |
merchantName | String? | The merchant name |
merchantPostalCode | String? | The postal code of the merchant |
transactionCountryCode | String? | The country in which the transaction was performed. Expressed as a 3-letter country code as defined in ISO 3166-1 |
comboCardAccountType | String? | Indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: CREDIT, DEBIT |
issuerResponseInformation | String? | Additional information provided by the issuer for declined transaction. One of: INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION |
transactionChannel | String? | Information about transaction channel. One of: CONTACTLESS, CLOUD, MONEYSEND |
ibanId | String? | Id of iban as *sha256Hex* |
mcc | String? | 4 digits merchant category code |
mccCategory | String? | Category of merchant category code |
originalAmountMinor | Long? | The transaction monetary amount in terms of the minor units of the original currency. For example, EUR 2.35 will return 235, and BHD -1.345 will return -1345. Negative amounts indicate a refund or payment |
originalCurrency | String? | 3-character ISO 4217 original currency code of the transaction |
exchangeRate | Double? | Exchange rate of the original currency into the base currency |
balanceMinorValueAfterTransaction | Long? | Account balance value after transaction in terms of the minor units |
commissionMinorValue | Long? | Commission value in terms of the minor units |
clearingTimestamp | String? | The date/time when the transaction changed status on CLEARED. In ISO 8601 extended format |
parentId | Long? | Id of base transaction |
contrahent | TransactionContrahent? | Contrahent data. For transaction type TOP\_UP it means the sender of the transfer. For transaction type OUTGOING\_TRANSFER it means the receiver of the transfer |
attachmentStatus | String? | Attachment status of transaction. One of: \[EMPTY, INCORRECT, TO\_APPROVE, APPROVED\] |
incorrectAttachmentStatusReason | String? | Reason of INCORRECT attachment status. Required only for this status. One of: \[ATTACHMENT\_UNREADABLE, ATTACHMENT\_INCORRECT, OTHER\] |
attachments | List<TransactionDetails Attachment> | Transaction attachments list |
categoriesInfo | TransactionCategoriesInfo? | Transaction categories |
walletReference | String? | In the case of a transaction with a digitized card, this field contains information from which xPay was initiated. |
partialReversals | List<PartialReversal>? | Transaction partial reversals list |
Parameter | Type | Description |
---|---|---|
id | String | Attachment id |
name | String | File name |
mimeType | String | Mime type |
link | String | Url address valid by default 10 minutes. If link expires then API to generate link should be used. Mostly in this case minio will return 403 Forbidden |
linkExpirationDate | String | Url expiration date for given link in ISO 8601 extended format. Given link will be valid only short period of time |
**Parameter** | **Type** | **Description** | **Validation conditions** |
categories | List<TransactionCategory>? | Transaction categories list |
**Parameter** | **Type** | **Description** | **Validation conditions** |
id | Long | Category id | |
amountMinor | Long | Part of the transaction monetary amount which is related to the given category (minor units of the currency) | |
idName | String | Category name | |
name | String | Category name in the language that was sent in the request header |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
amountMinor | Double | The reversal monetary amount in terms of the minor units of the currency. For example, EUR 2.35 will return 235, and BHD -1.345 will return -1345 | |
currency | String | 3-character ISO 4217 currency code of the transaction reversal | |
date | String | The date/time of the transaction reversal. In ISO 8601 extended format | |
balanceMinorValueAfterTransaction | Double | Account balance value after transaction reversal in terms of the minor units |
``` //sample entry data val getTransactionDetails = GetTransactionDetails(1210L) fun getTransactionDetails(getTransactionDetails: GetTransactionDetails) { mobileDcApi .transactionsHistoryService .getTransactionDetails(getTransactionDetails, { getTransactionDetailsResult -> //succes }, { //something went wrong, check exception }) } ``` |
Asynchronous. Online. Stores attachment file in Mobile DC backend for selected transactionId. |
**Parameter** | **Type** | **Description** |
---|---|---|
transactionAttachment | TransactionAttachment | Contains all data required to save attachment |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
transactionId | Long | Selected id of transaction | not null and greater or equal 0 |
attachmentInputStream | InputStream | Stream of file data | not null |
mimeType | String | MIME type of file. For example image/jpeg image/png | Is not empty |
fileName | String? | Name of file. If null or blank then it is generated randomly with unique name. File extension is optional. |
Success callback. |
``` //sample entry data val inputStream = contentResolver.openInputStream(uri) val mimeType = contentResolver.getType(uri) val transactionAttachment = TransactionAttachment( transactionId = 10023L, attachment = inputStream, mimeType = "image/jpeg" ) //transaction attachment with optional file name val transactionAttachment = TransactionAttachment( transactionId = 10023L, attachment = inputStream, mimeType = "image/png" fileName = "picture.png" ) val transactionAttachment = TransactionAttachment( transactionId = 10023L, attachment = inputStream, mimeType = "image/png" fileName = "1636362847509" ) fun storeAttachment(transactionAttachment: TransactionAttachment) { mobileDcApi .transactionsHistoryService .storeAttachment(transactionAttachment, { //succes }, { //something went wrong, check exception }) } ``` |
Asynchronous. Online. Provides new link to load attachment when existing one fails with 403 HTTP status. |
**Parameter** | **Type** | **Description** |
---|---|---|
generateAttachmentLink | GenerateAttachmentLink | Contains transactionId and attachmentId |
Parameter | Type | Description | Validation conditions |
---|---|---|---|
transactionId | Long | Selected id of transaction | not null and greater or equal 0 |
attachmentId | String | Selected attachment ID | is not empty |
Success callback with new attachment link and expiration date. |
**Parameter** | **Type** | **Description** |
---|---|---|
generateAttachmentLinkResult | GenerateAttachmentLinkResult | An object containing new link and link expiry date |
**Field** | **Type** | **Description** |
---|---|---|
link | String | Url address |
linkExpirationDate | String | Url expiration date for given link in ISO 8601 extended format. Given link will be valid only short period of time |
```
//sample entry data
val generateAttachmentLink = GenerateAttachmentLink(1210L, "2145")
fun generateAttachmentLink(generateAttachmentLink: GenerateAttachmentLink) {
mobileDcApi
.transactionsHistoryService
.generateAttachmentLink(generateAttachmentLink, { generateAttachmentLinkResult ->
//succes
}, {
//something went wrong, check exception
})
}
//sample usage when loading link from getTransactionDetails returns 403 HTTP status
fun getTransactionDetails() {
mobileDcApi
.transactionHistoryService
.getTransactionDetails(GetTransactionDetails(transactionId), { getTransactionDetailsResult ->
loadAttachmentsImages(getTransactionDetailsResult)
}, {
//something went wrong, check exception
}
)
}
private fun loadAttachmentsImages(getTransactionDetailsResult: GetTransactionDetailsResult) {
val attachments: List |
Asynchronous. Online. Delete attachment associated with provided transaction. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
deleteAttachment | DeleteAttachment | Plain object of DeleteAttachment | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
transactionId | Long | Identifier of selected transaction. Id can be taken from GetTransactionDetailsResult object, check [getTransactionDetails](https://wiki.verestro.com/display/UCP/getTransactionDetails) method | Not empty |
attachmentId | String | Identifier of selected attachment. Id can be taken from TransactionDetailsAttachment, check [getTransactionDetails](https://wiki.verestro.com/display/UCP/getTransactionDetails) method | Not empty |
Success callback/ Failure callback. |
``` val transactionDetailsResult: GetTransactionDetailsResult = GetTransactionDetails(1L) val deleteAttachment: DeleteAttachment = DeleteAttachment(transactionDetailsResult.id, transactionDetailsResult.transactionDetailsAttachment.id) private fun deleteAttachment(deleteAttachment) { mobileDcApi.transactionService .deleteAttachment(deleteAttachment, { //Deletion of attachment went succesfully }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Online. Updates single transaction data in Mobile DC backend by transactionId. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
updateSingleTransactionData | UpdateSingleTransactionData | Transaction data to be updated | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
transactionId | Long | Transaction ID | Not empty |
description | String? | Description of transaction | |
comment | String | Comment for the transaction |
Success callback/ Failure callback. |
Asynchronous. Online. Updates category of the transaction. It is possible to set more than one category (sum of the amounts in categories has to be matched to the transaction amount). |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
updateTransactionCategory | UpdateTransactionCategory | Category data to be updated in the transaction | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
transactionId | Long | Transaction ID | Not empty |
categoriesInfo | List<TransactionCategoryUpdateInfo> | List of new transaction categories | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
id | Long | Category id | Not empty |
amountMinor | Double? | Part of the transaction monetary amount which is related to the given category (minor units of the currency). Required if there is set more than one new category. Sum of all amounts in the list has to be matched to the transaction amount |
Success callback/ Failure callback. |
Asynchronous. Online. Method returns user categories. |
No input parameters. |
Success callback with user categories details. |
**Parameter** | **Type** | **Description** |
---|---|---|
categories | List<TransactionUserCategory> | User categories. |
**Field** | **Type** | **Description** |
---|---|---|
id | String | Category identifier |
idName | String | Category name in english |
name | String | Category name in the language that was sent in the request header |
type | String | Category type, one of: \[SYSTEM, USER\] |
childrenCategories | List<TransactionUserCategory>? | Children categories |
Asynchronous. Online. Method returns monthly spending amount in target currency which has to be given balance currency. For scenario where someone was added manually transaction in different currency than balance or target currency is different, then this method will return error |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
getMonthlySpending | GetMonthlySpending | Plain object of GetMonthlySpending | Not empty |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
balanceId | String | Account identifier which can be related to multiple cards | Not empty |
targetCurrency | String | Target currency of spending amount represented by 3-character ISO 4217 currency code. | Not empty |
date | String? | The month-year from which transactions will be included in statistics. If the parameter is not sent, it will be set to the current month by default. Format: yyyy-MM. |
Success callback with user monthly spending amount. |
**Parameter** | **Type** | **Description** | **Validation conditions** |
---|---|---|---|
amountMinor | Long | Calculated spending amount in minor units | Not empty |
currency | String | 3-character ISO 4217 currency code of spending amount | Not empty |