# User Lifecycle & Card Management API & SDK

This section explains how to register & manage user in Verestro Platform. Two technical documentations cover:

- Server-to-server API
- MDC SDK - SDK for Android & iOS which allows users to manage their accounts by themselves inside mobile app.

# Introduction

The main purpose of Verestro Lifecycle API & SDK web service is to add and manage user and payment cards in a safe way. All data are transfered to Verestro Data Core system which is placed in PCI compliant zone and is fully secure. By registering in the database, the partner can use various services provided by the Verestro i.e. Card Issuing, Card tokenization, Money Transfers and more.

The API allows to mass import of data files to Verestro systems, such as: user, user with a card, or cards. Using the HTTPS REST protocol, Partner can add a new resource (user or cards), update their status, e.g. lock, unlock or completely remove a resource from system.

Once connected to the partner's application, the SDK enables full user management and securing the connection to all Verestro products. Our SDK was develop for iOS and Android platforms.

The Mobile DC SDK is a core module dedicated to the management of users, devices, and cards in the Verestro system. Usage of other Verestro modules (f.e. UCP - Verestro Claud Payment) always depends on this SDK and Mobile DC must be always used.

Main responsibilities Lifecycle API:

<div class="confluence-information-macro-body" id="bkmrk-user---end-user-mana"><div class="confluence-information-macro-body">- user - end user management in system,
- cards - card management in system,
- addresses - module related to user resource.

</div></div>Main responsibilities Lifecycle SDK:

- user - end user registration, password and pin management,
- cards - card management,
- addresses - addresses management,
- device - device and session token management.

<div class="confluence-information-macro-body" id="bkmrk-"></div>

# Overview

Lifecycle API The main purpose of a web service is to add a user and payment cards in a safe way to dedicated database PCI DSS compliant systems, which are provided by Verestro. By registering in the database, the partner can use various services provided by the Verestro company, e.g. Card Issuing, Card tokenization, Money Transfers and more. The API allows to mass import of data files to Verestro systems, such as: user, user with a card, or cards. Using the HTTPS REST protocol, you can add a new resource (user or cards), update their status, e.g. lock, unlock or completely remove a resource from system.

LIfecycle API is an internal service secured by x509 certificate, which increases the safety of transported data. The API communicates with the data storehouse called DataCore. DataCore is internal service and one of crucial components of Verestro's product line-up. Its main responsibility is to provide secure, PCI-DSS compliant storage for cardholder data. DataCore manages the status of the user and their aggregates. All other product in implementation connect to DataCore which returns information about the user and his aggregates.

## Security

### Data Storage

Lifecycle API is a part of PCI zone of Verestro platform so it meets all standards and restrictions of secure data storage. All fragile data is secured and encrypted.

We are using <span class="g-type-body-small">HashiCorp Vault as a Software HSM.</span>

The master key isn't stored anywhere. It is reconstructed in unsealing process. It is used to encrypt encryption key. The data stored by Vault is stored encrypted. Therefore, to decrypt the data, Vault must decrypt the encryption key which requires the master key. Unsealing is the process of reconstructing this master key.

Instead of distributing this master key as a single key to an operator, Vault uses an algorithm known as [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the key into key shards. A certain threshold of shards is required to reconstruct the master key.

[More information](https://www.vaultproject.io/docs/concepts/seal.html)

When the Vault is initialized it generates an encryption key which is used to protect all the data. The encryption key is also stored with the data, but encrypted with another encryption key known as the *master key*. Once Vault retrieves the encryption key, it is able to decrypt the data in the storage backend, and enters the *unsealed state.* Vault uses 256-bit AES to encrypt Encryption Key.

All sensitive data is encrypted in this way.

### Encryption of fragile data

LC api allows to encrypt fragile card data. Detailed description is provided below.

### JWE Standard

To encrypt fragile card data you should use JWE. If you are unfamiliar with this kind of standard please look at links below:  
[Wiki](https://en.wikipedia.org/wiki/JSON_Web_Encryption "Wiki"),  
[RFC](https://tools.ietf.org/html/rfc7516),  
[Example](https://web-token.spomky-labs.com/).

The setup for Lifecycle JWE is presented below:

- in headers: 
    - alg: RSA-OAEP-256 - keyEncryptionAlgo,
    - enc: A128GCM/A256GCM - contentEncryptionAlgo,
    - zip: DEF,
    - iat: this field should contain current timestamp,
    - kid: SHA1 of thumbprint of public key used to generate JWE (Static values is: Pdk08OtjTS6-I7H\_E96XKme0BOY),
- in body: plaintext json data. Please see example below.

Public key used to generate JWE can be download from method [GET /lifecycle/v1/public-key](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation)

### JWE Examples

During development you can use test methods that allows to generate and check your implementation of JWE:

PAYLOAD - json string used to generate JWE, for example:

<div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-name="info" id="bkmrk-%7B%22pan%22%3A%22555544443333"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-name="info"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="confluence-information-macro-body"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}"><div bis_size="{"x":150,"y":1528,"w":840,"h":30,"abs_x":500,"abs_y":1741}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk-%7B%22pan%22%3A%22555544443333-0"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div bis_size="{"x":158,"y":1535,"w":465,"h":16,"abs_x":508,"abs_y":1748}" class="container" title="Hint: double-click to select code"><div bis_size="{"x":174,"y":1535,"w":433,"h":16,"abs_x":524,"abs_y":1748}" class="line number1 index0 alt2">`{``"pan"``:``"5555444433331234"``,``"expiryDate"``:``"2040-11-30"``}`</div></div></td></tr></tbody></table>

</div></div></div></div></div></div></div>ISSUER - string provided by DC Team during integration  
EXAMPLE\_JWE - JWE to be validated and decoded

<div bis_size="{"x":150,"y":1641,"w":840,"h":142,"abs_x":500,"abs_y":1854}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-generate-jwe-curl---"><div bis_size="{"x":150,"y":1641,"w":840,"h":22,"abs_x":500,"abs_y":1854}" class="codeHeader panelHeader pdl">**Generate JWE**</div><div bis_size="{"x":150,"y":1668,"w":840,"h":116,"abs_x":500,"abs_y":1881}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":1668,"w":840,"h":116,"abs_x":500,"abs_y":1881}"><div bis_size="{"x":150,"y":1668,"w":840,"h":116,"abs_x":500,"abs_y":1881}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk-curl---location---re"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div bis_size="{"x":158,"y":1675,"w":721,"h":102,"abs_x":508,"abs_y":1888}" class="container" title="Hint: double-click to select code"><div bis_size="{"x":174,"y":1675,"w":689,"h":18,"abs_x":524,"abs_y":1888}" class="line number1 index0 alt2">`curl --location --request GET ``'<a href="https://datacore.upaidtest.pl/test/generate-jwe-token/PAYLOAD'">https://datacore.upaidtest.pl/test/generate-jwe-token/PAYLOAD'</a>` `\`</div><div bis_size="{"x":174,"y":1694,"w":689,"h":16,"abs_x":524,"abs_y":1907}" class="line number2 index1 alt1">`--header ``'Content-Type: application/json'` `\`</div><div bis_size="{"x":174,"y":1710,"w":689,"h":16,"abs_x":524,"abs_y":1923}" class="line number3 index2 alt2">`--header ``'Accept: application/json'` `\`</div><div bis_size="{"x":174,"y":1727,"w":689,"h":16,"abs_x":524,"abs_y":1940}" class="line number4 index3 alt1">`--header ``'Authorization: Basic dGVzdDE6dGVzdDEyMw=='` `\`</div><div bis_size="{"x":174,"y":1744,"w":689,"h":16,"abs_x":524,"abs_y":1957}" class="line number5 index4 alt2">`--header ``'ISSUER-CODE: ISSUER'` `\`</div><div bis_size="{"x":174,"y":1761,"w":689,"h":16,"abs_x":524,"abs_y":1974}" class="line number6 index5 alt1">`--header ``'COLLECTION: internal'`</div></div></td></tr></tbody></table>

</div></div></div></div>**Read JWE**

<div bis_size="{"x":150,"y":1845,"w":840,"h":166,"abs_x":500,"abs_y":2058}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-read-jwe-curl---loca"><div bis_size="{"x":150,"y":1845,"w":840,"h":166,"abs_x":500,"abs_y":2058}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":1845,"w":840,"h":166,"abs_x":500,"abs_y":2058}"><div bis_size="{"x":150,"y":1845,"w":840,"h":166,"abs_x":500,"abs_y":2058}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk-curl---location---re-0"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div bis_size="{"x":158,"y":1852,"w":643,"h":153,"abs_x":508,"abs_y":2065}" class="container" title="Hint: double-click to select code"><div bis_size="{"x":174,"y":1852,"w":611,"h":18,"abs_x":524,"abs_y":2065}" class="line number1 index0 alt2">`curl --location --request POST ``'<a href="https://datacore.upaidtest.pl/test/read-jwe-token'">https://datacore.upaidtest.pl/test/read-jwe-token'</a>` `\`</div><div bis_size="{"x":174,"y":1871,"w":611,"h":16,"abs_x":524,"abs_y":2084}" class="line number2 index1 alt1">`--header ``'Content-Type: application/json'` `\`</div><div bis_size="{"x":174,"y":1887,"w":611,"h":16,"abs_x":524,"abs_y":2100}" class="line number3 index2 alt2">`--header ``'Accept: application/json'` `\`</div><div bis_size="{"x":174,"y":1904,"w":611,"h":16,"abs_x":524,"abs_y":2117}" class="line number4 index3 alt1">`--header ``'Authorization: Basic dGVzdDE6dGVzdDEyMw=='` `\`</div><div bis_size="{"x":174,"y":1921,"w":611,"h":16,"abs_x":524,"abs_y":2134}" class="line number5 index4 alt2">`--header ``'ISSUER-CODE: ISSUER'` `\`</div><div bis_size="{"x":174,"y":1938,"w":611,"h":16,"abs_x":524,"abs_y":2151}" class="line number6 index5 alt1">`--header ``'COLLECTION: internal'` `\`</div><div bis_size="{"x":174,"y":1954,"w":611,"h":16,"abs_x":524,"abs_y":2167}" class="line number7 index6 alt2">`--data-raw '{`</div><div bis_size="{"x":174,"y":1971,"w":611,"h":16,"abs_x":524,"abs_y":2184}" class="line number8 index7 alt1">`    ``"token"` `: ``"EXAMPLE_JWE"`</div><div bis_size="{"x":174,"y":1988,"w":611,"h":16,"abs_x":524,"abs_y":2201}" class="line number9 index8 alt2">`}'`</div></div></td></tr></tbody></table>

</div></div></div></div>**Hash HMAC**

Lifecycle also provides configuration called idType. It is simple tool that can be used if you can't store LC internal id's.  
There are two main id types: useridType and cardIdType. All possible options for both are presented in LC API specification.  
Here we are describing case when cardIdType is set to hash.  
Hash value is as SHA-256 HMAC, please see links below for more details:   
[RFC](https://tools.ietf.org/html/rfc4868#page-3),  
[Wiki](https://en.wikipedia.org/wiki/HMAC),  
[Java example](https://gist.github.com/MaximeFrancoeur/bcb7fc2db08c704f322a).

Test value of key used to calculate HMAC in HEX

59c6d62dde38d8a2c32105a53336b8ef

To validate your implementation please check plain and hashed values below:

<div bis_size="{"x":150,"y":2373,"w":840,"h":63,"abs_x":500,"abs_y":2586}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-%225555444433332222%22%C2%A0%C2%A0"><div bis_size="{"x":150,"y":2373,"w":840,"h":63,"abs_x":500,"abs_y":2586}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":2373,"w":840,"h":63,"abs_x":500,"abs_y":2586}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk-%225555444433332222%22%C2%A0%C2%A0-0"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div bis_size="{"x":158,"y":2380,"w":727,"h":50,"abs_x":508,"abs_y":2593}" class="container" title="Hint: double-click to select code"><div bis_size="{"x":174,"y":2380,"w":695,"h":16,"abs_x":524,"abs_y":2593}" class="line number1 index0 alt2">`"5555444433332222"` `"4f64c445c859f7e53209e0091a5faef7e8b3ebbad899fbf8c74df09a6bfe5646"`</div><div bis_size="{"x":174,"y":2397,"w":695,"h":16,"abs_x":524,"abs_y":2610}" class="line number2 index1 alt1">`"6984576897634895763948576"` `"4b2eab65ab16183fa6ac8a8b12ad690890db98c5ce20e6d56aa037b723bbe842"`</div><div bis_size="{"x":174,"y":2414,"w":695,"h":16,"abs_x":524,"abs_y":2627}" class="line number3 index2 alt2">`"someTestValue398048096859607"` `"9596a78a7382e90159d8ec78a8d37baff57d05f676c0607dd7fb24b0396270ce"`</div></div></td></tr></tbody></table>

</div></div></div><div bis_size="{"x":150,"y":2456,"w":840,"h":0,"abs_x":500,"abs_y":2669}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk--4"></div><div bis_size="{"x":150,"y":2456,"w":840,"h":0,"abs_x":500,"abs_y":2669}" class="syntaxhighlighter sh-confluence nogutter  java" id="bkmrk--5"></div>
### Trusted Identity use-case with MDC SDK

In the integrated model, Trusted Identity is used to proof User authenticity. User is firstly authenticated on the Customer side. Trusted Identity should be generated on Issuer backend side and pass via Wallet SDK, since mobile environment is treated as unsecure. Algorithm of generating Trusted Identity is placed in Wallet SDK API specification.

Access to User data stored on Wallet Server is possible only when session is established. After paring device session is automatically generated for particular User.

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #1C1E3F  
skinparam noteBorderColor #1C1E3F  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #1C1E3F  
ArrowFontColor #1C1E3F  
ActorBorderColor #1C1E3F  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #1C1E3F  
ParticipantBackgroundColor #1C1E3F  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #1C1E3F  
LifeLineBorderColor #1C1E3F  
}  
actor User  
User -&gt; MPA: Login by trusted identity  
activate "MPA"  
MPA -&gt; "Mobile DC": loginByTrustedIdentity(trustedIdentity: String)  
activate "Mobile DC"  
break If data is incorrect  
"Mobile DC" --&gt;&gt; "MPA": Login by trusted identity failure with MdcValidationExceptionError  
end  
group Build login request  
"Mobile DC" -&gt; "Mobile DC": Set userId from prefs  
note left  
userId is save after successful pairing  
end note  
break If userId not exist  
"Mobile DC" -&gt; "MPA": Login by trusted identity failure with CoreSdkException  
end  
"Mobile DC" -&gt; "Mobile DC": Set deviceInstallationId from prefs  
note left  
deviceInstallationId is save after successful pairing  
end note  
break If deviceInstallationId not exist  
"Mobile DC" -&gt; "MPA": Login by trusted identity failure with CoreSdkException  
end  
"Mobile DC" -&gt; "Mobile DC": Set trustedIdentity  
end  
"Mobile DC" -&gt; "Mobile DC Service": getMdcsCertificate()  
activate "Mobile DC Service"  
break If getMdcsCertificate is failure  
"Mobile DC Service" --&gt;&gt; "Mobile DC": failure  
"Mobile DC" --&gt;&gt; "MPA": Login by trusted identity failure with BackendException  
end  
"Mobile DC Service" --&gt;&gt; "Mobile DC": GetMdcsServerCertificateResponse(pemPublicKeyCert)  
deactivate "Mobile DC Service"  
"Mobile DC" -&gt; "Mobile DC": Save mdcsCertificate  
"Mobile DC" -&gt; "Mobile DC Service": loginByTrustedIdentity(UserLoginRequestEncrypted)  
activate "Mobile DC Service"  
break Pair request is failure  
"Mobile DC Service" --&gt;&gt; "Mobile DC": failure  
"Mobile DC" --&gt;&gt; "MPA": Login by trusted identity failure with BackendException  
end  
"Mobile DC Service" --&gt;&gt; "Mobile DC": UserLoginResponse(token)  
deactivate "Mobile DC Service"  
"Mobile DC" -&gt; "Mobile DC": Save token as userAuthToken  
"Mobile DC" -&gt; "Mobile DC": Clear sensitive data  
"Mobile DC" -&gt; "MPA": Login by trusted identity complete  
deactivate "Mobile DC"  
"MPA" -&gt; "User": Show login by trusted identity result  
deactivate "MPA"  
@enduml

<span style="color: rgb(28, 30, 63); font-family: -apple-system, 'system-ui', 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 2.8275em; font-weight: 400;">Lifecycle Import</span>

### Info

Lifecycle file import is a mechanism that allows you to create a file with multiple instructions for api. Each instruction is like an request. Instead of sending 10.000 requests to API, which may take ages, you can create single file with all those instructions and let our system handle it asynchronously. Once import is completed an report is generated which will contain errors and information about processed rows. Files with instructions should be uploaded onto SFTP. To get access details, a new integration needs to be set up for bank.

### Requirements

File storage with directories:

/**input** for input files  
/**output** for output files (reports)  
/**processed** for files that were processed

### Input

Input files should be uploaded onto storage into 'input' directory. Everyday at 12:07 am a cron job will run and process those files.

### File example

File format is json line (jsonl). In short this is a file that contains valid json in every line (separated by line break, not a comma etc.).

Each line is a single instruction for our import mechanism. Example file below:

```
{"method":"addUser","data":{"externalId":"48111111111","firstName":"First","lastName":"User","phone":"48111111111","email":"you@post.com","birthDate":"1979-10-06","wPIN":"1234","state":"VERIFIED"}}
{"method":"addUser","data":{"externalId":"48222222222","firstName":"Second","lastName":"User","phone":"48222222222","email":"me@post.com","birthDate":"1979-10-06","wPIN":"1234","state":"VERIFIED"}}
{"method":"addUser","data":{"externalId":"48333333333","firstName":"Third","lastName":"User","phone":"48333333333","email":"validemail@post.com","birthDate":"1979-10-06","wPIN":"1234","state":"VERIFIED"}}
```

<div bis_size="{"x":150,"y":5081,"w":840,"h":0,"abs_x":500,"abs_y":5294}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk--6"><div bis_size="{"x":150,"y":5081,"w":840,"h":0,"abs_x":500,"abs_y":5294}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":5081,"w":840,"h":0,"abs_x":500,"abs_y":5294}"><div bis_size="{"x":150,"y":5081,"w":840,"h":0,"abs_x":500,"abs_y":5294}" class="syntaxhighlighter sh-midnight nogutter  js" id="bkmrk--11"></div></div></div></div>### Line explaination

Each line is a JSON with two keys:

**method** - name of method you're calling (supported methods below),  
**data** - request body.

For example result of importing first line of example file is similar to making a request to **/lifecycle/v1/users** with body:

```
{"externalId":"48111111111","firstName":"First","lastName":"User","phone":"48111111111","email":"you@post.com","birthDate":"1979-10-06","wPIN":"1234","state":"VERIFIED"}
```

### Processing

Processing is handled asynchronously. It means that once file is read, every line will be changed into a "job" and then processed by our "workers". After reading whole file it is moved to **processed** directory. PS. This does not mean that the import is completed.

If workers encounter any troubles during handling their job an error message will be inserted into report file. Structure of error line is "**X, ERROR\_MESSAGE**" where ***X*** is the line number from import file and **ERROR\_MESSAGE** is just the error message. Examples presented in Output section.

### Output

Once import is completed an line with rows processed information is inserted into the report file. You can find report files inside **output** directory. Report file name is $input\_file\_name\_without\_extension-report.csv. Example input/output file with names below.

Example input file

<div bis_size="{"x":150,"y":5754,"w":840,"h":22,"abs_x":500,"abs_y":5967}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-input_file.jsonl"><div bis_size="{"x":150,"y":5754,"w":840,"h":22,"abs_x":500,"abs_y":5967}" class="codeHeader panelHeader pdl">**input\_file.jsonl**</div><div bis_size="{"x":150,"y":5776,"w":840,"h":0,"abs_x":500,"abs_y":5989}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":5776,"w":840,"h":0,"abs_x":500,"abs_y":5989}"><div bis_size="{"x":150,"y":5776,"w":840,"h":0,"abs_x":500,"abs_y":5989}" class="syntaxhighlighter sh-midnight  js" id="bkmrk--12"></div></div></div></div>```
{invalid json :((}
{"method":"addUser","data":{"externalId":"48222222222","firstName":"Second","lastName":"User","phone":"48222222222","email":"me@post.com","birthDate":"1979-10-06","wPIN":"1234","state":"VERIFIED"}}
{"method":"addUser","data":{"externalId":"48333333333","firstName":"Third","lastName":"User","phone":"48333333333","email":"validemail@post.com","birthDate":"1337","wPIN":"1234","state":"VERIFIED"}}
{"method":"thisWillNotWork","data":{"externalId":"4833"}}
```

Example output file

<div bis_size="{"x":150,"y":5928,"w":840,"h":22,"abs_x":500,"abs_y":6141}" class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-input_file-report.cs"><div bis_size="{"x":150,"y":5928,"w":840,"h":22,"abs_x":500,"abs_y":6141}" class="codeHeader panelHeader pdl">**input\_file-report.csv**</div><div bis_size="{"x":150,"y":5950,"w":840,"h":0,"abs_x":500,"abs_y":6163}" class="codeContent panelContent pdl"><div bis_size="{"x":150,"y":5950,"w":840,"h":0,"abs_x":500,"abs_y":6163}"><div bis_size="{"x":150,"y":5950,"w":840,"h":0,"abs_x":500,"abs_y":6163}" class="syntaxhighlighter sh-midnight nogutter  java" id="bkmrk--13"></div></div></div></div>```
1,INVALID_JSON
3,{"errors":{"phone":["VALUE_HAS_TO_BE_UNIQUE"],"birthDate":["DATE_IS_INVALID","DATE_FORMAT_IS_INVALID"]}}
4,INVALID_METHOD
 
Total rows processed: 4
```

Typical error messages:

**INVALID\_JSON** - there was an error while trying to decode line (first line of example input file).  
**INVALID\_METHOD -** invalid/unsupported method (fourth line of example input file).  
**UNKNOWN\_ERROR** - unhandled error (contact DC team for more info).

As you may have noticed there is also an error message encoded in json format. This is the same response that you would receive in a normal api call.

PS. Successfully processed line doesn't produce any output in report file (that's why there is no status for 2nd line).

# Technical documentation

 @swagger="https://s3.verestro.dev/datacore-private/api-docs-lifecycle.json?AWSAccessKeyId=datacore-private&amp;Signature=asBA%2BPUr%2BoBBC%2BQtd7F2rrX%2BpIc%3D&amp;Expires=5355073646"

# Technical documentation MDC SDK

### Basic abbreviations and definitions

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-description-fc" style="height: 346px; width: 70.1235%;"><tbody><tr style="height: 29.8px;"><th class="confluenceTh mceSelected" style="width: 26.9841%; height: 29.8px;">**Field**</th><th class="confluenceTh mceSelected" style="width: 73.0159%; height: 29.8px;">**Description**</th></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" style="width: 26.9841%; height: 29.8px;">FCM</td><td class="confluenceTd mceSelected" style="width: 73.0159%; height: 29.8px;">Firebase Cloud Messaging

</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">DC</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Data Core</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">MDC</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Mobile <span class="inline-comment-marker" data-ref="41e1cb0e-23bd-4434-b47c-5305160244e6">DC</span> module

</td></tr><tr style="height: 77.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 77.8px;">MPA</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 77.8px;">Mobile Payment Application

</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">UCP</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Verestro Cloud Payments</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">IBAN</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Back Account Number</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">JWT</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Json Web Token</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">JWE</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">Json Web Encryption</td></tr><tr style="height: 29.8px;"><td class="confluenceTd mceSelected" colspan="1" style="width: 26.9841%; height: 29.8px;">OTP</td><td class="confluenceTd mceSelected" colspan="1" style="width: 73.0159%; height: 29.8px;">One-time password</td></tr></tbody></table>

### What is Mobile DC SDK?

The Mobile DC SDK is a core module dedicated to the management of users, devices, and cards in the Verestro system.

Usage of other Verestro modules (f.e. UCP - Verestro Claud Payment) always depends on this SDK and Mobile DC must be always used.

### Versioning and backward compatibility

SDK version contains three numbers. For example: 1.0.0.

- <span class="inline-comment-marker" data-ref="46f6c1d4-dfa6-4eef-9534-5d67a64f05e4">First version digit tracks compatibility-breaking changes in SDK public APIs. It is mandatory to update the application code and to use SDK when this is incremented.</span>
- Second version digit tracks new, not compatibility-breaking changes in the public API of SDK. It is optional to update the application code when this digit is incremented.
- The third version digit tracks internal changes in SDK. No updates in the application code are necessary to update to the version, which has this number incremented.

Changes not breaking compatibility:

- Adding a new optional interface to SDK setup.
- Adding a new method to any domain.
- Adding new ENUM value to input or output.<span class="inline-comment-marker" data-ref="72e32c34-1e2c-42be-bfae-d5ee3d3181e9">  
    </span>
- <span class="inline-comment-marker" data-ref="72e32c34-1e2c-42be-bfae-d5ee3d3181e9">Adding a new field in the input or output model.</span>

## <span class="inline-comment-marker" data-ref="72e32c34-1e2c-42be-bfae-d5ee3d3181e9">Technical overview</span>

<span class="inline-comment-marker" data-ref="72e32c34-1e2c-42be-bfae-d5ee3d3181e9">This section describes basic information about Mobile DC SDK, SDK setup, and available methods.</span>

### <span class="inline-comment-marker" data-ref="72e32c34-1e2c-42be-bfae-d5ee3d3181e9">Basic configuration</span>

**Artifactory**

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

**The username and password are provided by Verestro.**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="4d87e775-bd2f-4fa9-a47a-a4d754e863ce" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-repositories%7B-maven-"><tbody><tr><td class="wysiwyg-macro-body">```
repositories{
	maven {
		credentials {
			username "<enter_username_here>"
			password "<enter_password_here>"
		}
	url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
}
```

</td></tr></tbody></table>

**Versions**

<span class="inline-comment-marker" data-ref="2f78929c-873f-45c6-8a92-0c5a8e815328">Mobile DC SDK is available in two versions: debug and release</span>.

The difference between versions is debugged version allows to use of an application with a debugger connected.

Debug version is ended with appendix "-debug" in version name. Samples below:

<span class="inline-comment-marker" data-ref="3b381b18-7363-4c81-8740-e75f51f1e219">For release version, used on production environment in application uploaded to Google Play:</span>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="08424b55-6596-4ffc-8619-f4611df66259" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-dependencies%7B-implem"><tbody><tr><td class="wysiwyg-macro-body">```
dependencies{
	implementation 'pl.upaid.module:mobiledc:{version}'
} 
```

</td></tr></tbody></table>

<span class="inline-comment-marker" data-ref="c491e291-f133-4f1f-b644-c593573b36e9">Debug version - could be used for application development:</span>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="5a1ab960-8df9-47db-a46b-a7f7166c6101" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-dependencies%7B-implem-0"><tbody><tr><td class="wysiwyg-macro-body">```
dependencies{
	implementation 'pl.upaid.module:mobiledc:{version}-debug'
}
```

</td></tr></tbody></table>

**Min SDK Version**

The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="8772f259-4b73-431d-a965-a0dc5cc3b0eb" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%3Cuses-sdk-tools%3Aover"><tbody><tr><td class="wysiwyg-macro-body">```
  <uses-sdk tools:overrideLibrary= "pl.upaid.module.ucp, 
    pl.upaid.module.mobiledc, pl.upaid.internal.module.mcbp-v3,
    pl.upaid.internal.module.security, com.mastercard.mpsdk, 
	pl.upaid.nativesecurity, pl.upaid.sdk.mdes, pl.upaid.module.delivery, pl.upaid.internal.module.worker " />
```

</td></tr></tbody></table>

SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.

**Android APIs 31+**

Android Worker uses PendingIntent which causes some problems with the newest Android APIs. To resolve this problem application Gradle dependency configuration must override this dependency.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="60bc9361-5af9-4961-86bb-f4a29db8f7bf" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-dependencies%7B-implem-1"><tbody><tr><td class="wysiwyg-macro-body">```
dependencies{
	implementation 'androidx.work:work-runtime-ktx:2.7.1'
} 
```

</td></tr></tbody></table>

Native libs extraction in AndroidManifest and Gradle.

Native libs should be packaged in application in uncompressed form due to security reasons.

This solution is also recommended by Google due to the smaller app install and download size.

Note: Starting from Android Gradle Plugin 4.2 an attribute is replaced with parameter `<span class="pln">android.packagingOptions.jniLibs.useLegacyOptions</span>`.

  
If you need to package native libraries in the compressed form please contact Verestro.

Recommended solution when using Verestro SDK below:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="5a9fd133-e48b-4fc8-922e-baf18a81edbd" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%2F%2Fandroidmanifest.xm"><tbody><tr><td class="wysiwyg-macro-body">```
//AndroidManifest.xml

<application
    android:extractNativeLibs="false"
    ... >
</application>
```

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="9d30133f-7177-4af6-9d24-d599d94f2931" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%2F%2Fbuild.gradle-andro"><tbody><tr><td class="wysiwyg-macro-body">```
//build.gradle

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging false
        }
    }
}
```

</td></tr></tbody></table>

**Source code obfuscation and optimization**

As SDK is written in Kotlin the language we recommend adding following code to Gradle configuration:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="cd915575-cc6d-4123-9c81-6f58583354ed" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-android-%7B-...-kotlin"><tbody><tr><td class="wysiwyg-macro-body">```
android {
	...	 
	kotlinOptions {
    	freeCompilerArgs = [
        	    '-Xno-param-assertions',
        	    '-Xno-call-assertions',
        	    '-Xno-receiver-assertions'
    	]
	}

	packagingOptions {
    	exclude '/kotlin_metadata/**'
	}
	...
}
```

</td></tr></tbody></table>

And use the newest tools for code shrinking, optimization, and obfuscation from Google by enabling R8 instead Proguard in the *gradle.properties* file:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="af2de44e-2280-4dd2-8ef5-c8b15964baac" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-android.enabler8%3Dtru"><tbody><tr><td class="wysiwyg-macro-body">```
android.enableR8=true
```

</td></tr></tbody></table>

**Android permissions**

**QUERY\_ALL\_PACKAGES**

Module declares the usage of permission QUERY\_ALL\_PACKAGES, which is required since Android API 30 to list packages available on the device.  
Permission is used for security tasks.

On 20.07.2022 Google Play introduced restrictions on high-risk permissions and the application sender could be obliged to send more information about this permission usage.

The application which uses this permission is usually a bank or financial institution - in such case permission may be granted to usage.  
Read more [https://support.google.com/googleplay/android-developer/answer/10158779?hl=en](https://support.google.com/googleplay/android-developer/answer/10158779?hl=en)

In case of lack of agreement from Google Play permission could be removed on the application side AndroidManifest.xml file.  
When removed application should declare package visibility to search known root packages.

**<u>In case of removing this permission please contact Verestro representative.</u>**

Sample code to remove QUERY\_ALL\_PACKAGES permission in the AndroidManigest.xml file and package visibility declaration:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="95dca755-c865-43dd-8f4c-bb0491ce689f" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%3Cmanifest-package%3D%22c"><tbody><tr><td class="wysiwyg-macro-body">```
<manifest package="com.sampleapp">
	
	<!-- remove permission from manifest -->
	<uses-permission
    	android:name="android.permission.QUERY_ALL_PACKAGES"
    	tools:ignore="QueryAllPackagesPermission"
    	tools:node="remove" />
        
        CONTACT VERESTRO TO GET 

	<!-- declare application visibility -->
	<queries>
  
  		IMPORTANT!
        CONTACT VERESTRO TO GET PACKAGES LIST
  
    </queries>
```

</td></tr></tbody></table>

**Additional dependency for Huawei / HMS integrations**

 If the application integrates Mobile DC SDK in Huawei / HMS distribution, add the following dependency:

```
dependencies {
  implementation 'com.huawei.hms:safetydetect:6.3.0.301'
}
```

The dependency is required because the SDK uses Huawei Safety Detect classes to perform Huawei attestation flow on HMS devices.

If it is not added, Huawei / HMS builds may fail during code shrinking or the application may crash at runtime when Huawei attestation is triggered.

This dependency is required only for Huawei / HMS integrations and is not needed for Google Play / GMS integrations.

### MDC SDK Size

The size of SDK is dependent on the apk distribution system.

The table below shows the size of the module for apk and bundle file.

<table class="wrapped relative-table confluenceTable" id="bkmrk-format-size-notes-ap" style="width: 100%; height: 110.55px;"><colgroup><col style="width: 13.2313%;"></col><col style="width: 11.4398%;"></col><col style="width: 75.3388%;"></col></colgroup><tbody><tr style="height: 29.9167px;"><th class="confluenceTh" style="height: 29.9167px;">**Format**</th><th class="confluenceTh" style="height: 29.9167px;">**Size**</th><th class="confluenceTh" style="height: 29.9167px;">**Notes**</th></tr><tr style="height: 50.7167px;"><td class="confluenceTd" style="height: 50.7167px;">APK all architectures</td><td class="confluenceTd" style="height: 50.7167px;">~12,8MB</td><td class="confluenceTd" style="height: 50.7167px;">Size compared to empty application.</td></tr><tr style="height: 29.9167px;"><td style="height: 29.9167px;">APK Arm64</td><td style="height: 29.9167px;">~2.3 MB</td><td style="height: 29.9167px;">Size compared to empty application.</td></tr></tbody></table>

<span class="inline-comment-marker" data-ref="71f32ad2-2cb9-4467-b639-71582fb7508d">Additional information</span>

- size from the table above is referred to release version;
- size depends on configured proguard (module provides consumer progurd rules);

### MDC SDK usage

This chapter describes the structure and basic usage of Mobile DC SDK.

#### Domains

Every described facade is divided into domains with different responsibilities.

Available domains:

- Cards.
- User.
- Device.
- CloudMessaging.
- TransactionsHistory.

Every domain contains domain-related methods.

#### Facade

The facade is an entry point to communication with Mobile DC SDK.

Contains an SDK initialization method and domains which allows to manage Verestro account.

#### Multiple facade types

Mobile DC SDK provides three public APIs with the same functionalities, the APIs are:

- MobileDcApiJava for projects which use Java programming language.
- MobileDcApiKotlin for projects which use Kotlin programming language.

The difference between the APIs is a way of providing data to SDK methods and getting the results from them.

Input and output as information data are always the same.

This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).

#### Method structure

Every method described in documentation has same structure.

**Execution type:**

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

**Method type:**

- Online - Operation requires internet connection.
- Offline - Operation can be called without internet access.

**Input**

Input parameters with name, description and validation rules. For some methods input is result of different Verestro method.

**Output**

If present is delivered in success callback with data described below.

**Callbacks**

- Success callback - Depends on used programming language and facade type <span class="toc-item-body">[Multiple facade types.](https://wiki.verestro.com/pages/viewpage.action?pageId=67340674)</span> <span class="inline-comment-marker" data-ref="4b21e998-1763-4a1f-98f3-ace7533c14f0">s</span> onSuccess or success callback inform about operation success.
- Success callback with data - Callback with additional result object.
- Failure callback - Informs about failure. Contains information about exception ([Error handling.](https://wiki.verestro.com/pages/viewpage.action?pageId=67340690)). Exception can contains additional details.

**Sample usage:**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="34e8edd0-f624-46c0-832e-0e3f50232cb6" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%2F%2Fjava-sample-cardss"><tbody><tr><td class="wysiwyg-macro-body">```
//java sample

cardsService.getAll(
        new SuccessDataCallback<List<Card>>() {
            @Override
            public void onSuccess(List<Card> cards) {
                //show cards on UI
            }
        }, new FailureCallback() {
            @Override
            public void onFailure(@NotNull Throwable throwable) {
                //show error
            }
        });

SuccessDataCallback and FailureCallback could be replaced by lambda like in kotlin sample below

//kotlin sample

cardsService.getAll({ cards ->
    //show cards on UI
}, {
    //show error
})
```

</td></tr></tbody></table>

#### Error handling

SDK returns errors by exceptions, which could be caught by the application and shown on UI with a detailed message.

**Note:** Exception message is only information for a developer and shouldn't be shown on the application UI to the user. Use reason code to add a suitable message on the application layer.

 The table below describes exceptions types.

<table class="relative-table wrapped confluenceTable" id="bkmrk-exception-type-excep"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Exception type**</th><th class="confluenceTh">**Exception class**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">SDK Validation</td><td class="confluenceTd">ValidationException</td><td class="confluenceTd">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

</td></tr><tr><td class="confluenceTd">Backend</td><td class="confluenceTd">BackendException</td><td class="confluenceTd">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

</td></tr><tr><td class="confluenceTd" colspan="1">Internal Sdk</td><td class="confluenceTd" colspan="1">CoreSdkException</td><td class="confluenceTd" colspan="1">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

</td></tr><tr><td class="confluenceTd">Process related</td><td class="confluenceTd">-</td><td class="confluenceTd">As every process is different some methods could throw specified exception. Types of exception is described in method description

</td></tr><tr><td class="confluenceTd" colspan="1">Network</td><td class="confluenceTd" colspan="1">NetworkConnectionException</td><td class="confluenceTd" colspan="1">Provide information about network connection error. Check table with possible reasons below</td></tr><tr><td class="confluenceTd" colspan="1">Internal</td><td class="confluenceTd" colspan="1">UnknownException</td><td class="confluenceTd" colspan="1">For unknown errors in SDK process</td></tr></tbody></table>

**BackendException error codes**

<table id="bkmrk-reason-code-descript" width="100%"><tbody><tr><td style="width: 36.5919%;">**Reason code**

</td><td style="width: 63.4081%;">**Description**

</td></tr><tr><td style="width: 36.5919%;" width="24%">INTERNAL\_ERROR

</td><td style="width: 63.4081%;" width="75%">Error occurred on server

</td></tr><tr><td style="width: 36.5919%;" width="24%">CRYPTOGRAPHY\_ERROR

</td><td style="width: 63.4081%;" width="75%">Error occurred during cryptography operation

</td></tr><tr><td style="width: 36.5919%;" width="24%">VALIDATION\_ERROR

</td><td style="width: 63.4081%;" width="75%">Client sent invalid data

</td></tr><tr><td style="width: 36.5919%;">CLIENT\_NOT\_FOUND

</td><td style="width: 63.4081%;"><span class="inline-comment-marker active" data-ref="e690f021-e188-4f32-8df4-888bdd89930e">Requested client id not found</span>

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_NO\_OUTSIDE\_RANGE\_BINS

</td><td style="width: 63.4081%;" width="75%">Card number is outside of preconfigured range

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_KIND\_LIMIT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Card kind limit reached

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_DELETED

</td><td style="width: 63.4081%;" width="75%">Card was deleted and operation cannot be proceed

</td></tr><tr><td style="width: 36.5919%;" width="24%">FAIL\_3DS\_VERIFICATION

</td><td style="width: 63.4081%;" width="75%">3ds verification failed

</td></tr><tr><td style="width: 36.5919%;" width="24%">FAIL\_AUTHORIZATION

</td><td style="width: 63.4081%;" width="75%">Fail authorization - error from card verification

</td></tr><tr><td style="width: 36.5919%;" width="24%">TRANSACTION\_DENIED

</td><td style="width: 63.4081%;" width="75%">Transaction denied - error from card verification

</td></tr><tr><td style="width: 36.5919%;" width="24%">FAIL\_AUTHENTICATION

</td><td style="width: 63.4081%;" width="75%">Invalid username or password

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_EXPIRED

</td><td style="width: 63.4081%;" width="75%">Card expired

</td></tr><tr><td style="width: 36.5919%;" width="24%">LIMITS\_EXCEEDED

</td><td style="width: 63.4081%;" width="75%">Limit of transactions has been exceeded

</td></tr><tr><td style="width: 36.5919%;" width="24%">REJECTED\_BY\_BANK

</td><td style="width: 63.4081%;" width="75%">Current transaction has been rejected by bank - error from card verification

</td></tr><tr><td style="width: 36.5919%;" width="24%">INSUFFICIENT\_FOUNDS

</td><td style="width: 63.4081%;" width="75%">There is no enough founds on card to complete this transaction

</td></tr><tr><td style="width: 36.5919%;" width="24%">INVALID\_JWS\_TOKEN

</td><td style="width: 63.4081%;" width="75%">Specified JWS token is invalid

</td></tr><tr><td style="width: 36.5919%;" width="24%">INVALID\_FCM\_TOKEN

</td><td style="width: 63.4081%;" width="75%">Given FCM token is invalid

</td></tr><tr><td style="width: 36.5919%;" width="24%">OPERATION\_NOT\_SUPPORTED

</td><td style="width: 63.4081%;" width="75%">Method is not allowed

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_USER

</td><td style="width: 63.4081%;" width="75%">Cannot find user by requested identifier

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_CARD

</td><td style="width: 63.4081%;" width="75%">Cannot find card by requested identifier

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_DEVICE

</td><td style="width: 63.4081%;" width="75%">Cannot find device by requested identifier

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_WPIN

</td><td style="width: 63.4081%;" width="75%">Cannot find wallet pin

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_ADDRESS

</td><td style="width: 63.4081%;" width="75%">Cannot find requested address

</td></tr><tr><td style="width: 36.5919%;" width="24%">CANT\_FIND\_INVITATION

</td><td style="width: 63.4081%;" width="75%">Cannot find invitation for the requested resource

</td></tr><tr><td style="width: 36.5919%;" width="24%">RESOURCE\_NOT\_FOUND

</td><td style="width: 63.4081%;" width="75%">Cannot find requested resource

</td></tr><tr><td style="width: 36.5919%;" width="24%">USER\_IS\_LOCKED

</td><td style="width: 63.4081%;" width="75%">Requested user is locked

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_IS\_LOCKED

</td><td style="width: 63.4081%;" width="75%">Requested card is locked

</td></tr><tr><td style="width: 36.5919%;" width="24%">DEVICE\_PERMANENTLY\_LOCKED

</td><td style="width: 63.4081%;" width="75%">Requested device is locked

</td></tr><tr><td style="width: 36.5919%;" width="24%">DEVICE\_TEMPORARILY\_LOCKED

</td><td style="width: 63.4081%;" width="75%">Requested device is temporary locked

</td></tr><tr><td style="width: 36.5919%;" width="24%">BAD\_LOGIN\_LIMIT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Number of incorrect login attempts is reached

</td></tr><tr><td style="width: 36.5919%;" width="24%">BAD\_WPIN\_LIMIT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Requested user is temporary locked

</td></tr><tr><td style="width: 36.5919%;" width="24%">SMS\_FAILCOUNT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Sms fail count limit reached

</td></tr><tr><td style="width: 36.5919%;" width="24%">TOO\_MANY\_REQUESTS

</td><td style="width: 63.4081%;" width="75%">Too Many Requests

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_IS\_ALREADY\_VERIFIED

</td><td style="width: 63.4081%;" width="75%">Requested card has been verified

</td></tr><tr><td style="width: 36.5919%;" width="24%">USER\_IS\_NOT\_VERIFIED

</td><td style="width: 63.4081%;" width="75%">User is not verified. E.g. User had registered already however did not finish the verification step and is trying to pair/login

</td></tr><tr><td style="width: 36.5919%;" width="24%">PAYMENT\_ALREADY\_SUCCESS

</td><td style="width: 63.4081%;" width="75%">Requested payment has been already finished

</td></tr><tr><td style="width: 36.5919%;" width="24%">INVALID\_CARD

</td><td style="width: 63.4081%;" width="75%">Card is invalid for this payment

</td></tr><tr><td style="width: 36.5919%;" width="24%">USER\_HAS\_NOT\_SET\_A\_PASSWORD

</td><td style="width: 63.4081%;" width="75%">Requested user has not set password

</td></tr><tr><td style="width: 36.5919%;" width="24%">DEVICE\_LIMIT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Number of device is reached

</td></tr><tr><td style="width: 36.5919%;" width="24%">BAD\_WPIN

</td><td style="width: 63.4081%;" width="75%">The wallet pin does not match the requested user

</td></tr><tr><td style="width: 36.5919%;" width="24%">SMS\_LIMIT\_EXCEEDED

</td><td style="width: 63.4081%;" width="75%">Number of sent messages has reached the limit. Please try again later

</td></tr><tr><td style="width: 36.5919%;" width="24%">FAIL\_COUNT\_LIMIT\_REACHED

</td><td style="width: 63.4081%;" width="75%">Attempt limit has exceeded

</td></tr><tr><td style="width: 36.5919%;" width="24%">INITIALIZE\_PROCESS\_REQUIRED

</td><td style="width: 63.4081%;" width="75%">Fail count limit has been reached and new process has not been initialized

</td></tr><tr><td style="width: 36.5919%;" width="24%">INVALID\_AUTHORIZATION\_AMOUNT

</td><td style="width: 63.4081%;" width="75%">Authorization amount is incorrect

</td></tr><tr><td style="width: 36.5919%;" width="24%">CLIENT\_UNAUTHORIZED

</td><td style="width: 63.4081%;" width="75%">Client of the api is unauthorized(invalid/expired *X-Client-Auth* token)

</td></tr><tr><td style="width: 36.5919%;" width="24%">USER\_UNAUTHORIZED

</td><td style="width: 63.4081%;" width="75%">User is unauthorized

</td></tr><tr><td style="width: 36.5919%;" width="24%">VERIFICATION\_FAILED

</td><td style="width: 63.4081%;" width="75%">Requested card could not be verified

</td></tr><tr><td style="width: 36.5919%;" width="24%">CARD\_NOT\_ENROLLED

</td><td style="width: 63.4081%;" width="75%">Card does not participate in 3ds v2, please use 3ds v1

</td></tr><tr><td style="width: 36.5919%;" width="24%">INVALID\_AUTHENTICATION\_ID

</td><td style="width: 63.4081%;" width="75%">Authentication process id does not match card id

</td></tr><tr><td style="width: 36.5919%;">ATTESTATION\_FAILED

</td><td style="width: 63.4081%;">The attestation request failed

</td></tr><tr><td style="width: 36.5919%;">ATTESTATION\_PLAY\_INTEGRITY\_REQUIRED

</td><td style="width: 63.4081%;">The Play Store app is not installed, or it is not the official version, or it is an old version

</td></tr></tbody></table>

**BackendException - additional error codes** **related to TransactionsHistoryService**

<table id="bkmrk-reason-code-descript-0" style="width: 100%;"><tbody><tr><td style="width: 42.0177%;">**Reason code**

</td><td style="width: 57.9823%;">**Description**

</td></tr><tr><td style="width: 42.0177%;">TRANSACTION\_ATTACHMENT\_STATUS\_APPROVED

</td><td style="width: 57.9823%;">Cannot update transaction or store new attachment. Attachment status in transaction is APPROVED

</td></tr><tr><td style="width: 42.0177%;">MAX\_ATTACHMENTS\_COUNT

</td><td style="width: 57.9823%;">Maximum number of attachments for given transaction

</td></tr><tr><td style="width: 42.0177%;">MAX\_ATTACHMENT\_SIZE\_EXCEEDED

</td><td style="width: 57.9823%;">Maximum attachment size exceeded

</td></tr><tr><td style="width: 42.0177%;">EMPTY\_ATTACHMENT

</td><td style="width: 57.9823%;">Empty attachment file

</td></tr><tr><td style="width: 42.0177%;">EMPTY\_ATTACHMENT\_NAME

</td><td style="width: 57.9823%;">Empty attachment file name

</td></tr><tr><td style="width: 42.0177%;">NOT\_SUPPORTED\_ATTACHMENT\_FILE\_TYPE

</td><td style="width: 57.9823%;">Attachment file type is not supported

</td></tr><tr><td style="width: 42.0177%;">CANT\_FIND\_TRANSACTION\_ATTACHMENT

</td><td style="width: 57.9823%;">Cannot find transaction attachment

</td></tr></tbody></table>

**CoreSdkException error codes INTERNAL\_ERROR**

<table class="relative-table wrapped confluenceTable" id="bkmrk-reason-code-descript-1" style="width: 100%; height: 1013.85px;"><colgroup><col style="width: 41.7783%;"></col><col style="width: 58.2217%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="confluenceTh" style="height: 29.8px;">Reason code</th><th class="confluenceTh" style="height: 29.8px;">Description</th></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">DEVICE\_NOT\_PAIRED</td><td class="confluenceTd" style="height: 29.8px;">Device is not paired or trying to call the method without device pairing</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">SAFETYNET\_ERROR</td><td class="confluenceTd" style="height: 29.8px;">An error during device authentication in Google SafetyNet service

Deprecated, replaced by ATTESTATION\_API\_ERROR

</td></tr><tr style="height: 63.3833px;"><td class="confluenceTd" style="height: 63.3833px;">PUSH\_INVALID\_SOURCE</td><td class="confluenceTd" style="height: 63.3833px;">Relates to push processing process. Push message should be consumed in another module

</td></tr><tr style="height: 40.9833px;"><td class="confluenceTd" style="height: 40.9833px;">PUSH\_INVALID\_PUSH\_CONTENT</td><td class="confluenceTd" style="height: 40.9833px;">Cannot process push message. The message is invalid or some process failed

</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">BIOMETRIC\_AUTHENTICATION\_NOT\_ENABLED</td><td class="confluenceTd" style="height: 46.6px;">Biometric public key is invalid</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">BIOMETRIC\_AUTHENTICATION\_ABORTED</td><td class="confluenceTd" style="height: 46.6px;">Cannot authenticate biometric signature</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">KEYSTORE\_IS\_NOT\_SECURE</td><td class="confluenceTd" style="height: 29.8px;">Keystore is not secure. The device is not secured with PIN, pattern or password</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">CANNOT\_GET\_PUBLIC\_KEY</td><td class="confluenceTd" style="height: 29.8px;">Internal error during SDK processing</td></tr><tr style="height: 108.167px;"><td class="confluenceTd" style="height: 108.167px;">SECURITY\_EVENT\_OCCURRED</td><td class="confluenceTd" style="height: 108.167px;">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

</td></tr><tr style="height: 40.9833px;"><td class="confluenceTd" style="height: 40.9833px;">PIN\_AUTHENTICATION\_FAILURE

</td><td class="confluenceTd" style="height: 40.9833px;">Provided PIN is invalid</td></tr><tr style="height: 63.3833px;"><td class="confluenceTd" style="height: 63.3833px;">PIN\_AUTHENTICATION\_FAILURE\_LIMIT\_EXCEEDED

</td><td class="confluenceTd" style="height: 63.3833px;">PIN fail count is reached, every next try PIN authentication will finish with this status</td></tr><tr style="height: 85.7667px;"><td class="confluenceTd" style="height: 85.7667px;">PIN\_AUTHENTICATION\_NOT\_POSSIBLE

</td><td class="confluenceTd" style="height: 85.7667px;">PIN authentication is not possible until the user is at least once logged online with PIN</td></tr><tr style="height: 63.3833px;"><td class="confluenceTd" style="height: 63.3833px;">PIN\_AUTHENTICATION\_INTERNAL\_ERROR

</td><td class="confluenceTd" style="height: 63.3833px;">Something went wrong during PIN authentication  
</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">PAIRING\_IS\_ALREADY\_IN\_PROGRESS</td><td class="confluenceTd" style="height: 29.8px;">Another pairing is now processed</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND</td><td class="confluenceTd" style="height: 46.6px;">No default payment instrument for contactless payment found</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">PAYMENT\_INSTRUMENT\_NOT\_FOUND</td><td class="confluenceTd" style="height: 46.6px;">Payment instrument with this id cannot be found in SDK</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">APPLICATION\_PROCESS\_NOT\_KILLED</td><td class="confluenceTd" style="height: 46.6px;">Application process is not killed after SDK reset</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">TOKEN\_NOT\_ACTIVE</td><td class="confluenceTd" style="height: 29.8px;">Required token status is ACTIVE</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">PAYMENT\_INSTRUMENT\_NOT\_FOUND</td><td class="confluenceTd" style="height: 46.6px;">Token with that id was not found in SDK</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">API\_SERVICE\_NOT\_INITIALIZED</td><td class="confluenceTd" style="height: 29.8px;">API service was not initialized</td></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">DIGITIZATION\_NOT\_STARTED</td><td class="confluenceTd" style="height: 29.8px;">Digitization of that payment instrument was not started</td></tr><tr><td>ATTESTATION\_API\_ERROR  
</td><td>An error during device authentication in Device Attestation service (Play Integrity)  
</td></tr></tbody></table>

**NetworkConnectionException error codes**

<table class="relative-table wrapped confluenceTable" id="bkmrk-reason-code-descript-2" style="width: 100.494%;"><colgroup><col style="width: 35.0671%;"></col><col style="width: 64.9329%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Reason code**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">UNKNOWN\_HOST</td><td class="confluenceTd">Host is unreachable, check network connection and try again later

</td></tr><tr><td class="confluenceTd">SOCKET\_TIMEOUT</td><td class="confluenceTd">Connection timeout, check network connection and try again later</td></tr><tr><td class="confluenceTd" colspan="1">UNKNOWN\_HTTP\_ERROR</td><td class="confluenceTd" colspan="1">An unknown HTTP error</td></tr></tbody></table>

###   


### Firebase Cloud Messaging configuration 

**Dependency**

Add Firebase Cloud Messaging dependency entry to build.gradle.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="db5f2755-0880-497f-9476-19a1d5b50f56" data-macro-name="code" data-macro-parameters="language=groovy" data-macro-schema-version="1" id="bkmrk-...-implementation%28%27"><tbody><tr><td class="wysiwyg-macro-body">```
...

implementation('com.google.firebase:firebase-messaging:22.0.0')

...
```

</td></tr></tbody></table>

**Initializing**

All parameter required to initialize FCM can get from firebase console.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="a889a0e2-4935-47f6-a995-60019e513f28" data-macro-name="code" data-macro-parameters="language=java" data-macro-schema-version="1" id="bkmrk-val-firebaseoptions-"><tbody><tr><td class="wysiwyg-macro-body">```
val firebaseOptions =
            FirebaseOptions
                .Builder()
                .setApplicationId(applicationId)
                .setGcmSenderId(senderId)
                .setProjectId(projectId)
                .setApiKey(apiKey)
                .build()
FirebaseApp.initializeApp(this, firebaseOptions)
```

</td></tr></tbody></table>

To initialize two FCM projects should add name parameter for second one.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="4a727d1a-1274-488b-89cf-1d51e3d51422" data-macro-name="code" data-macro-parameters="language=java" data-macro-schema-version="1" id="bkmrk-%2F%2Finit-default-proje"><tbody><tr><td class="wysiwyg-macro-body">```
//init default project
FirebaseApp.initializeApp(this, firebaseOptions)
 
//init additional project
FirebaseApp.initializeApp(this, firebaseOptionsOther, otherProjectName)
```

</td></tr></tbody></table>

**Getting FCM registration token**

FCM token should be get periodically on application side to make sure it's actual.   
When token change detected application should update Cloud Messaging token with SDK API.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="cafa42ff-f701-4850-ba04-e10dac60da34" data-macro-name="code" data-macro-parameters="language=java" data-macro-schema-version="1" id="bkmrk-%2F%2Fgetting-token-for-"><tbody><tr><td class="wysiwyg-macro-body">```
//getting token for default project
FirebaseMessaging.getInstance().token
    .addOnCompleteListener {
        //handle token, save in storage to provide in SDK methods
    }
  
  
//getting token for additional project
val messaging = FirebaseApp.getInstance("other").get(FirebaseMessaging::class.java)
messaging.token.addOnCompleteListener {
    //handle token save in storage to provide in SDK methods
}
```

</td></tr></tbody></table>

### Security processes overview

This document contains short information about security mechanisms used by SDK. Only high-level functions are described, without technical specifications.

Security processes were designed to protect its assets, and ensure that the application using our product is installed on a safe environment.

SDK verify checks like root detection, certificate, hook, emulator detection, debug check and more.<span class="inline-comment-marker" data-ref="312b2529-54f3-44c1-bd06-49f6cdf0684b">  
</span>

SDK security mechanism starts just after initialisation of library. Because of process optimalization part of checks are made only once, other are called periodically.

**SafetyNet Api - deprecated from version 2.14.6**

API tool used for protecting application from tampering, harmful applications, and validating device OS. It availability depends on project configuration.

Usage of this process is configured on server side. If end application already performs this process it could be disabled during project configuration.

**Play Integrity API**

Due to Safetynet Attestation API planned deprecation it's replaced by Play Integrity API in Mobile DC version 2.14.6.

API tool used for protecting application from tampering, harmful applications, and validating device OS. It availability depends on project configuration.

Usage of this process is configured on server side. If end application already performs this process it could be disabled during project configuration.

When used, Play Integrity API must be enabled Google Play Developer Console - [https://developer.android.com/google/play/integrity/setup#enable-responses](https://developer.android.com/google/play/integrity/setup#enable-responses).

**<span class="inline-comment-marker" data-ref="52d8f089-a5c6-48fb-b7c6-303e6c3866fb">Error codes handling in application</span>**

<span class="inline-comment-marker" data-ref="52d8f089-a5c6-48fb-b7c6-303e6c3866fb">When SDK detect security issue with callback onSecurityIssueAppeared an application should show error that application cannot be used.</span>

### Application Isolated Process (Deprecated)

**Overview**

Starting from Mobile DC SDK version 2.4.3 SDK provides additional security checks which could be enabled in [setup.](https://wiki.verestro.com/pages/viewpage.action?pageId=67340696) method using "withOptionalDeveloperOptions" and enableAdditionalSecurityChecks parameter.

For some security processes SDK need to start services marked as *isolatedProcess* to ensure more security by splitting application from a security layer.  
It may cause problems with initialize Application as this service will run under a special process that is isolated from the rest of the system and has no permissions of its own.

To avoid problems, check if application start from isolated process and do not invoke any additional action in your Application::onCreate.

**Sample implementation**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="e9e5b08c-8900-4344-8a6e-8214aefafb3c" data-macro-name="code" data-macro-parameters="language=java" data-macro-schema-version="1" id="bkmrk-%2F%2Fmobile-dc-setup-co"><tbody><tr><td class="wysiwyg-macro-body">```
//Mobile DC setup configuration for enableAdditionalSecurityChecks 

val developerOptions = DeveloperOptions()
//Field removed in 2.16.0
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
        	}
    	}
	}
}
```

</td></tr></tbody></table>

This functionality is introduced to protect against magisk tool.

Magisk gives root access using daemon, which starts with system booting, with unrestricted SELinux context. When specific application needs access to /su it connects to daemon unix socket, process of granting access access is managed with Magisk Manager application.

Magisk Hide function hides /sbin paths for specific process, what obscures magisk presence in /proc/pid/mounts. This problems is solved with isolated processes introduced in android 4.1. They are started with new, fresh SELinux context without any permissions, what keeps magisk from removing it paths with /sbin. From this process view there is possibility to check mounted paths and find evidences of magisk presence.

### Data signing and encryption

#### Configuration

**Signing Data Configuration**

Signature will be verified using public key certificate which was signed by preconfigured Root CA. DN from the certificate will be also validated. Root CA and DN will be set during onboarding. Client has two options:

- provide Root CA and DN of the public key certificate for the private key which already has and use this private key for signing data.
    
    <table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b03719a2-8b60-4892-91ee-092f9d72f551" data-macro-name="info" data-macro-schema-version="1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">DN cannot change during certificate renewals and all intermediate certificates should be placed in JWT</p>
    
    </td></tr></tbody></table>
- generate csr where `CN=Signature-${uniqueClientName}`. Csr will be signed by Verestro. Client needs to use private key for signing from key pair used to generate csr.

**Encryption Data Configuration**

If the client decide to encrypt data, public key certificate from RSA 2048 should be set during onboarding. **Public key certificate can be self-signed.**

**Signed Data Verification**

<span class="inline-comment-marker" data-ref="a72b8cd0-8cb4-482a-b4ef-d9f6070660c8">Some methods requires signed data verification on client side. Public key certificate from RSA 2048 will be provided during onboarding and should be used for signature validation.</span>

#### Data Encryption

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b871d406-e912-44c5-8233-d9ebef041cb4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-some-data-like-token"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Some data like Token Verification Code can be encrypted using JWE per RFC 7516.</p>

</td></tr></tbody></table>

Configured(see *Encrypting Data Configuration* *in Confoguration chapter*) public key certificate will be used to encrypt CEK(Content Encryption Key).

**Algorithm used for encryption:**

<table class="wrapped confluenceTable" id="bkmrk-jwe-header-name-desc"><colgroup><col></col><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**JWE header**</th><th class="confluenceTh">**Name**</th><th class="confluenceTh">**Description**</th></tr></thead><tbody><tr><td class="confluenceTd">alg

</td><td class="confluenceTd">RSA-OAEP-256

</td><td class="confluenceTd">Cryptographic algorithm used to encrypt CEK

</td></tr><tr><td class="confluenceTd">enc

</td><td class="confluenceTd">A256GCM

</td><td class="confluenceTd">Identifies the content encryption algorithm used to perform authenticated encryption

</td></tr></tbody></table>

Payload of the JWE will be json formatted object.

Client needs to perform decryption with private key using standard JWE library.

**Sample code which shows how to decrypt JWE for given encryptedData and privateKey**:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="31629ebf-8702-4275-87e4-4c27fa4f8550" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-rsajwedecrypte"><tbody><tr><td class="wysiwyg-macro-body">```
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()
    }
}
```

</td></tr></tbody></table>

#### Data Signing

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0f9af74f-2b85-42ef-bf64-6e86cad825bc" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-some-fields-are-sign"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Some fields are signed using JWT per RFC 7519.</p>

<p class="callout info">Data signing should be done on **server side**.</p>

</td></tr></tbody></table>

JWTs are composed of three sections: a header, a payload (containing a claim set), and a signature.

The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding.

The JWT’s header, payload, and signature are concatenated with periods (.). As a result, a JWT typically takes the following form:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="9a464607-d8e1-44cc-b7bc-1a8281fb4b28" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%7Bbase64url-encoded-h"><tbody><tr><td class="wysiwyg-macro-body">```
{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}
```

</td></tr></tbody></table>

Object fields should be placed as claims in the token. Moreover there are some additional required claims that are needed to protect against replay attack:

<table class="relative-table wrapped confluenceTable" id="bkmrk-name-description-iat"><colgroup><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Name**</th><th class="confluenceTh">**Description**</th></tr></thead><tbody><tr><td class="confluenceTd">iat

</td><td class="confluenceTd">The time at which the JWT was issued. UNIX Epoch timestamp, in seconds

</td></tr><tr><td class="confluenceTd">jti

</td><td class="confluenceTd">JWT ID - unique identifier for the JWT

</td></tr></tbody></table>

JWT tokens have TTL which is validated against "issued at" time from claims (iat). TTL is 10 minutes.

JWT tokens should be signed using private key from the RSA 2048 key pair (see *Signing Data Configuration in Configuration chapter*).

**JWT tokens must have additional header:**

<table class="wrapped relative-table confluenceTable" id="bkmrk-name-description-x5c"><colgroup><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Name**</th><th class="confluenceTh">**Description**</th></tr></thead><tbody><tr><td class="confluenceTd">x5c

</td><td class="confluenceTd">Parameter contains the X.509 certificates chain ([RFC7515#section-4.1.6](https://tools.ietf.org/html/rfc7515#section-4.1.6))

</td></tr></tbody></table>

This chain will be validated against preconfigured Root CA. DN from the public key certificate(from key pair which private key was used for signing) will be also validated (See *Signing Data Configuration in Configuration chapter*).

**Sample code which shows how to build JWT for given claims, certificates and <span class="inline-comment-marker" data-ref="ecf63aeb-038d-46ac-9817-5d6c3953661b">private key</span>:**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6900e1a9-b7cf-44a9-bc57-fa69c825c59e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-jwtgenerator-%7B"><tbody><tr><td class="wysiwyg-macro-body">```
class JwtGenerator {
    
    fun generate(
        jwtClaimsSet: JWTClaimsSet,
        certificates: List<X509Certificate>,
        privateKey: PrivateKey
    ): String {

        val claims = buildFinalClaims(jwtClaimsSet)

        val certChains = certificates
            .map { it.encoded }
            .map { Base64.encode(it) }

        val jwsHeader = JWSHeader.Builder(JWSAlgorithm.RS256)
            .x509CertChain(certChains)
            .build()

        val signer = RSASSASigner(privateKey)

        val jwsObject = JWSObject(
            jwsHeader,
            Payload(claims.toJSONObject())
        )

        jwsObject.sign(signer)

        return jwsObject.serialize()
    }


    private fun buildFinalClaims(jwtClaimsSet: JWTClaimsSet): JWTClaimsSet {

        val epochSeconds = Instant.now().epochSecond

        return JWTClaimsSet
            .Builder(jwtClaimsSet)
            .claim("iat", epochSeconds)
            .jwtID(UUID.randomUUID().toString())
            .build()
    }
}
```

</td></tr></tbody></table>

####   


#### Signed data verification

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0f9af74f-2b85-42ef-bf64-6e86cad825bc" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-some-fields-are-sign-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Some fields are signed on Wallet Server using JWT per RFC 7519.</p>

</td></tr></tbody></table>

Wallet Server signs some data in response and signature has to be verified before this data are used. Data are signed using JWT per RFC 7519. JWTs are composed of three sections: a header, a payload (containing a claim s<span class="inline-comment-marker" data-ref="4d70d56f-9aec-4f85-b8ea-be05fedf4ff9">et) and a</span> signature.

The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding.

The JWT's header, payload, and signature are concatenated with period<span class="inline-comment-marker" data-ref="dc5c8de3-d76b-47f4-9208-8eb6009774b5">s (.).</span>  
As a result, a JWT typically takes the following form:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="9a464607-d8e1-44cc-b7bc-1a8281fb4b28" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%7Bbase64url-encoded-h-0"><tbody><tr><td class="wysiwyg-macro-body">```
{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}
```

</td></tr></tbody></table>

Specific object fields are placed as claims in the JWT token.  
Moreover there are some additional claims that are added to the JWT token to protect against replay attack:

<table class="relative-table wrapped confluenceTable" id="bkmrk-name-description-iat-0"><colgroup><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Name**</th><th class="confluenceTh">**Description**</th></tr></thead><tbody><tr><td class="confluenceTd">iat

</td><td class="confluenceTd">The time at which the JWT was issued. UNIX Epoch timestamp, in seconds

</td></tr><tr><td class="confluenceTd">jti

</td><td class="confluenceTd">JWT ID - unique identifier for the JWT

</td></tr></tbody></table>

JWT tokens are signed using private key from the RSA 2048 key pair. <span class="inline-comment-marker" data-ref="9308531d-9232-4579-89aa-f28262b12909">Public key certificate will be shared as part of configuration</span> of given project and public key should be used for signature validation.

JWT tokens have additional header:

<table class="relative-table wrapped confluenceTable" id="bkmrk-name-description-kid"><colgroup><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Name**</th><th class="confluenceTh">**Description**</th></tr></thead><tbody><tr><td class="confluenceTd">kid

</td><td class="confluenceTd">fingerprint of public key which's corresponding private key was used to sign data calculated as sha1Hex(publicKeyBytes)

</td></tr></tbody></table>

**Sample code which shows how to verify signed JWT:**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6900e1a9-b7cf-44a9-bc57-fa69c825c59e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-jwtverifier-%7B-"><tbody><tr><td class="wysiwyg-macro-body">```
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
        }
    }
```

</td></tr></tbody></table>

### APK Certificate

#### <span class="inline-comment-marker" data-ref="5f483f08-8d5d-4eb7-8ca2-b0cd05969c24">About APK certificate</span>

Verestro provides mechanism which ensures that authorized entities using Verestro SDKs.

To achieve that apk certificate needs to configured during onboarding.

Apk Certificate is binded to given client id, if customer uses many applications then many apk certificates digest should be provided and for each client id will be given by Verestro.

#### <span class="inline-comment-marker" data-ref="a90e9d05-e6d2-455d-a804-09a18d422df9">How to get APK certificate</span>

You can sign your application using self managed key, or let Google Play sign using Google Play managed keys:

- APK or Bundle <span class="inline-comment-marker" data-ref="fecb3c49-8400-44c3-b34c-cd68ae083da6">signing</span> key (aka "upload key").
- Google Play signing key (optional, may be enabled and configured in Google Play Console).

If you update key, you must follow steps below again and provide key to representative Verestro person.

Please check your installation package and follow the outlined steps.

#### <span class="inline-comment-marker" data-ref="3c2c1300-d689-42c2-9c4d-992750885ecc">Using own APK Signing Key</span>

<span class="inline-comment-marker" data-ref="8475f843-6276-4896-98b0-7bf420f058b5">When</span> signing apk in android studio only, please follow the steps below:

1\. Convert java keystore (eg. cert.jks) used to sign APK to p12 format using following command:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="ec4fd0e9-d9a1-4dae-b9c3-c096b6e79868" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-keytool--importkeyst"><tbody><tr><td class="wysiwyg-macro-body">```
keytool -importkeystore -srckeystore cert.jks -destkeystore cert.p12 -srcstoretype jks -deststoretype pkcs12
```

</td></tr></tbody></table>

2\. Convert obtained p12 file (eg. cert.p12) to pem format using following command:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="88fe1b0b-8bd3-4467-ab7b-af4248e2a0d6" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-openssl-pkcs12--noke"><tbody><tr><td class="wysiwyg-macro-body">```
openssl pkcs12 -nokeys -in cert.p12 -out cert.pem
```

</td></tr></tbody></table>

#### <span class="inline-comment-marker" data-ref="e11ef677-15eb-49d4-ab5d-1cf0cc9913ea">Using Google Play Signing Key</span>

When signing application in Google Play console(whenever you uploaded own key, or used one that was automatically generated by Google), please follow steps below:

1. Add .apk or .aab file in google play console.
2. Select "Let Google create and manage my app signing key (recommended)" and press Continue.  
    [![google app sign key.png](https://developer.verestro.com/uploads/images/gallery/2022-11/scaled-1680-/google-app-sign-key.png)](https://developer.verestro.com/uploads/images/gallery/2022-11/google-app-sign-key.png)
3. In the application panel in the menu look for release management option.
4. Select app signing section.  
      
    [![app_signing.png](https://developer.verestro.com/uploads/images/gallery/2022-11/scaled-1680-/app-signing.png)](https://developer.verestro.com/uploads/images/gallery/2022-11/app-signing.png)
5. Download the certificate from App signing certificate section.  
      
    [![app sing cert.png](https://developer.verestro.com/uploads/images/gallery/2022-11/scaled-1680-/app-sing-cert.png)](https://developer.verestro.com/uploads/images/gallery/2022-11/app-sing-cert.png)
6. Convert downloaded certificate from der to pem format using following command:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="a944e1de-9b6a-4e37-878a-e75e62facb50" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-openssl-x509--inform"><tbody><tr><td class="wysiwyg-macro-body">```
openssl x509 -inform der -in deployment_cert.der -out certificate.pem
```

</td></tr></tbody></table>

### Recommended MPA data protection mechanisms

- <span class="inline-comment-marker" data-ref="81d37bf4-4aea-4518-9b6e-bb272c4a58a6">Code obfuscation:</span>  
    Code obfuscation is basic, and one of the most efficient application protection mechanism. Obfuscating code saves your app from static code analysis, exploring your code in search of vulnerabilities, that can be used by hooking software. There are many tools used for obfuscation nowadays, the most popular are proguard and its successor - R8. If you are using Kotlin in your project, R8 is a better option for you. It is also important to keep app architecture supporting obfuscation, using obfuscation tools is as simple as your architecture is adjusted to it.
- Disable logs &amp; turning off debugging:  
    It is very important to remember turning off logging data and disable debugging in your production application. Data printed in logs in development process should never be available in release application. It is recommended to manage printing it from one place, to not 'forget' removing every single of them.
- Input data validation:  
    Input data should be validated on every level of app structure, it reduces risk of processing some unwanted, or even harmful data. It is recommended to clean sensitive data that is no longer useful, we advise to not use string to keep it. String is immutable, data stored in it can later be accessed by dumping application memory. We recommend using **char\[\]**, and overwriting it when it is no longer useful.
- Prevent taking screenshot:  
    We recommend adding a mechanism that prevents taking screenshots, and recording your application. It protects you from harmful applications getting users inputted data.
- Prevent copy/paste :  
    Input taking sensitive data such as user password should not have the ability to copying and pasting in it. Storing it in clipboard expose it for copying, or modifying by harmful applications, even if it was initially encrypted it is plaintext when the user copies it.
- Prevent screen overlay:  
    It is recommended to protect MPA from applications that have the possibility to overlay it. Not securing it may result with recording user data.
- Checking the installer:  
    MPA should implement a mechanism that will check installer of application. It should check if the application is downloaded from Google Play, preventing it from possibility of tampering installation binary.
- Checksum mechanism:  
    Implementing checking checksum mechanism is a very efficient way to check if your application was not tampered. It should compare checksum of your application, prepared after generating app with data send by your app after installing it on device. It bases on the fact that every generated application have different checksum, comparing it can ensure you that your server is communicating with the app released by you.
- Removal redundant permissions:  
    It is important to keep in your app only used permissions. You should not give your application access to components, that it not requires.
- Network security configuration:  
    MPA should use network security configuration application customize their network security settings(for example protection application from usage of cleartext traffic) in declarative configuration file without modifying app code.

### Models

#### LimitedResourceInfo

<table class="confluenceTable" id="bkmrk-parameter-type-descr" style="width: 64.9383%;"><colgroup><col style="width: 29.3413%;"></col><col style="width: 10.7784%;"></col><col style="width: 59.8802%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">xRateLimitLimit</td><td class="confluenceTd">Int?</td><td class="confluenceTd">Limit of requests until resource will be locked</td></tr><tr><td class="confluenceTd" colspan="1">xRateLimitRemaining</td><td class="confluenceTd" colspan="1">Int?</td><td class="confluenceTd" colspan="1">Remaining amount of requests</td></tr><tr><td class="confluenceTd" colspan="1">retryAfter</td><td class="confluenceTd" colspan="1">Int?</td><td class="confluenceTd" colspan="1">Seconds until lock expires</td></tr><tr><td class="confluenceTd" colspan="1">xRateLimitReset</td><td class="confluenceTd" colspan="1">Long?</td><td class="confluenceTd" colspan="1">Lock expiration timestamp - epoch in seconds</td></tr></tbody></table>

### External libraries

The SDK uses several external Apache 2.0 libraries:

- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttp

## MDC SDK Setup

### Setup

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="03d404e5-9701-4720-b451-d3766b4aa2ff" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline. Mobile DC initialization method. Contains all necessary data to configure SDK.</p>

<p class="callout info">Should be called at very beginning of application lifecycle. For example in Android Application::onCreate method.</p>

<p class="callout info">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.</p>

<p class="callout info">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.</p>

<p class="callout info">**Note:** Please be aware to use this method before usage of any MobileDC methods or another Verestro product.</p>

</td></tr></tbody></table>

#### Input

Mobile DC different configuration options depending on SKD usage.

Configuration is provided by builder in facade method named *setup*.

All builder methods without *optional* keyword in method name are required.

**<span class="inline-comment-marker" data-ref="00efe6b4-e058-46e7-adab-5d29955fa882">Available configurations methods</span>:**

- setup(MobileDcCoreConfiguration)
- setup(MobileDcApiConfiguration)

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b1c7c216-5aa8-46a8-b76d-eed73ef0ad94" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-sdk-event-listeners-"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">**SDK Event Listeners - errors catching**</p>

<p class="callout info">The application should prevent throwing exceptions in MDC SDK Event Listeners described below as it could cause breaking process in SDK.</p>

<p class="callout info">In case of error in application event listener implementation SDK runs this code in try-catch block.</p>

</td></tr></tbody></table>

**MobileDcCoreConfiguration**

Used when usage of Verestro product doesn't require Verestro backend system (f.e. UCP with External Wallet Server).

<table class="relative-table wrapped confluenceTable" id="bkmrk-method-parameter-des" style="width: 100%; height: 244.2px;"><colgroup><col style="width: 34.9767%;"></col><col style="width: 24.5949%;"></col><col style="width: 21.1343%;"></col><col style="width: 19.2804%;"></col></colgroup><tbody><tr style="height: 60.6px;"><th class="confluenceTh" style="height: 60.6px;">**Method**</th><th class="confluenceTh" style="height: 60.6px;">**Parameter**</th><th class="confluenceTh" style="height: 60.6px;">**Description**</th><th class="confluenceTh" style="height: 60.6px;">**Validation conditions**

</th></tr><tr style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">withApplicationContext</td><td class="confluenceTd" style="height: 29.8px;">Context</td><td class="confluenceTd" style="height: 29.8px;">Application context</td><td class="confluenceTd" style="height: 29.8px;">Not empty</td></tr><tr style="height: 57.8px;"><td class="confluenceTd" style="height: 57.8px;">withWalletSecurityEventListener</td><td class="confluenceTd" style="height: 57.8px;">WalletSecurityEventListener

</td><td class="confluenceTd" style="height: 57.8px;">Global listener for security events

</td><td class="confluenceTd" style="height: 57.8px;">Not empty</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">withOptionalLogger</td><td class="confluenceTd" style="height: 46.6px;">EventsLogger</td><td class="confluenceTd" style="height: 46.6px;">Handler for secure logging of sdk events</td><td class="confluenceTd" style="height: 46.6px;">  
</td></tr><tr style="height: 49.4px;"><td class="confluenceTd" style="height: 49.4px;">withOptionalDeveloperOptions</td><td class="confluenceTd" style="height: 49.4px;">DeveloperOptions

</td><td class="confluenceTd" style="height: 49.4px;">Additional options for developers</td><td class="confluenceTd" style="height: 49.4px;">  
</td></tr><tr><td>withOptionalMobileDcTransactionEventListener</td><td>MobileDcTransactionEventListener

</td><td>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.</td><td>  
</td></tr></tbody></table>

**MobileDcApiConfiguration**

Used when applicaton use Mobile DC API for user data management.

<table class="relative-table wrapped confluenceTable" id="bkmrk-method-parameter-des-0" style="width: 100%;"><colgroup><col style="width: 27.9346%;"></col><col style="width: 24.2356%;"></col><col style="width: 32.4988%;"></col><col style="width: 15.4505%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Method**</th><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">withApplicationContext</td><td class="confluenceTd">Context</td><td class="confluenceTd">Application context</td><td class="confluenceTd">Not null</td></tr><tr><td class="confluenceTd">withMobileDcConnection  
Configuration

</td><td class="confluenceTd">MobileDcConnection  
Configuration

</td><td class="confluenceTd">Mobile DC API connection configuration delivered by Verestro

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">withWalletSecurityEventListener</td><td class="confluenceTd">WalletSecurityEventListener

</td><td class="confluenceTd">Global listener for security events

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">withOptionalWalletPin  
Configuration</td><td class="confluenceTd">MobileDcWalletPin  
Configuration</td><td class="confluenceTd">Wallet Pin configuration in SDK</td><td class="confluenceTd">  
</td></tr><tr><td class="confluenceTd">withOptionalLogger</td><td class="confluenceTd">EventsLogger</td><td class="confluenceTd">Handler for secure logging of sdk events</td><td class="confluenceTd">  
</td></tr><tr><td class="confluenceTd">withOptionalDeveloperOptions</td><td class="confluenceTd">DeveloperOptions</td><td class="confluenceTd">Additional options for developers</td><td class="confluenceTd">  
</td></tr><tr><td style="height: 35.4px;">withOptionalCloudMessaging  
Configuration  
</td><td style="height: 35.4px;">MobileDcCloudMessaging  
Configuration

</td><td style="height: 35.4px;">Interface for providing cloud messaging configuration like. For now used only for FCM registration token.  
</td><td>  
</td></tr></tbody></table>

**MobileDcConnectionConfiguration**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-0" style="width: 100%;"><colgroup><col style="width: 16.9345%;"></col><col style="width: 14.9609%;"></col><col style="width: 57.4743%;"></col><col style="width: 10.6304%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">url</td><td class="confluenceTd">String</td><td class="confluenceTd">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.

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">pinningCertificates</td><td class="confluenceTd">List&lt;String&gt;</td><td class="confluenceTd">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.

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">clientId</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Each customer has a unique client id it's different for development and production environment.

ClientId should be provided by Verestro representative.

</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**MobileDcWalletPinConfiguration**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-1" style="width: 75.679%;"><colgroup><col style="width: 18.3007%;"></col><col style="width: 11.5906%;"></col><col style="width: 44.4551%;"></col><col style="width: 25.6536%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">pinFailCount</td><td class="confluenceTd">Int</td><td class="confluenceTd">Number of possible fails in offline pin verification

</td><td class="confluenceTd">Greater then 0</td></tr></tbody></table>

**WalletSecurityEventListener**

<table class="relative-table wrapped confluenceTable" id="bkmrk-method-name-paramete" style="width: 100%;"><colgroup><col style="width: 22.3733%;"></col><col style="width: 26.8118%;"></col><col style="width: 50.8149%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Method** </th><th class="confluenceTh">**Parameters**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">onSecurityIssueAppeared</td><td class="confluenceTd">EventSecurityIssueAppeared  
(tag: Int, code: Int, message:String)

</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="cd5144a0-5bb7-4d9b-924c-0091f7ebae32">Information about security issue. Due to security requirements this message isn’t readable for user</span>

<span class="inline-comment-marker" data-ref="cd5144a0-5bb7-4d9b-924c-0091f7ebae32">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.</span>

<span class="inline-comment-marker" data-ref="cd5144a0-5bb7-4d9b-924c-0091f7ebae32">Some error codes could be properly handled in application [Security processes overview](https://wiki.verestro.com/display/UCP/Security+processes+overview)  
</span>

</td></tr></tbody></table>

**EventsLogger**

<table class="relative-table wrapped confluenceTable" id="bkmrk-method-name-paramete-0" style="width: 100%;"><colgroup><col style="width: 11.0012%;"></col><col style="width: 18.0425%;"></col><col style="width: 70.9562%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Method** </th><th class="confluenceTh">**Parameters**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">onEvent</td><td class="confluenceTd">onEvent(eventId:Int)</td><td class="confluenceTd">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.

</td></tr></tbody></table>

**DeveloperOptions**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-2" style="width: 100%; height: 343.2px;"><colgroup><col style="width: 27.4413%;"></col><col style="width: 10.7443%;"></col><col style="width: 61.8145%;"></col></colgroup><tbody><tr style="height: 35.4px;"><th class="confluenceTh" style="height: 35.4px;">**Parameter**</th><th class="confluenceTh" style="height: 35.4px;">**Type**</th><th class="confluenceTh" style="height: 35.4px;">**Description**

</th></tr><tr style="height: 102.6px;"><td class="confluenceTd" style="height: 102.6px;">allowDebug</td><td class="confluenceTd" style="height: 102.6px;">Boolean

</td><td class="confluenceTd" style="height: 102.6px;">Determine AndroidManifest *android:debuggable* state in *&lt;application&gt;* scope.

When configured as true SDK verifies combination of SDK production(without -debug) version and *android:debuggable*=true.

</td></tr><tr style="height: 147.4px;"><td class="confluenceTd" colspan="1" style="height: 147.4px;">enableAdditionalSecurityChecks</td><td class="confluenceTd" colspan="1" style="height: 147.4px;">Boolean</td><td class="confluenceTd" colspan="1" style="height: 147.4px;">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.

</td></tr><tr style="height: 57.8px;"><td class="confluenceTd" colspan="1" style="height: 57.8px;">enableCodeObfuscationCheck</td><td class="confluenceTd" colspan="1" style="height: 57.8px;">Boolean</td><td class="confluenceTd" colspan="1" style="height: 57.8px;">Enable additional check if application obfuscates SDK facade classes.

Default value is false.

</td></tr></tbody></table>

**MobileDcCloudMessagingConfiguration**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-3" style="width: 100%;"><colgroup><col style="width: 22.3733%;"></col><col style="width: 26.8118%;"></col><col style="width: 50.8149%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter** </th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">cloudMessaging  
RegistrationToken</td><td class="confluenceTd">CloudMessaging  
RegistrationProvider</td><td class="confluenceTd">Provides information about Cloud Messaging service.  
</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-method-parameters-de" style="width: 100%; height: 138px;"><colgroup><col style="width: 18.2942%;"></col><col style="width: 15.4454%;"></col><col style="width: 66.2604%;"></col></colgroup><tbody><tr style="height: 35.4px;"><th class="confluenceTh" style="height: 35.4px;">**Method** </th><th class="confluenceTh" style="height: 35.4px;">**Parameters**</th><th class="confluenceTh" style="height: 35.4px;">**Description**

</th></tr><tr style="height: 102.6px;"><td class="confluenceTd" style="height: 102.6px;">getRegistrationToken</td><td class="confluenceTd" style="height: 102.6px;">-</td><td class="confluenceTd" style="height: 102.6px;">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.

</td></tr></tbody></table>

**CloudMessagingRegistrationToken**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-4" style="width: 100%; height: 129.6px;"><colgroup><col style="width: 26.9478%;"></col><col style="width: 18.7877%;"></col><col style="width: 54.2645%;"></col></colgroup><tbody><tr style="height: 43.8px;"><th class="confluenceTh" style="height: 43.8px;">**Parameter**</th><th class="confluenceTh" style="height: 43.8px;">**Type**</th><th class="confluenceTh" style="height: 43.8px;">**Description**

</th></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">type</td><td class="confluenceTd" style="height: 54px;">CloudMessagingType

</td><td class="confluenceTd" style="height: 54px;">Mandatory. One of: \[FCM, HCM, EXTERNAL\].

FCM - Firebase Cloud Messaging

HCM - Huawei Cloud Messaging  
EXTERNAL - External token for external source of RNS

</td></tr><tr style="height: 31.8px;"><td class="confluenceTd" style="height: 31.8px;">token</td><td class="confluenceTd" style="height: 31.8px;">String</td><td class="confluenceTd" style="height: 31.8px;">Registaration token for push notifications  
</td></tr></tbody></table>

**MobileDcTransactionEventListener**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-5" style="width: 100%; height: 129.6px;"><colgroup><col style="width: 26.9478%;"></col><col style="width: 18.7877%;"></col><col style="width: 54.2645%;"></col></colgroup><tbody><tr style="height: 43.8px;"><th class="confluenceTh" style="height: 43.8px;">**Parameter**</th><th class="confluenceTh" style="height: 43.8px;">**Type**</th><th class="confluenceTh" style="height: 43.8px;">**Description**

</th></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">onNewTransaction</td><td class="confluenceTd" style="height: 54px;">EventNewTransaction

</td><td class="confluenceTd" style="height: 54px;">Plain EventNewTransaction object

</td></tr></tbody></table>

**EventNewTransaction**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-6" style="width: 100%; height: 129.6px;"><colgroup><col style="width: 26.9478%;"></col><col style="width: 18.7877%;"></col><col style="width: 54.2645%;"></col></colgroup><tbody><tr style="height: 43.8px;"><th class="confluenceTh" style="height: 43.8px;">**Parameter**</th><th class="confluenceTh" style="height: 43.8px;">**Type**</th><th class="confluenceTh" style="height: 43.8px;">**Description**

</th></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">newTransaction</td><td class="confluenceTd" style="height: 54px;">NewTransaction

</td><td class="confluenceTd" style="height: 54px;">Plain NewTransaction object

</td></tr></tbody></table>

**NewTransaction**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-7" style="width: 100%; height: 129.6px;"><colgroup><col style="width: 26.9478%;"></col><col style="width: 18.7877%;"></col><col style="width: 54.2645%;"></col></colgroup><tbody><tr style="height: 43.8px;"><th class="confluenceTh" style="height: 43.8px;">**Parameter**</th><th class="confluenceTh" style="height: 43.8px;">**Type**</th><th class="confluenceTh" style="height: 43.8px;">**Description**

</th></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">id</td><td class="confluenceTd" style="height: 54px;">Long

</td><td class="confluenceTd" style="height: 54px;">The internal transaction id

</td></tr><tr><td>clientTransactionId</td><td>String

</td><td>The client id of transaction

</td></tr><tr><td>type</td><td>String

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

</td></tr><tr><td>amountMinor</td><td>Long

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

</td></tr><tr><td>currency</td><td>String

</td><td>The transaction currency. 3-digit ISO 4217 currency code

</td></tr><tr><td>merchantName</td><td>String?

</td><td>The merchant name. Deprecated, please use contrahent.name field

</td></tr></tbody></table>

**Sample**

Mobile DC setup() method could be called on MainThread in Application:onCreate as blocking or another thread.  
When applicaiton has multiple dependencies there is possible to call setup() method on another thread.  
<span style="text-decoration: underline;">Important:</span> In case of loading SDK on another thread and then loading another Verestro module like VCP module - MobileDC:setup() must be already finished.

Initialization for **MobileDcCoreConfiguration** (without Wallet Server)

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="93697b07-c9eb-4286-a455-3e55a1b53d87" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-var-eventstrace-%3D-ar"><tbody><tr><td class="wysiwyg-macro-body">```
var eventsTrace = arrayListOf<Int>()//make use of this in case of error/failure/unexpected behaviour to retrace sdk internal processes


val mobileDcCoreConfiguration = MobileDcCoreConfiguration.create(
    MobileDcCoreConfigurationBuilder()
        .withApplicationContext(this)
        .withWalletSecurityEventListener(object : WalletSecurityEventListener {
            override fun onSecurityIssueAppeared(event: EventSecurityIssueAppeared) {
                //eg. show security screen or toast with details from event object
                //all data collected by SDK will be removed
                //Clearing application data in context of SDK is recommended
            }

        })
        .withOptionalLogger(object : EventsLogger {
            override fun onEvent(eventId: Int) {
                eventsTrace.add(eventId)
            }
        })
        .withOptionalDeveloperOptions(DeveloperOptions().apply {
            allowDebug = false
            enableAdditionalSecurityChecks = true
            enableCodeObfuscationCheck = true
        })
)

MobileDcApiKotlin.setup(mobileDcCoreConfiguration)
```

</td></tr></tbody></table>

Initialization for **MobileDcApiConfiguration**

```
class MyAppMobileDcConnectionConfig : MobileDcConnectionConfiguration {
    override val clientId: String = "clientId"
    override val url: String = "https://subdomain.domain.com/endpoint"
    override val pinningCertificates: List<String> = listOf(certificatePublicKeyInPemFormat)
}

class MyAppMobileDcWalletPinConfig : MobileDcWalletPinConfiguration {
    override val pinFailCount: Int = 3
}

var eventsTrace = arrayListOf<Int>()//make use of this in case of error/failure/unexpected behaviuour to retrace sdk internal processes

val mobileDcApiConfiguration = MobileDcApiConfiguration.create(
    MobileDcApiConfigurationBuilder()
        .withApplicationContext(this)
        .withMobileDcConnectionConfiguration(MyAppMobileDcConnectionConfig())
        .withOptionalWalletPinConfiguration(MyAppMobileDcWalletPinConfig())
        .withWalletSecurityEventListener(object : WalletSecurityEventListener {
            override fun onSecurityIssueAppeared(event: EventSecurityIssueAppeared) {
                //eg. show security screen or toast with details from event object
                //all data collected by SDK will be removed
                //Clearing application data in context of SDK is recommended
            }
        })
        .withOptionalLogger(object : EventsLogger {
            override fun onEvent(eventId: Int) {
                eventsTrace.add(eventId)
            }
        })
        .withOptionalDeveloperOptions(DeveloperOptions().apply {
            allowDebug = false
			enableAdditionalSecurityChecks = true
			enableCodeObfuscationCheck = true
        })
        .withOptionalCloudMessagingConfiguration(
            object : MobileDcCloudMessagingConfiguration {
                override val cloudMessagingRegistrationTokenProvider =
                      object : MobileDcCloudMessagingInfoProvider {
                          override fun getRegistrationToken(): CloudMessagingRegistrationToken? {
                              return CloudMessagingRegistrationToken(
									CloudMessagingType.FCM, 
									getFCMToken() //get current FCM token, FCM token for Verestr service shoud be checked by application and saved in storage to provide here in most fastest way of token delivery
						  )
        	          }
            }
        })
)

MobileDcApiKotlin.setup(mobileDcApiConfiguration)
```

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="b6fa2348-b956-497c-b0fa-b9678c614f90" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%C2%A0-10"><tbody><tr><td class="wysiwyg-macro-body">  
</td></tr></tbody></table>

Additional isolated process check, read more: **Application Isolated Process**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="a8501b77-c50e-49e2-b70e-9da0a93e51c0" data-macro-name="code" data-macro-parameters="language=java|theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-app-%3A-applicat"><tbody><tr><td class="wysiwyg-macro-body">```
class App : Application() {

    override fun onCreate() {
        super.onCreate()
        if (isIsolatedProcess()) {
			return
        }

		//call all required methods
    }

}
```

</td></tr></tbody></table>

## Address domain

### addAddress

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Adds new address with given parameters.</p>

</td></tr></tbody></table>

**Input**

**AddAddress**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-8"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th><th class="confluenceTh">Validation conditions</th></tr><tr><td class="confluenceTd">street</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Street

</td><td class="confluenceTd">-</td></tr><tr><td class="confluenceTd">number</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Number

</td><td class="confluenceTd">-</td></tr><tr><td class="confluenceTd">apartment</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Apartment

</td><td class="confluenceTd">-</td></tr><tr><td class="confluenceTd">city</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">City

</td><td class="confluenceTd">-</td></tr><tr><td class="confluenceTd" colspan="1">isBilling</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is invoice address

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">isShipping</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is Shipping address

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">zipCode</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Zip code

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">countryId</td><td class="confluenceTd" colspan="1">Int?</td><td class="confluenceTd" colspan="1">Country identifier

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">vatNo</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Vat number

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">companyName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Company name

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">firstName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">First name

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Last name

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">province</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Province

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">district</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">District

</td><td class="confluenceTd" colspan="1">-</td></tr><tr><td class="confluenceTd" colspan="1">additional</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">(Optional) Additional field

</td><td class="confluenceTd" colspan="1">-</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-with-long-va"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success with Long value as addressId / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-addadress%28addadd" style="width: 61.7284%;"><tbody><tr><td class="wysiwyg-macro-body" style="width: 100%;">```
fun addAdress(addAddress: AddAddress) {
    mobileDcApi
        .addressesService
        .addAddress(addAddress, { addressId ->
            // Address added
        }, {
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}
```

</td></tr></tbody></table>

### getAll

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Gets all addresses for the current user.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout success">Success callback with list of user <span class="inline-comment-marker" data-ref="7a827c0d-6b12-468f-a778-c7806b702992">addresses.</span></p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-9" style="width: 52.8395%;"><colgroup><col style="width: 24.7093%;"></col><col style="width: 31.9767%;"></col><col style="width: 43.314%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd"><span class="inline-comment-marker" data-ref="63f38489-2dc2-437a-8a17-0c5d92fdb57a">addresses</span></td><td class="confluenceTd">List &lt;Address&gt;</td><td class="confluenceTd">List of user addresses

</td></tr></tbody></table>

**Address**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-10" style="width: 52.4691%;"><colgroup><col style="width: 33.4337%;"></col><col style="width: 25.6024%;"></col><col style="width: 41.2651%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">id</td><td class="confluenceTd" colspan="1">Int</td><td class="confluenceTd" colspan="1">Id of the address</td></tr><tr><td class="confluenceTd">street</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="9820a2e5-c80f-4ca1-bd1c-340f846ade76">Street</span>

</td></tr><tr><td class="confluenceTd">number</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Number

</td></tr><tr><td class="confluenceTd">apartment</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Apartment

</td></tr><tr><td class="confluenceTd">city</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">City

</td></tr><tr><td class="confluenceTd" colspan="1">isBilling</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is invoice address

</td></tr><tr><td class="confluenceTd" colspan="1">isShipping</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is Shipping address

</td></tr><tr><td class="confluenceTd" colspan="1">zipCode</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Zip code

</td></tr><tr><td class="confluenceTd" colspan="1">country</td><td class="confluenceTd" colspan="1">Country?</td><td class="confluenceTd" colspan="1">Country

</td></tr><tr><td class="confluenceTd" colspan="1">vatNo</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Vat number

</td></tr><tr><td class="confluenceTd" colspan="1">companyName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Company name

</td></tr><tr><td class="confluenceTd" colspan="1">firstName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">First name

</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Last name

</td></tr><tr><td class="confluenceTd" colspan="1">province</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Province

</td></tr><tr><td class="confluenceTd" colspan="1">district</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">District

</td></tr><tr><td class="confluenceTd" colspan="1">additional</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Additional field

</td></tr></tbody></table>

**Country**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-11"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**

</th><th class="confluenceTh">**Type**

</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd" colspan="1">id

</td><td class="confluenceTd" colspan="1">Int

</td><td class="confluenceTd" colspan="1">Id of the country

</td></tr><tr><td class="confluenceTd">code

</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">Country code

</td></tr><tr><td class="confluenceTd">currency

</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">Currency code

</td></tr><tr><td class="confluenceTd">currencyNumeric

</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">Numeric currency code

</td></tr><tr><td class="confluenceTd">prefix

</td><td class="confluenceTd">CharArray?

</td><td class="confluenceTd">Prefix telephone number for a given country

</td></tr><tr><td class="confluenceTd" colspan="1">regexp

</td><td class="confluenceTd" colspan="1">CharArray?

</td><td class="confluenceTd" colspan="1">The phone number validation rule for a given country

</td></tr><tr><td class="confluenceTd" colspan="1">name

</td><td class="confluenceTd" colspan="1">CharArray?

</td><td class="confluenceTd" colspan="1">The currency's name

</td></tr><tr><td class="confluenceTd" colspan="1">currencyName

</td><td class="confluenceTd" colspan="1">CharArray?

</td><td class="confluenceTd" colspan="1">Country

</td></tr><tr><td class="confluenceTd" colspan="1">language

</td><td class="confluenceTd" colspan="1">CharArray?

</td><td class="confluenceTd" colspan="1">Official language

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-getall%28%29-%7B-mobil"><tbody><tr><td class="wysiwyg-macro-body">```
fun getAll() {
    mobileDcApi
        .addressesService
        .getAll({
            // List of addresses
        }, { throwable ->
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}
```

</td></tr></tbody></table>

### updateAddress

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Update address for the current id.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-12"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">updateAddress</td><td class="confluenceTd">UpdateAddress</td><td class="confluenceTd">An object containing address data to update

</td></tr></tbody></table>

**UpdateAddress**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-13" style="width: 57.4074%;"><colgroup><col style="width: 33.5859%;"></col><col style="width: 37.6263%;"></col><col style="width: 29.0404%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">addressId</td><td class="confluenceTd" colspan="1">Long</td><td class="confluenceTd" colspan="1">Id of the address</td></tr><tr><td class="confluenceTd" colspan="1">street</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Street</td></tr><tr><td class="confluenceTd" colspan="1">number</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Number</td></tr><tr><td class="confluenceTd" colspan="1">apartment</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Apartment</td></tr><tr><td class="confluenceTd" colspan="1">city</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">City</td></tr><tr><td class="confluenceTd" colspan="1">isBilling

</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is invoice address</td></tr><tr><td class="confluenceTd" colspan="1">isShipping</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Is shipping address</td></tr><tr><td class="confluenceTd" colspan="1">zipCode</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Zip code</td></tr><tr><td class="confluenceTd" colspan="1">countryId</td><td class="confluenceTd" colspan="1">Int?</td><td class="confluenceTd" colspan="1">Country identifier</td></tr><tr><td class="confluenceTd" colspan="1">vatNo</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Vat number</td></tr><tr><td class="confluenceTd" colspan="1">companyName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Company Name</td></tr><tr><td class="confluenceTd" colspan="1">firstName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">First name</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Last name</td></tr><tr><td class="confluenceTd" colspan="1">province</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Province</td></tr><tr><td class="confluenceTd" colspan="1">district</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">District</td></tr><tr><td class="confluenceTd" colspan="1">additionalField</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">Additional filed</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="66fa869c-ab3b-43ac-8c7e-aaa02ec5f4a2" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-private-fun-updatead"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### deleteAddress

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="fd52d643-70ee-4169-8ab1-22b3911b5e3f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-method-for-delete-us"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Method for delete user address with given address id.</p>

</td></tr></tbody></table>

**Input**

<table class="confluenceTable" id="bkmrk-parameter-type-descr-14" style="width: 46.4198%;"><colgroup><col style="width: 25.8359%;"></col><col style="width: 14.5897%;"></col><col style="width: 59.5745%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">addressId</td><td class="confluenceTd">Long</td><td class="confluenceTd">(Required) Unique address id</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="9a536f26-f2a1-4978-80b7-1f794147d74d" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6a77dcad-cb03-473a-a6b9-e3925d1b458f" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-deleteaddress%28ad"><tbody><tr><td class="wysiwyg-macro-body">```
fun deleteAddress(addressId: Long) {
    mobileDcApi
        .addressesService
        .deleteAddress(addressId, {
            //Success, address deleted
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter
        })
}
```

</td></tr></tbody></table>

###   


## User domain

### addUser

<p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Creates new user wallet account with given parameters.</p>

**Input**

NewUser model is required, but most of it's fields are optional. Fields requirement depends on product integration process.

<div class="table-wrap" id="bkmrk-parameter-type-descr-15"><table class="wrapped confluenceTable tablesorter tablesorter-default stickyTableHeaders" role="grid"><colgroup><col></col><col></col><col></col><col></col></colgroup><thead class="tableFloatingHeaderOriginal"><tr class="tablesorter-headerRow" role="row"><th aria-disabled="false" aria-label="Parameter: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="0" role="columnheader" scope="col" tabindex="0"><div class="tablesorter-header-inner">**Parameter**</div></th><th aria-disabled="false" aria-label="Type: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="1" role="columnheader" scope="col" tabindex="0"><div class="tablesorter-header-inner">**Type**</div></th><th aria-disabled="false" aria-label="Description: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="2" role="columnheader" scope="col" tabindex="0"><div class="tablesorter-header-inner">**Description**</div></th><th aria-disabled="false" aria-label="Validation coditions: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="3" role="columnheader" scope="col" tabindex="0"><div class="tablesorter-header-inner">**Validation coditions**</div></th></tr></thead><tbody aria-live="polite" aria-relevant="all"><tr role="row"><td class="confluenceTd">newUser</td><td class="confluenceTd">NewUser</td><td class="confluenceTd"><span class="tlid-translation translation" lang="en">An object containing user data</span></td><td class="confluenceTd">(Required)</td></tr></tbody></table>

</div>NewUser object contains following fields:

<div class="table-wrap" id="bkmrk-parameter-type-descr-16"><table class="relative-table confluenceTable tablesorter tablesorter-default stickyTableHeaders" role="grid" style="border-collapse: collapse; width: 100%; border-style: dashed; height: 641.2px;"><colgroup><col style="width: 19.3087%;"></col><col style="width: 10.9654%;"></col><col style="width: 23.8379%;"></col><col style="width: 45.888%;"></col></colgroup><thead><tr class="tablesorter-headerRow" role="row" style="height: 38.2px;"><td aria-disabled="false" aria-label="Parameter: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="0" role="columnheader" style="height: 38.2px;" tabindex="0"><div class="tablesorter-header-inner">**Parameter**</div></td><td aria-disabled="false" aria-label="Type: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="1" role="columnheader" style="height: 38.2px;" tabindex="0"><div class="tablesorter-header-inner">**Type**</div></td><td aria-disabled="false" aria-label="Description: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="2" role="columnheader" style="height: 38.2px;" tabindex="0"><div class="tablesorter-header-inner">**Description**</div></td><td aria-disabled="false" aria-label="Validation conditions: No sort applied, activate to apply an ascending sort" aria-sort="none" class="confluenceTh tablesorter-header sortableHeader tablesorter-headerUnSorted" data-column="3" role="columnheader" style="height: 38.2px;" tabindex="0">**Validation conditions**

</td></tr></thead><tbody aria-live="polite" aria-relevant="all"><tr role="row" style="height: 38.2px;"><td class="confluenceTd" style="height: 38.2px;">phone</td><td class="confluenceTd" style="height: 38.2px;">CharArray?</td><td class="confluenceTd" style="height: 38.2px;">User's phone number

</td><td class="confluenceTd" style="height: 38.2px;">Phone with country prefix. For pl: 48500500500</td></tr><tr role="row" style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">email</td><td class="confluenceTd" style="height: 29.8px;">CharArray?</td><td class="confluenceTd" style="height: 29.8px;">User's email address</td><td class="confluenceTd" style="height: 29.8px;">Email format if any value passed</td></tr><tr role="row" style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">firstName</td><td class="confluenceTd" style="height: 29.8px;">CharArray?</td><td class="confluenceTd" style="height: 29.8px;">User's first name</td><td class="confluenceTd" style="height: 29.8px;">  
</td></tr><tr role="row" style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">lastName</td><td class="confluenceTd" style="height: 29.8px;">CharArray?</td><td class="confluenceTd" style="height: 29.8px;">User's last name</td><td class="confluenceTd" style="height: 29.8px;">  
</td></tr><tr role="row" style="height: 29.8px;"><td class="confluenceTd" style="height: 29.8px;">walletPin</td><td class="confluenceTd" style="height: 29.8px;">CharArray?</td><td class="confluenceTd" style="height: 29.8px;">User's wallet pin</td><td class="confluenceTd" style="height: 29.8px;">4 to 8 digits if passed  
</td></tr><tr role="row" style="height: 80.2px;"><td class="confluenceTd" style="height: 80.2px;">password</td><td class="confluenceTd" style="height: 80.2px;">CharArray?</td><td class="confluenceTd" style="height: 80.2px;">User's password</td><td class="confluenceTd" style="height: 80.2px;">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</td></tr><tr role="row" style="height: 69px;"><td class="confluenceTd" style="height: 69px;">accepted  
Marketing</td><td class="confluenceTd" style="height: 69px;">Boolean</td><td class="confluenceTd" style="height: 69px;">True if user accepted marketing agreement, false otherwise</td><td class="confluenceTd" style="height: 69px;">-

</td></tr><tr role="row" style="height: 63.4px;"><td class="confluenceTd" style="height: 63.4px;">invitationCode</td><td class="confluenceTd" style="height: 63.4px;">CharArray?</td><td class="confluenceTd" style="height: 63.4px;">Invitation code <span class="tlid-translation translation" lang="en">used in a specific server configuration</span></td><td class="confluenceTd" style="height: 63.4px;">(Conditional/Optional) - depends on specific server configuration</td></tr><tr role="row" style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">nip</td><td class="confluenceTd" style="height: 46.6px;">String?</td><td class="confluenceTd" style="height: 46.6px;">Taxpayer identification number</td><td class="confluenceTd" style="height: 46.6px;">Not empty if passed</td></tr><tr style="height: 63.4px;"><td style="height: 63.4px;">accepted  
Regulations</td><td style="height: 63.4px;">Boolean?  
</td><td style="height: 63.4px;">Information if user has accepted regulations agreement</td><td style="height: 63.4px;">  
</td></tr><tr style="height: 63.4px;"><td style="height: 63.4px;">acceptedMarketing  
Receiving  
</td><td style="height: 63.4px;">Boolean?  
</td><td style="height: 63.4px;">Information if user has accepted marketing consent</td><td style="height: 63.4px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">preferredLanguage</td><td style="height: 29.8px;">CharArray?</td><td style="height: 29.8px;">Preferred language</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">nationality</td><td style="height: 29.8px;">CharArray?</td><td style="height: 29.8px;">Nationality</td><td style="height: 29.8px;">Must be format: ISO-3166 alpha-2 code, two uppercase letters (PL, US, GB)</td></tr><tr><td>birthDate</td><td>CharArray?</td><td>Birth date</td><td>Must be format: yyyy-MM-dd and date must be today or in the past (1970-01-01)</td></tr><tr><td>walletId</td><td>CharArray?</td><td>Wallet id</td><td>  
</td></tr></tbody></table>

</div>**Output**

<p class="callout info">Success / failure callback.</p>

**Sample**

<div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-fun-adduser%28newuser%3A"><div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code"><div class="codeContent panelContent pdl"><div class="syntaxhighlighter sh-eclipse nogutter  java" id="bkmrk-fun-adduser%28newuser%3A-0"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div class="container" title="Hint: double-click to select code"><div class="line number1 index0 alt2">`fun addUser(newUser: NewUser) {`</div><div class="line number2 index1 alt1">`    ``mobileDcApi`</div><div class="line number3 index2 alt2">`        ``.userService`</div><div class="line number4 index3 alt1">`        ``.addUser(newUser, {`</div><div class="line number5 index4 alt2">`            ``//new user is added successfully`</div><div class="line number6 index5 alt1">`        ``}, { throwable ->`</div><div class="line number7 index6 alt2">`            ``// Something went wrong, maybe user data was incorrect`</div><div class="line number8 index7 alt1">`            ``// Check exceptions described in Error handling chapter`</div><div class="line number9 index8 alt2">`        ``})`</div><div class="line number10 index9 alt1">`}`</div></div></td></tr></tbody></table>

</div></div></div></div>### addUser (deprecated)

<div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-asynchronous.-online-3"><div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code"><div class="codeContent panelContent pdl"><table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Creates new user wallet account with given parameters.</p>

</td></tr></tbody></table>

</div></div></div>**Input**

Most of fields are optional. Fields requirement depends on product integration process.

<div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-parameter-type-descr-17"><div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code"><div class="codeContent panelContent pdl"><table class="relative-table wrapped confluenceTable" style="width: 100%;"><colgroup><col style="width: 19.6539%;"></col><col style="width: 14.8331%;"></col><col style="width: 19.394%;"></col><col style="width: 46.119%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">phone</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">User's phone number

</td><td class="confluenceTd">Phone with country prefix. For pl: 48500500500</td></tr><tr><td class="confluenceTd" colspan="1">email</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's email address</td><td class="confluenceTd" colspan="1">Email format if any value passed</td></tr><tr><td class="confluenceTd" colspan="1">firstName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's first name</td><td class="confluenceTd" colspan="1">  
</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's last name</td><td class="confluenceTd" colspan="1">  
</td></tr><tr><td class="confluenceTd" colspan="1">walletPin</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's wallet pin</td><td class="confluenceTd" colspan="1">4 to 8 digits if passed  
</td></tr><tr><td class="confluenceTd" colspan="1">password</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's password</td><td class="confluenceTd" colspan="1">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</td></tr><tr><td class="confluenceTd" colspan="1">acceptedMarketing</td><td class="confluenceTd" colspan="1">Boolean</td><td class="confluenceTd" colspan="1">True if user accepted marketing agreement, false otherwise</td><td class="confluenceTd" colspan="1">-

</td></tr></tbody></table>

</div></div></div>**Output**

<div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code" id="bkmrk-success-%2F-failure-ca-1"><div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-name="code"><div class="codeContent panelContent pdl"><table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

</div></div></div>### addUserWithIban

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="2844aba3-955a-4a44-a160-08ab8c140435" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Creates new user wallet account if not exist with IBAN in Mobile DC backend.</p>

<p class="callout info">When user already exist calling this method will be also finished with success.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-18" style="width: 100%; height: 160.391px;"><colgroup><col style="width: 17.5525%;"></col><col style="width: 11.4865%;"></col><col style="width: 53.1612%;"></col><col style="width: 17.7998%;"></col></colgroup><tbody><tr style="height: 57.7969px;"><th class="confluenceTh" style="height: 57.7969px;">**Parameter**</th><th class="confluenceTh" style="height: 57.7969px;">**Type**</th><th class="confluenceTh" style="height: 57.7969px;">**Description**</th><th class="confluenceTh" style="height: 57.7969px;">**Validation conditions**

</th></tr><tr style="height: 102.594px;"><td class="confluenceTd" style="height: 102.594px;">signedAccountInfo</td><td class="confluenceTd" style="height: 102.594px;">String</td><td class="confluenceTd" style="height: 102.594px;">Signed AccountInfo per RFC 7519 generated on Client server side

Instruction how to sign data with JWT can be found in [*<span class="inline-comment-marker" data-ref="fcc560bb-e660-475f-b79d-b14d39dfd6a5">Data signing and encryption</span>*](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation-mdc-sdk#bkmrk-data-signing-and-enc) chapter

</td><td class="confluenceTd" style="height: 102.594px;">Not empty</td></tr></tbody></table>

**AccountInfo**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-19" style="width: 100.247%;"><colgroup><col style="width: 12.8514%;"></col><col style="width: 7.09505%;"></col><col style="width: 60.5087%;"></col><col style="width: 19.5448%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">userId</td><td class="confluenceTd">String</td><td class="confluenceTd">External user id given by the client

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">iban</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Bank Account Number</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">countryCode</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">The country of the financial account

Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1

</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback.-ca"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback. Called when new user is created or already exist with passed input data.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-20"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">ibanId</td><td class="confluenceTd">String</td><td class="confluenceTd">Hash (sha256) of provided IBAN

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6165e6d0-8a81-4de4-b672-2f622b7c6282" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="1a4477e8-d027-48c9-a04b-c58b22986fec">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="7ac25542-1b63-4862-8c18-36b532d0bff9" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-class-signedaccounti"><tbody><tr><td class="wysiwyg-macro-body">```
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)
        // ...
    }
}
```

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="bcc44fb5-ac88-483f-bc03-7a4c8159f59d" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-private-fun-adduserw"><tbody><tr><td class="wysiwyg-macro-body">```
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?
        })
}
```

</td></tr></tbody></table>

### updateUser

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Update user wallet account with given parameters.</p>

<p class="callout info">Most of it's fields are optional. Fields requirement depends on product integration process.  
</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-21"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation coditions**</th></tr><tr><td class="confluenceTd">updateUser</td><td class="confluenceTd">UpdateUser</td><td class="confluenceTd"><span class="tlid-translation translation" lang="en">An object containing user data to update</span></td><td class="confluenceTd">(Required)</td></tr></tbody></table>

**UpdateUser**

<table class="relative-table confluenceTable wrapped" id="bkmrk-parameter-type-descr-22"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">firstName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's first name</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray?</td><td class="confluenceTd" colspan="1">User's last name</td></tr><tr><td class="confluenceTd" colspan="1">acceptedMarketing</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">True if user accepted marketing agreement, false otherwise</td></tr><tr><td class="confluenceTd" colspan="1">acceptedRegulations</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Accepted regulations agreement</td></tr><tr><td class="confluenceTd" colspan="1">acceptedMarketingReceiving</td><td class="confluenceTd" colspan="1">Boolean?</td><td class="confluenceTd" colspan="1">Accepted marketing consent</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-2"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-updateuser%28updat"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### getUser

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="62ccd748-1dd8-490f-825e-9fb87ed4cb5f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-6"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Get data of current user.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info"><span class="inline-comment-marker" data-ref="676ca14c-1f64-49ef-b7ef-e07a9bd6931a">Success callback with User model.</span></p>

</td></tr></tbody></table>

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-23"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">user</td><td class="confluenceTd">User</td><td class="confluenceTd">User data

</td></tr></tbody></table>

User contains following fields:

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-24" style="width: 100%;"><colgroup><col style="width: 23.115%;"></col><col style="width: 12.6027%;"></col><col style="width: 64.2824%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd"><span class="inline-comment-marker" data-ref="c258fa37-23ef-46a1-a19f-018bfdc3cf36">userId</span></td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of registered user

</td></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">First name of the user (required depending on server configuration)</td></tr><tr><td class="confluenceTd">lastName</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Last name of the user (required depending on server configuration)</td></tr><tr><td class="confluenceTd">phone</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Phone with country prefix. For pl: 48500500500 (required depending on server configuration)</td></tr><tr><td class="confluenceTd">email</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Email of the user (required depending on server configuration)

</td></tr><tr><td class="confluenceTd">birthDate</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Birth date in format yyyy-MM-dd

</td></tr><tr><td class="confluenceTd">gender</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Gender: \[M, F\]</td></tr><tr><td class="confluenceTd">acceptTos</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Date when user accepted regulations in format yyyy-MM-dd hh:mm:ss</td></tr><tr><td class="confluenceTd">acceptMarketing</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Date when user accepted marketing info in format yyyy-MM-dd hh:mm:ss</td></tr><tr><td class="confluenceTd">isLocked</td><td class="confluenceTd">Boolean?</td><td class="confluenceTd">True if user is locked, false otherwise</td></tr><tr><td class="confluenceTd">deactivated</td><td class="confluenceTd">Boolean?</td><td class="confluenceTd">True if user is deactivated, false otherwise</td></tr><tr><td class="confluenceTd">status</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">User status: \[ACTIVE, LOCKED, DEACTIVATED\]</td></tr><tr><td class="confluenceTd">verified</td><td class="confluenceTd">Boolean?</td><td class="confluenceTd">True if user is verified, false otherwise</td></tr><tr><td class="confluenceTd">kyc</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">User’s KYC verification status, one of: \[SUCCESS, REJECTED, IN\_PROGRESS\]</td></tr><tr><td>kycRejectReason</td><td>List&lt;String&gt;?</td><td>User’s KYC list of rejection reasons

</td></tr><tr><td class="confluenceTd">created</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Date of creation user in DB</td></tr><tr><td class="confluenceTd">failCount</td><td class="confluenceTd">Int?</td><td class="confluenceTd">Number of failed authentication attempts</td></tr><tr><td class="confluenceTd">hasSetPassword</td><td class="confluenceTd">Boolean?</td><td class="confluenceTd">True if user has password set, false otherwise</td></tr><tr><td class="confluenceTd">lastPasswordChange</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Last password change in format yyyy-MM-dd</td></tr><tr><td class="confluenceTd">lockTo</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Time for which user is locked in format Y-m-d H:i:s</td></tr><tr><td class="confluenceTd">lastActivity</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Data of user last activity in format yyyy-MM-dd hh:mm:ss</td></tr><tr><td class="confluenceTd">country</td><td class="confluenceTd">Country</td><td class="confluenceTd">Country object</td></tr><tr><td class="confluenceTd">acceptMarketingReceiving</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Date when user accepted marketing consent in format yyyy-MM-dd hh:mm:ss</td></tr><tr><td>preferredLanguage</td><td>CharArray?</td><td>Preferred language</td></tr><tr><td>nationality</td><td>CharArray?</td><td>Nationality. Must be format: ISO-3166 alpha-2 cod (PL, US, GB)</td></tr><tr><td>walletId</td><td>CharArray?</td><td>Wallet id</td></tr></tbody></table>

Country contains following fields.

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti" style="width: 70.6173%;"><colgroup><col style="width: 10.099%;"></col><col style="width: 20.5941%;"></col><col style="width: 69.3069%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">id</td><td class="confluenceTd">Long</td><td class="confluenceTd">Country identifier

</td></tr><tr><td class="confluenceTd" colspan="1">code</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Country code in accordance with the ISO 3166-2 standard</td></tr><tr><td class="confluenceTd" colspan="1">prefix</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Prefix telephone number for a given country</td></tr><tr><td class="confluenceTd" colspan="1">name</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="85e7b956-dc5d-49e5-abd1-b6f435d85a71">Country name</span>

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0d22d5a0-2696-456f-9197-316a059eb4c3" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="834a2333-be7d-42a3-a162-f5991680f7db">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="624723bc-c8d5-40cb-b571-7983b758cc02" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-getuser%28%29-%7B-mobi"><tbody><tr><td class="wysiwyg-macro-body">```
fun getUser() {
    mobileDcApi.userService
        .getUser({ user ->
            // Getting user went successfully
			showUser(user)
        }, { throwable ->
            // Something went wrong
            // Check exceptions described in error handling chapter
        })
}
```

</td></tr></tbody></table>

### finalizeUserRegistration

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-7"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Activate user account by finalizing registration process with SMS code sent to the phone number provided during new user wallet account creation.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-25" style="width: 100%;"><colgroup><col style="width: 11.6193%;"></col><col style="width: 10.1346%;"></col><col style="width: 61.188%;"></col><col style="width: 17.0581%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd" colspan="1">otp</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">One time password (sent via SMS as a result of successful new user wallet account creation)</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-finalizeuserregi"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### authenticateByPin

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Authenticates user locally after providing correct pin.</p>

<p class="callout info">Provide method to verify user without connection into Mobile DC.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-26" style="width: 100%;"><colgroup><col style="width: 12.6082%;"></col><col style="width: 13.4676%;"></col><col style="width: 58.473%;"></col><col style="width: 15.4512%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd"><span class="inline-comment-marker" data-ref="ae79c10f-7e9c-4c28-9710-811b89553266">pin</span></td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Wallet Pin created during user registration process associated with user account. (see: [addUser (deprecated)](https://wiki.verestro.com/pages/viewpage.action?pageId=67340747))

</td><td class="confluenceTd">Not empty.</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="5cdf5835-d768-4d5d-ab72-66ad22ecf864" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="74a94987-8a53-4a43-a21c-8ec9b131a77e">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-authenticatebypi"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### isBiometricAuthenticationEnabled

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="3a308729-1dd5-4a2e-8aca-75664529673a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Method that check if biometric authentication is enabled.</p>

<p class="callout info">**Note:** Authentication could be disabled by system when Android Keystore state changed (eg. User disabled screen lock or add new authentication method).</p>

<p class="callout info">State of biometrics should be checked before every biometrics authentication usage.</p>

</td></tr></tbody></table>

**Input**

No input parameters

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="8273ee62-8345-488e-afa0-24b8c55ae11f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with status of authentication or failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="5c25e7cd-70b8-4aab-9ead-d5c7642a8e95">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="1fd5ed54-717c-43d7-823f-64029be325d3" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-fun-isbiometricauthe"><tbody><tr><td class="wysiwyg-macro-body">```
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
            })
}
```

</td></tr></tbody></table>

### enableBiometricAuthentication

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="36fa2435-c943-49d1-be5e-e1a7091861a4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-8"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Method for enabling device level authentication and updating biometric public key.</p>

<p class="callout info">To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-27" style="width: 100%;"><colgroup><col style="width: 19.2793%;"></col><col style="width: 32.1423%;"></col><col style="width: 32.6329%;"></col><col style="width: 15.9456%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh" colspan="1">**Description**</th><th class="confluenceTh" colspan="1">**Validation conditions**</th></tr><tr><td class="confluenceTd">userName</td><td class="confluenceTd">CharArray</td><td class="confluenceTd" colspan="1">Current username</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd">password</td><td class="confluenceTd">CharArray</td><td class="confluenceTd" colspan="1">Current password</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">biometricAuthType</td><td class="confluenceTd" colspan="1">BiometricAuthType (BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE)</td><td class="confluenceTd" colspan="1">Type of biometrics to enable during device pairing process.</td><td class="confluenceTd" colspan="1">Not null</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="7c625c53-6d1f-4bad-b332-b76ee3d08318" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
//KeyguardManager example
keyguardManager = context.getSystemService(KEYGUARD_SERVICE)

fun isDeviceSecure(): Boolean {
    return keyguardManager.isKeyguardSecure
}
//if isDeviceSecure return true device is safe and enableBiometricAuthentication method can be performed

fun enableBiometricAuthentication(userName: CharArray, password: CharArray, biometricAuthType : BiometricAuthType) {
    mobileDcApi.userService
        		.enableBiometricAuthentication(userName, password, biometricAuthType,
					{
            			// Biometric authentication is enabled. Read startBiometricAuthentication description to authenticate user.
        			},
 					{ throwable ->
            			// Something went wrong
            			// Check exceptions described in Error handling chapter
        			}
				)
}
```

### disableBiometricAuthentication

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-2"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Disable possibility to use biometric authentication.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-2"><tbody><tr><td class="wysiwyg-macro-body">No input parameters.

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-6"><tbody><tr><td class="wysiwyg-macro-body">Success / failure callback.

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-disablebiometric"><tbody><tr><td class="wysiwyg-macro-body">```
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            
        })
}
```

</td></tr></tbody></table>

### enableBiometricAuthenticationWithWalletPin

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="36fa2435-c943-49d1-be5e-e1a7091861a4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-9"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Method for enabling device level authentication and updating biometric public key with Wallet Pin.</p>

<p class="callout info">To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable wrapped" id="bkmrk-parameter-type-descr-28" style="width: 100%;"><colgroup><col style="width: 17.7953%;"></col><col style="width: 33.6262%;"></col><col style="width: 32.6329%;"></col><col style="width: 15.9456%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh" colspan="1">**Description**</th><th class="confluenceTh" colspan="1">**Validation conditions**</th></tr><tr><td class="confluenceTd">walletPin</td><td class="confluenceTd">CharArray</td><td class="confluenceTd" colspan="1">Current walletPin</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">biometricAuthType</td><td class="confluenceTd" colspan="1">BiometricAuthType (BIOMETRIC\_ONLY, BIOMETRIC\_WITH\_ALTERNATIVE)</td><td class="confluenceTd" colspan="1">Type of biometrics to enable during device pairing process.</td><td class="confluenceTd" colspan="1">Not null</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="7c625c53-6d1f-4bad-b332-b76ee3d08318" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-7"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="418fa22f-892f-4370-88ac-4510cb8fd22b" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-%2F%2Fkeyguardmanager-ex-0"><tbody><tr><td class="wysiwyg-macro-body">```
//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
        			}
				)
}
```

</td></tr></tbody></table>

### startBiometricAuthentication

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="e6f53b54-8abb-4a1d-b90f-eadd82dc4836" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Create CryptoObject for biometric authentication.</p>

<p class="callout info">Depends on usage of androidx/android support library an different CryptoObject can be provided by Android SDK.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-29" style="width: 100%;"><colgroup><col style="width: 15.9456%;"></col><col style="width: 20.1402%;"></col><col style="width: 48.463%;"></col><col style="width: 15.4512%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">cryptoObjectType</td><td class="confluenceTd">CryptoObjectType</td><td class="confluenceTd">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

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="84f21610-8bb6-4ffd-9609-ea0ef2b54549" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout success">Success callback.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-30"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">result</td><td class="confluenceTd">BiometricAuthenticationData

</td><td class="confluenceTd">Object containing CryptoObject kept as Object. </td></tr></tbody></table>

BiometricAuthenticationData contains following field:

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-31"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cryptoObject</td><td class="confluenceTd">Object</td><td class="confluenceTd">Wrapper class for crypto objects supported biometric authentication.</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b9e08504-b114-488f-905f-022b53b8571b" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout warning">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

startBiometricAuthentication sample:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="fa26fc15-0037-4bc0-beb9-dbd408619a45" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-mobiledcapi-.userser"><tbody><tr><td class="wysiwyg-macro-body">```
  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 
            }
```

</td></tr></tbody></table>

BiometricAuthenticationData should be used as parameter in [authenticateWithBiometric](https://wiki.verestro.com/display/UCP/authenticateWithBiometric) but application must cast cryptoObject parameter to CryptoObject.

Cast to CryptoObject sample :

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="47cac0d9-b60f-44f9-aa74-872a37e9d28d" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-wraptobiometrica"><tbody><tr><td class="wysiwyg-macro-body">```
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
	)
}
```

</td></tr></tbody></table>

Complete flow of authentication with biometric methods:

Create your own custom view, which require to authenticate with biometric.

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="941e68e7-e349-4b62-b091-a039662f36c4" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-customviewforbiometr"><tbody><tr><td class="wysiwyg-macro-body">```
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()
        }
    })
```

</td></tr></tbody></table>

### authenticateWithBiometric

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="e6f53b54-8abb-4a1d-b90f-eadd82dc4836" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Starts system biometric authentication.</p>

<p class="callout info">After invoke system waits for a biometric authentication.</p>

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b81b967a-f154-43e4-b72d-e67037af6b16" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-method-can-throw-bio"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout warning">Method can throw BiometricVerificationException.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-32" style="width: 106.049%;"><colgroup><col style="width: 25.2153%;"></col><col style="width: 24.9681%;"></col><col style="width: 34.7328%;"></col><col style="width: 15.2033%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">biometricAuthenticationResult</td><td class="confluenceTd">BiometricAuthenticationResult</td><td class="confluenceTd">Class wrapper for biometric authentication result (Signature, Cipher, Mac) created in startBiometricAuthentication

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="1f81ae82-9572-48b4-97f6-cb34a8724351" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout success">Success callback.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-33"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">result</td><td class="confluenceTd">AuthorizationResult</td><td class="confluenceTd">Object containing verification details. </td></tr></tbody></table>

AuthorizationResult contains following fields:

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-34"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th></tr><tr><td class="confluenceTd">timestamp</td><td class="confluenceTd">Long?</td><td class="confluenceTd">Internal information for SDK.</td></tr><tr><td class="confluenceTd">signedTimestamp</td><td class="confluenceTd">ByteArray?</td><td class="confluenceTd">Internal information for SDK</td></tr><tr><td class="confluenceTd">errorMessage</td><td class="confluenceTd">String?</td><td class="confluenceTd">Internal information for SDK</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="cab0dcf7-a1fc-4f49-b110-625130adb69a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback."><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.  
</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="fa26fc15-0037-4bc0-beb9-dbd408619a45" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-authenticatewith"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### loginByTrustedIdentity

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-10"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Authenticates user in Mobile DC backend after providing trusted identity.</p>

<p class="callout info">Creates / refreshes user session.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-35"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th><th class="confluenceTh">Validation conditions

</th></tr><tr><td class="confluenceTd">trustedIdentity</td><td class="confluenceTd">String</td><td class="confluenceTd">Trusted identity generated by client

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**TrustedIdentity**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-36"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh" colspan="1">Parameter</th><th class="confluenceTh" colspan="1">Type</th><th class="confluenceTh" colspan="1">Description</th><th class="confluenceTh" colspan="1">Validation conditions

</th></tr><tr><td class="confluenceTd">userId</td><td class="confluenceTd">String</td><td class="confluenceTd">External user id given by the client

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="5cdf5835-d768-4d5d-ab72-66ad22ecf864" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-8"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="74a94987-8a53-4a43-a21c-8ec9b131a77e">Sample</span>**

<span class="inline-comment-marker" data-ref="74a94987-8a53-4a43-a21c-8ec9b131a77e">Sample code for *trustedIdentity* generation (see also *Data signing and encryption* chapter):</span>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-trustedidentit"><tbody><tr><td class="wysiwyg-macro-body">```
class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}
```

</td></tr></tbody></table>

<span class="inline-comment-marker" data-ref="74a94987-8a53-4a43-a21c-8ec9b131a77e">Usage of trustedIdentity in application:</span>

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="e7cf8263-8c60-44e0-a8c1-8921372f7cfc" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-loginbytrustedid"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### loginByPin

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-11"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Authenticates user in Mobile DC backend after providing correct pin.</p>

<p class="callout info">Creates / refreshes user session.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-37" style="width: 100%;"><colgroup><col style="width: 12.2373%;"></col><col style="width: 11.8635%;"></col><col style="width: 58.0995%;"></col><col style="width: 17.7998%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd"><span class="inline-comment-marker" data-ref="2d0c88d6-1037-41b9-b59d-d159223c6eb9">pin</span></td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Wallet Pin created during user registration process associated with user account. (see: [addUser](https://wiki.upaid.pl/display/UCP/addUser))

</td><td class="confluenceTd">Not empty.</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="5cdf5835-d768-4d5d-ab72-66ad22ecf864" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-9"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="74a94987-8a53-4a43-a21c-8ec9b131a77e">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-loginbypin%28mobil"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### loginBySignature

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="044d24ab-6cbb-41db-b624-c8856b7fb6f9" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-12"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Authenticates user in Mobile DC backend after local biometric authentication (startBiometricAuthentication and authenticateWithBiometric methods).</p>

<p class="callout info">Creates / refreshes user session.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0bb800ad-adb2-4280-9c77-efbb8101ae98" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-authorizationresult--0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 14px;"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">**AuthorizationResult** provided in success callback from authenticateWithBiometric method.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="db497e45-0229-45bc-b073-a4cb0941b276" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-10"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="8e6ff1e0-73c7-4ba1-aac4-2d3f0b1f9511" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-fun-loginbysignature"><tbody><tr><td class="wysiwyg-macro-body">```
fun loginBySignature(authorizationResult: AuthorizationResult) {
    mobileDcApi
            .userService
            .loginBySignature(authorizationResult, {
                // User is authenticated
            }, { throwable ->
                // Something went wrong
                // Check exceptions
            })
}
```

</td></tr></tbody></table>

### changeWalletPin

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="cf6d5185-0632-4dff-9ffe-11cb909aa71d" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-13"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Changes user's wallet PIN with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-38"><colgroup><col></col><col></col><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Parameter**

</th><th class="confluenceTh">**Type**

</th><th class="confluenceTh">**Description**

</th><th class="confluenceTh">**Validation conditions**

</th></tr></thead><tbody><tr><td class="confluenceTd">walletPin</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Current wallet PIN.

</td><td class="confluenceTd">Has 4 or 8 digits.</td></tr><tr><td class="confluenceTd" colspan="1">newWalletPin</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">New wallet PIN.</td><td class="confluenceTd" colspan="1">Has 4 or 8 digits.</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="562c1282-1c79-4861-9368-60a3b0a8c487" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-11"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-changewalletpin%28"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### resetWalletPin

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-14"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Resets wallet pin with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-39" style="width: 100%;"><colgroup><col style="width: 14.0915%;"></col><col style="width: 10.8763%;"></col><col style="width: 24.5996%;"></col><col style="width: 50.4326%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd" colspan="1">userLoginType

</td><td class="confluenceTd" colspan="1">UserType</td><td class="confluenceTd" colspan="1">User identifier type. One of: \[PHONE, EMAIL\]

</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">userLogin</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">User identifier. Depends on user identifier type (EMAIL or PHONE)</td><td class="confluenceTd" colspan="1">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</td></tr><tr><td class="confluenceTd" colspan="1">newWalletPin</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">New user wallet pin</td><td class="confluenceTd" colspan="1">Only numbers with 4 to 8 digits</td></tr><tr><td class="confluenceTd">password</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Current user password

</td><td class="confluenceTd">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</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-12"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-resetwalletpin%28u"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### changePassword

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-15"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Changes user's password with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-40" style="width: 100%;"><colgroup><col style="width: 12.9776%;"></col><col style="width: 9.89013%;"></col><col style="width: 11.8665%;"></col><col style="width: 65.2658%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">password</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Current user password

</td><td class="confluenceTd">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  
</td></tr><tr><td class="confluenceTd" colspan="1">newPassword</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">New user password</td><td class="confluenceTd" colspan="1">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</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-13"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-changepassword%28p"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### initializeResetUserPassword (deprecated)

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-16"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Reset user's password with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-41" style="width: 100%;"><colgroup><col style="width: 12.1135%;"></col><col style="width: 10.3812%;"></col><col style="width: 36.2186%;"></col><col style="width: 41.4083%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">userLoginType</td><td class="confluenceTd">UserType</td><td class="confluenceTd"> User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]

</td><td class="confluenceTd"> Not empty</td></tr><tr><td class="confluenceTd" colspan="1">userLogin</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">User identifier. Depends on user identifier type</td><td class="confluenceTd" colspan="1">Not empty, valid email address or phone with country prefix. For pl: 48500500500</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-2"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with key and optionally with LimitedResourceInfo.  
</p>

</td></tr></tbody></table>

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-42" style="width: 100%; height: 106.188px;"><colgroup><col style="width: 18.1706%;"></col><col style="width: 19.5289%;"></col><col style="width: 62.3005%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="confluenceTh" style="height: 29.7969px;">**Parameter**</th><th class="confluenceTh" style="height: 29.7969px;">**Type**</th><th class="confluenceTh" style="height: 29.7969px;">**Description**</th></tr><tr style="height: 46.5938px;"><td class="confluenceTd" style="height: 46.5938px;">key</td><td class="confluenceTd" style="height: 46.5938px;">CharArray</td><td class="confluenceTd" style="height: 46.5938px;">(Required) Initialization key that will be required for finalize reser user password process</td></tr><tr style="height: 29.7969px;"><td class="confluenceTd" colspan="1" style="height: 29.7969px;" width="">limitedResourceInfo</td><td class="confluenceTd" colspan="1" style="height: 29.7969px;" width="">LimitedRedourceInfo?</td><td class="confluenceTd" colspan="1" style="height: 29.7969px;" width="">Additional paremeter which shows information about rate of APIs limits.</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bde8e26d-767a-4d6d-8051-64ec62259124" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-2"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-initializeresetu"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### initializeResetUserPassword

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-17"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Reset user's password with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-43" style="width: 100%;"><colgroup><col style="width: 23.9817%;"></col><col style="width: 24.1023%;"></col><col style="width: 33.869%;"></col><col style="width: 18.1706%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">initializeResetUserPassword</td><td class="confluenceTd">InitializeResetUserPassword</td><td class="confluenceTd">An object containing user login type and user login</td><td class="confluenceTd"> Not empty

</td></tr></tbody></table>

**InitializeResetUserPassword** model:

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-44" style="width: 80.9877%; height: 125.984px;"><colgroup><col style="width: 16.1832%;"></col><col style="width: 14.4999%;"></col><col style="width: 69.3169%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="confluenceTh" style="height: 29.7969px;">Parameter</th><th class="confluenceTh" style="height: 29.7969px;">Type</th><th class="confluenceTh" style="height: 29.7969px;">Description</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd" style="height: 49.5938px;">userLoginType</td><td class="confluenceTd" style="height: 49.5938px;">UserType</td><td class="confluenceTd" style="height: 49.5938px;">User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]

</td></tr><tr style="height: 46.5938px;"><td class="confluenceTd" style="height: 46.5938px;">userLogin</td><td class="confluenceTd" style="height: 46.5938px;">CharArray</td><td class="confluenceTd" style="height: 46.5938px;">User identifier. Depends on user identifier type</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with key.</p>

</td></tr></tbody></table>

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-45" style="width: 100%;"><colgroup><col style="width: 17.6761%;"></col><col style="width: 18.6638%;"></col><col style="width: 63.6601%;"></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th></tr><tr><td class="confluenceTd">key</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">(Required) Initialization key that will be required for finalize reser user password process</td></tr><tr><td class="confluenceTd" colspan="1">limitedResourceInfo</td><td class="confluenceTd" colspan="1">LimitedResourceInfo?</td><td class="confluenceTd" colspan="1">Additional paremeter which shows information about rate limited APIs.</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bde8e26d-767a-4d6d-8051-64ec62259124" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-initializeresetu-0"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### finalizeResetUserPassword

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-18"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Set new user password with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-46" style="width: 100%;"><colgroup><col style="width: 13.2235%;"></col><col style="width: 10.1387%;"></col><col style="width: 28.5538%;"></col><col style="width: 48.0841%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">userLoginType</td><td class="confluenceTd">UserType</td><td class="confluenceTd"> User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]

</td><td class="confluenceTd"> Not empty</td></tr><tr><td class="confluenceTd" colspan="1">userLogin</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">User identifier. Depends on user identifier type</td><td class="confluenceTd" colspan="1">Not empty, valid email address or phone with country prefix. For pl: 48500500500</td></tr><tr><td class="confluenceTd" colspan="1">key</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Key from initialize reset user password method</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">otp</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">One time password (sent via email during initialize password reset process)</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">newPassword</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">New user password</td><td class="confluenceTd" colspan="1">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</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-14"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-finalizeresetuse"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### initializeEmailUpdate

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-19"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="be455b11-a2af-4ecd-b6fd-d757a5f09930">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.  
</span></p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-47"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd" colspan="1">email</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">New email (an OTP will be sent to that address)

</td><td class="confluenceTd" colspan="1">Email format</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout success">Success callback with key.</p>

</td></tr></tbody></table>

<table class="confluenceTable" id="bkmrk-parameter-type-descr-48"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">key</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Initialization key that will be required for finalize reset user password process</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6d7f9b22-b90d-4a28-9b8d-5d9dffea2bd0" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-initializeemailu"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### finalizeEmailUpdate

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-20"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Set new user email.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-49"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd" colspan="1">key</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Key from initialize change email method</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">otp</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">One time password (sent via email during initialize change email process)</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-15"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-finalizeemailupd"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### resendOtp

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-21"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Method for resend OTP.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-50"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd" colspan="1">userLoginType</td><td class="confluenceTd" colspan="1">UserType</td><td class="confluenceTd" colspan="1">User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">userLogin</td><td class="confluenceTd" colspan="1">User identifier. Depends on user identifier type</td><td class="confluenceTd" colspan="1">User identifier. Depends on user identifier type</td><td class="confluenceTd" colspan="1">Not empty, valid email address or phone with country prefix. For pl: 48500500500</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-16"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-resendotp%28userlo"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### logout

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="e6f53b54-8abb-4a1d-b90f-eadd82dc4836" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Cancels user session.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-17"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-logout%28%29-%7B-mobil"><tbody><tr><td class="wysiwyg-macro-body">```
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            
        })
}
```

</td></tr></tbody></table>

### deleteUser

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-22"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">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)</p>

<p class="callout info"><u>Usage of this method causes clearing all data related to selected user.</u>  
</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success%2Ffailure-call"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success/failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="cefc550c-5147-4e3f-a684-9694049b9071" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-deleteuser%28%29-%7B-m"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

## Cards domain

### addCard

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-23"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Adds new payment card with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-51"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">addCard</td><td class="confluenceTd">AddCard</td><td class="confluenceTd">Card information data.</td></tr></tbody></table>

**AddCard**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-52" style="width: 100%; height: 342.141px;"><colgroup><col style="width: 13.7206%;"></col><col style="width: 12.6054%;"></col><col style="width: 23.2413%;"></col><col style="width: 50.4326%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="confluenceTh" style="height: 29.7969px;">**Parameter**</th><th class="confluenceTh" style="height: 29.7969px;">**Type**</th><th class="confluenceTh" style="height: 29.7969px;">**Description**</th><th class="confluenceTh" style="height: 29.7969px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd" style="height: 49.5938px;">cardNumber</td><td class="confluenceTd" style="height: 49.5938px;">CharArray</td><td class="confluenceTd" style="height: 49.5938px;">Card number

</td><td class="confluenceTd" style="height: 49.5938px;">Field cannot be empty, it must contain only digits, a length of exactly 16 digits and the checksum of the digits must be valid</td></tr><tr style="height: 46.5938px;"><td class="confluenceTd" style="height: 46.5938px;">expirationDate</td><td class="confluenceTd" style="height: 46.5938px;">CharArray</td><td class="confluenceTd" style="height: 46.5938px;">Card expiration date</td><td class="confluenceTd" style="height: 46.5938px;">Field may not be empty and must have a format MM/YY</td></tr><tr style="height: 35.3906px;"><td class="confluenceTd" style="height: 35.3906px;">description</td><td class="confluenceTd" style="height: 35.3906px;">CharArray</td><td class="confluenceTd" style="height: 35.3906px;">Card description

</td><td class="confluenceTd" style="height: 35.3906px;">Not empty</td></tr><tr style="height: 57.7812px;"><td class="confluenceTd" style="height: 57.7812px;">cardHolder</td><td class="confluenceTd" style="height: 57.7812px;">CardHolder

</td><td class="confluenceTd" style="height: 57.7812px;">Card holder data</td><td class="confluenceTd" style="height: 57.7812px;">Not empty</td></tr><tr style="height: 29.7969px;"><td class="confluenceTd" style="height: 29.7969px;">isDefault</td><td class="confluenceTd" style="height: 29.7969px;">Boolean?</td><td class="confluenceTd" style="height: 29.7969px;">Is default card for user</td><td class="confluenceTd" style="height: 29.7969px;">-</td></tr><tr style="height: 46.5938px;"><td class="confluenceTd" style="height: 46.5938px;">currency</td><td class="confluenceTd" style="height: 46.5938px;">CharArray?</td><td class="confluenceTd" style="height: 46.5938px;">Currency of card (ISO 4217, three letter code)</td><td class="confluenceTd" style="height: 46.5938px;">-</td></tr><tr style="height: 46.5938px;"><td class="confluenceTd" style="height: 46.5938px;">visualId</td><td class="confluenceTd" style="height: 46.5938px;">CharArray?</td><td class="confluenceTd" style="height: 46.5938px;">Visual identifier</td><td class="confluenceTd" style="height: 46.5938px;">-</td></tr><tr><td>name</td><td>CharArray?</td><td>Card name</td><td>-</td></tr><tr><td>brand</td><td>CharArray?</td><td>Card brand</td><td>-</td></tr></tbody></table>

**CardHolder**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-53"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">First name of card holder

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">lastName</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Last name of card holder</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with cardId.</p>

</td></tr></tbody></table>

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-54" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 14px;"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of added card</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-addcard%28addcard%3A"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### addCard (deprecated)

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-24"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Adds new payment card with given parameters.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-55" style="width: 100%;"><colgroup><col style="width: 13.2247%;"></col><col style="width: 11.4972%;"></col><col style="width: 17.1817%;"></col><col style="width: 58.0964%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">cardNumber</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Card number</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="2a8b387b-a22d-43f1-8131-57ff337b7c6f">Field</span> cannot be empty, it must contain only digits, a length of exactly 16 digits and the checksum of the digits must be valid</td></tr><tr><td class="confluenceTd">expirationDate</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Card expiration date</td><td class="confluenceTd">Field may not be empty and must have a format MM/YY</td></tr><tr><td class="confluenceTd">description</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Card description

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">CharArray

</td><td class="confluenceTd">Card holder first name</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">lastName</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Card holder last name</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="cff68a64-a34e-4db0-b395-608e079f86eb">Output</span>**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-6"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with cardId.</p>

</td></tr></tbody></table>

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-56"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of added card</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="01dddc41-787c-48f2-b9a3-7e16de321244">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-addcard%28cardnumb"><tbody><tr><td class="wysiwyg-macro-body">```
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
       	 })
}
```

</td></tr></tbody></table>

### getAll

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="62ccd748-1dd8-490f-825e-9fb87ed4cb5f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-25"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Provides user cards from Mobile DC backend.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="6ba37464-67ba-4870-b2e6-d83a4be5450e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-7"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with list of user cards.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-57"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cards</td><td class="confluenceTd">List &lt;Card&gt;</td><td class="confluenceTd">List of user cards

</td></tr></tbody></table>

**Card**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-0"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Card main identifier. Also used as paymentInstrumentId

</td></tr><tr><td class="confluenceTd" colspan="1">lastFourDigits</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Last four digits of user card</td></tr><tr><td class="confluenceTd" colspan="1">expirationDate</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Card expiration date</td></tr><tr><td class="confluenceTd" colspan="1">isVerified</td><td class="confluenceTd" colspan="1">Boolean</td><td class="confluenceTd" colspan="1">Flag informing about card verification

</td></tr><tr><td class="confluenceTd" colspan="1">cardHolder</td><td class="confluenceTd" colspan="1">CardHolder?</td><td class="confluenceTd" colspan="1">Card holder details</td></tr><tr><td class="confluenceTd" colspan="1">visualPath</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">Path to visual of card</td></tr><tr><td class="confluenceTd" colspan="1">description</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">Card description</td></tr><tr><td class="confluenceTd" colspan="1">cardType</td><td class="confluenceTd" colspan="1">CardType (MASTERCARD, VISA, OTHER, UNKNOWN)</td><td class="confluenceTd" colspan="1">Type of card</td></tr><tr><td class="confluenceTd" colspan="1">isDefault</td><td class="confluenceTd" colspan="1">Boolean</td><td class="confluenceTd" colspan="1">Indicates if card is default user’s card</td></tr><tr><td class="confluenceTd" colspan="1">source</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">From which source card has been added</td></tr><tr><td class="confluenceTd" colspan="1">currency</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">Currency code (ISO 4217, three letter code)</td></tr><tr><td class="confluenceTd" colspan="1">visualId</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">Visual id</td></tr><tr><td class="confluenceTd" colspan="1">externalId</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">Card external id</td></tr><tr><td class="confluenceTd" colspan="1">isLocked</td><td class="confluenceTd" colspan="1">Boolean</td><td class="confluenceTd" colspan="1">Flag which informs if card is locked</td></tr></tbody></table>

**CardHolder**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-1"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh" colspan="1">**Description**</th></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">String</td><td class="confluenceTd" colspan="1">Card holder first name</td></tr><tr><td class="confluenceTd">lastName</td><td class="confluenceTd">String</td><td class="confluenceTd" colspan="1">Card holder last name</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0d22d5a0-2696-456f-9197-316a059eb4c3" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="624723bc-c8d5-40cb-b571-7983b758cc02" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-getcards%28%29-%7B-mob"><tbody><tr><td class="wysiwyg-macro-body">```
fun getCards() {
    mobileDcApi
        .cardsService
        .getAll({ cards ->
            showCardList(cards)
        }, {
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}
```

</td></tr></tbody></table>

### getAll (with pagination)

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="62ccd748-1dd8-490f-825e-9fb87ed4cb5f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-26"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Provides user cards from Mobile DC backend.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-93" style="width: 100%;"><colgroup><col style="width: 11.0012%;"></col><col style="width: 20.5175%;"></col><col style="width: 53.2773%;"></col><col style="width: 15.204%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">getAllCards</td><td class="confluenceTd">GetAllCards?</td><td class="confluenceTd">Filters for getAllCards()</td><td class="confluenceTd">  
</td></tr></tbody></table>

**GetAllCardsMeta**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-58" style="width: 100%; height: 169.6px;"><colgroup><col style="width: 11.919%;"></col><col style="width: 25.9782%;"></col><col style="width: 46.8466%;"></col><col style="width: 15.2563%;"></col></colgroup><tbody><tr style="height: 46.6px;"><th class="confluenceTh" style="height: 46.6px;">**Parameter**</th><th class="confluenceTh" style="height: 46.6px;">**Type**</th><th class="confluenceTh" style="height: 46.6px;">**Description**</th><th class="confluenceTh" style="height: 46.6px;">**Validation conditions**</th></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">sortOptions</td><td class="confluenceTd" style="height: 46.6px;">List&lt;GetAllCardsSortOption&gt;?</td><td class="confluenceTd" style="height: 46.6px;">List of cards sorting options if applied. Order of sorting options is important in context of filtering</td><td class="confluenceTd" style="height: 46.6px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">page</td><td style="height: 29.8px;">Int?</td><td style="height: 29.8px;">Page number to retrieve</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">limit</td><td style="height: 46.6px;">Int?</td><td style="height: 46.6px;">Cards limit per page. If not provided, uses value from card configuration or falls back to default value of 50.</td><td style="height: 46.6px;">  
</td></tr></tbody></table>

**GetAllCardsSortOption**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-59" style="width: 100%; height: 123px;"><colgroup><col style="width: 11.919%;"></col><col style="width: 25.9782%;"></col><col style="width: 46.8466%;"></col><col style="width: 15.2563%;"></col></colgroup><tbody><tr style="height: 46.6px;"><th class="confluenceTh" style="height: 46.6px;">**Parameter**</th><th class="confluenceTh" style="height: 46.6px;">**Type**</th><th class="confluenceTh" style="height: 46.6px;">**Description**</th><th class="confluenceTh" style="height: 46.6px;">**Validation conditions**</th></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">sortBy</td><td class="confluenceTd" style="height: 46.6px;">String</td><td class="confluenceTd" style="height: 46.6px;">Cards sorting filter. Should be one or more of: verified,locked,created</td><td class="confluenceTd" style="height: 46.6px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">sortOrder</td><td style="height: 29.8px;">GetAllCardsMetaSortOrder</td><td style="height: 29.8px;">One of: ASC, DESC</td><td style="height: 29.8px;">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-8"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with list of user cards with meta pagination object.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-60" style="width: 59.2857%; height: 106.2px;"><colgroup><col style="width: 29.176%;"></col><col style="width: 35.6403%;"></col><col style="width: 35.187%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="confluenceTh" style="height: 29.8px;">**Parameter**</th><th class="confluenceTh" style="height: 29.8px;">**Type**</th><th class="confluenceTh" style="height: 29.8px;">**Description**</th></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">cards</td><td class="confluenceTd" style="height: 46.6px;">List &lt;Card&gt;</td><td class="confluenceTd" style="height: 46.6px;">List of user cards

</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">meta</td><td style="height: 29.8px;">GetAllCardsMetaResult</td><td style="height: 29.8px;">Pagination details object

</td></tr></tbody></table>

**Card**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-2"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Card main identifier. Also used as paymentInstrumentId

</td></tr><tr><td class="confluenceTd">lastFourDigits</td><td class="confluenceTd">String</td><td class="confluenceTd">Last four digits of user card</td></tr><tr><td class="confluenceTd">expirationDate</td><td class="confluenceTd">String</td><td class="confluenceTd">Card expiration date</td></tr><tr><td class="confluenceTd">isVerified</td><td class="confluenceTd">Boolean</td><td class="confluenceTd">Flag informing about card verification

</td></tr><tr><td class="confluenceTd">cardHolder</td><td class="confluenceTd">CardHolder?</td><td class="confluenceTd">Card holder details</td></tr><tr><td class="confluenceTd">visualPath</td><td class="confluenceTd">String?</td><td class="confluenceTd">Path to visual of card</td></tr><tr><td class="confluenceTd">description</td><td class="confluenceTd">String?</td><td class="confluenceTd">Card description</td></tr><tr><td class="confluenceTd">cardType</td><td class="confluenceTd">CardType (MASTERCARD, VISA, OTHER, UNKNOWN)</td><td class="confluenceTd">Type of card</td></tr><tr><td class="confluenceTd">isDefault</td><td class="confluenceTd">Boolean</td><td class="confluenceTd">Indicates if card is default user’s card</td></tr><tr><td class="confluenceTd">source</td><td class="confluenceTd">String?</td><td class="confluenceTd">From which source card has been added</td></tr><tr><td class="confluenceTd">currency</td><td class="confluenceTd">String?</td><td class="confluenceTd">Currency code (ISO 4217, three letter code)</td></tr><tr><td class="confluenceTd">visualId</td><td class="confluenceTd">String?</td><td class="confluenceTd">Visual id</td></tr><tr><td class="confluenceTd">externalId</td><td class="confluenceTd">String?</td><td class="confluenceTd">Card external id</td></tr><tr><td class="confluenceTd">isLocked</td><td class="confluenceTd">Boolean</td><td class="confluenceTd">Flag which informs if card is locked</td></tr><tr><td>name</td><td>String?</td><td>Card name</td></tr><tr><td>brand</td><td>String?</td><td>Card brand</td></tr></tbody></table>

**CardHolder**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-3"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh" colspan="1">**Description**</th></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">String</td><td class="confluenceTd" colspan="1">Card holder first name</td></tr><tr><td class="confluenceTd">lastName</td><td class="confluenceTd">String</td><td class="confluenceTd" colspan="1">Card holder last name</td></tr></tbody></table>

**GetAllCardsMetaResult**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-4"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">currentPage</td><td class="confluenceTd">Int</td><td class="confluenceTd">Current page number, starting from 1</td></tr><tr><td class="confluenceTd">from</td><td class="confluenceTd">Int?</td><td class="confluenceTd">Current page first element number</td></tr><tr><td>lastPage</td><td>Int</td><td>Last page number, starting from 1</td></tr><tr><td>perPage</td><td>Int</td><td>Number of elements per page</td></tr><tr><td>to</td><td>Int?</td><td>Current page last element number</td></tr><tr><td>total</td><td>Int</td><td>Total number of elements</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="0d22d5a0-2696-456f-9197-316a059eb4c3" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback.-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
fun getCards() {
    val sortOption1 = GetAllCardsMetaSortOption(
      sortBy = "created",
      sortOrder = GetAllCardsMetaSortOrder.DESC
    )

    val sortOption2 = GetAllCardsMetaSortOption(
      sortBy = "locked",
      sortOrder = GetAllCardsMetaSortOrder.DESC
    )

    val getAllCardsMeta = GetAllCardsMeta(
      sortOptions = listOf(sortOption1, sortOption2),
      page = 1,
      limit = 10
    )

    val getAllCards = GetAllCards(getAllCardsMeta)

    MobileDcApiKotlin.cardsService.getAll(getAllCards, { result ->
      val cards = result.cards
      val meta = result.meta
      showCardsWithPagination(cards, meta)
    }, {
      // Something went wrong
      // Check exceptions described in Error handling chapter
    })
}
```

### deleteCard

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-27"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Delete card with given card id.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-61"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of deleting card</td><td class="confluenceTd">Field cannot be empty.</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-18"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-deletecard%28cardi"><tbody><tr><td class="wysiwyg-macro-body">```
fun deleteCard(cardId: Long) {
    mobileDcApi
        .cardsService
        .deleteCard(cardId, {
            //Success
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter
        })
}
```

</td></tr></tbody></table>

### initialize3ds

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-28"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Card verification- initialize 3D Secure. Provides the data needed for the 3D Secure verification process.</p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-62"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th><th class="confluenceTh">Validation conditions</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of added card</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-9"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with Initialize3dsResult.</p>

</td></tr></tbody></table>

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-63"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">initialize3dsResult</td><td class="confluenceTd">Initialize3dsResult</td><td class="confluenceTd">Contains necessary data for 3DS verification</td></tr></tbody></table>

**Initialize3dsResult**

<table class="wrapped relative-table confluenceTable" id="bkmrk-field-type-descripti-5"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">paymentId</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Internal transaction id</td></tr><tr><td class="confluenceTd">pageContent</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Content of webpage to be shown in browser created in application</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-initialize3ds%28mo"><tbody><tr><td class="wysiwyg-macro-body">```
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<WebView>(R.id.myWebView)

        //JavaScript is disabled in a WebView by default. You can enable it through the WebSettings
        //attached to your WebView. You can retrieve WebSettings with getSettings(), then enable JavaScript 
        //with setJavaScriptEnabled().
        val webSettings: WebSettings = myWebView.getSettings()
        webSettings.javaScriptEnabled = true

        //Necessary bind this class to the JavaScript that runs in your WebView with addJavascriptInterface() 
        //and name the interface Android.
        myWebView.addJavascriptInterface(WebAppInterface(), "Android")

        // Decode pageContent from initialize3ds response
        val viewPageContent = String(Base64.decode(pageContent, Base64.DEFAULT))
        // Load page in vebWiew
        myWebView.loadData(viewPageContent, "text/html; charset=UTF-8", "utf-8")
    }

//To bind a new interface between your JavaScript and Android code, call addJavascriptInterface(),
//passing it a class instance to bind to your JavaScript and an interface name that your JavaScript 
//can call to access the class, like below example

    class WebAppInterface {
        // Get the pares parameter from the web page
        @JavascriptInterface
       	fun setData(pares: String?) {
            // onPares interface method provides the pares parameter after interaction with webView. 
            //Parameter pares is needed to perform finalize3ds
            // Necessary convert from String to CharArray
            val paresToCharArray = pares?.toCharArray()
            // close webView
            // Then you need to properly handle the parameter pares to be able to call finalize3ds
            //with the parameter pares and paymentId.
        }
    }

```

</td></tr></tbody></table>

### finalize3ds

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-29"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-64" style="width: 100%;"><colgroup><col style="width: 11.0012%;"></col><col style="width: 11.9941%;"></col><col style="width: 29.1678%;"></col><col style="width: 47.8368%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of added card</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">cvc</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1">Card verification code </td><td class="confluenceTd" colspan="1">Field cannot be empty, it must contain only digits, a length of exactly 3 digits</td></tr><tr><td class="confluenceTd" colspan="1">pares</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="14d8c3e1-9ee3-4664-9aed-dec3d13d2c86">Received after successful interaction with webView  
</span></td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">paymentId</td><td class="confluenceTd" colspan="1">CharArray</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="424ee91e-3788-4cf8-8ed6-bfd594e0455f">Received after a valid query to Initialize3ds  
</span></td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-10"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with Finalize3dsResult.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-65" style="width: 100%;"><colgroup><col style="width: 17.6761%;"></col><col style="width: 16.8068%;"></col><col style="width: 65.5171%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">finalize3dsResult</td><td class="confluenceTd">Finalize3dsResult</td><td class="confluenceTd">Contains data on the needed to carry out the amount verification and the verification value of the cardholder authentication</td></tr></tbody></table>

**Finalize3dsResult**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-6"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">amountValidation</td><td class="confluenceTd">Boolean</td><td class="confluenceTd">Inform if random quotation should be used to complete card verification</td></tr><tr><td class="confluenceTd">cavv</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">Cardholder authentication verification value</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="c9cfe99d-66da-444d-a0c1-97fa75b87968">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-finalize3ds%28mobi"><tbody><tr><td class="wysiwyg-macro-body">```
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
            })
}
```

</td></tr></tbody></table>

### initialize3DSv2

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-30" style="width: 85.0617%; height: 105.8px;"><tbody><tr style="height: 105.8px;"><td class="wysiwyg-macro-body" style="width: 99.8549%; height: 105.8px;"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Card verification - initialize 3D Secure. Provides the data needed for the 3D Secure verification process.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-66"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">initialize3DSv2</td><td class="confluenceTd">Initialize3DSv2</td><td class="confluenceTd">An object containing data for secure verification process.</td><td class="confluenceTd">Not empty

</td></tr></tbody></table>

**Initialize3DSv2**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-67"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditaions**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of the card</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">challengeUrl</td><td class="confluenceTd">String</td><td class="confluenceTd">Callback url to handle redirect during Challenge (status CHALLENGE\_REQUIRED from response).  
Check sample implementation below.

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">browserDetails</td><td class="confluenceTd">BrowserDetails</td><td class="confluenceTd">Object with properties described below</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**BrowserDetails**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-68"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">timezoneOffset</td><td class="confluenceTd">String</td><td class="confluenceTd">Timezone offset - numeric</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">userAgent</td><td class="confluenceTd">String</td><td class="confluenceTd">User Agent</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">acceptHeader</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Accept Header</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">screenWidth</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Screen Width - numeric</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">screenHeight</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Screen Height</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">language</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Language - IETF BCP 47</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">browserIp</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Browser IP</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">screenColorDepth</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Screen Color Depth - numeric</td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-11"><tbody><tr><td class="wysiwyg-macro-body">**Success callback with Initialize3DSv2Result**

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-69"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">initialize3DSv2Result</td><td class="confluenceTd">Initialize3DSv2Result</td><td class="confluenceTd">Contains necessary data for 3DS verification</td></tr></tbody></table>

**Initialize3DSv2Result**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-7" style="width: 100%;"><colgroup><col style="width: 18.1706%;"></col><col style="width: 9.51411%;"></col><col style="width: 72.3153%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">status</td><td class="confluenceTd">String</td><td class="confluenceTd">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.*

</td></tr><tr><td class="confluenceTd">authenticationId</td><td class="confluenceTd">String</td><td class="confluenceTd">Card authentication id, used in finalize3DSv2 method.</td></tr><tr><td class="confluenceTd" colspan="1">acsUrl</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">ACS (Access Control Server) url. Required for CHALLENGE\_REQUIRED.</td></tr><tr><td class="confluenceTd" colspan="1">challengeHtmlFormBase64</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1">64BASED html code provided ACQ/ASC. This should be displayed to Application User. Required for CHALLENGE\_REQUIRED.</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-initialize3dsv2%28"><tbody><tr><td class="wysiwyg-macro-body">```
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)
        }
    }
}
```

</td></tr></tbody></table>

### finalize3DSv2

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-31"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-70"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">finalize3DSv2</td><td class="confluenceTd">Finalize3DSv2</td><td class="confluenceTd">An object containing data for secure finalization process.</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

####   


**Finalize3DSv2**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-71"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Id of the card.</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">authenticationId</td><td class="confluenceTd">String</td><td class="confluenceTd">Identifier of verification process from Initialize3DSv2Result</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-0"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-finalize3ds%28mobi-0"><tbody><tr><td class="wysiwyg-macro-body">```
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
            }
        )
}
```

</td></tr></tbody></table>

### updateCard

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="62ccd748-1dd8-490f-825e-9fb87ed4cb5f" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-method-for-updating-"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Method for updating payment card data.</p>

</td></tr></tbody></table>

**Input**

<table class="confluenceTable" id="bkmrk-parameter-type-descr-72"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">updateCard</td><td class="confluenceTd" colspan="1">UpdateCard</td><td class="confluenceTd" colspan="1">An object containing card data to update</td></tr></tbody></table>

**UpdateCard**

<table class="confluenceTable" id="bkmrk-parameter-type-descr-73"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Unique card id</td></tr><tr><td class="confluenceTd">description</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Card description</td></tr><tr><td class="confluenceTd">currency</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Card currency (ISO 4217, three letter code format)</td></tr><tr><td class="confluenceTd">isDefault</td><td class="confluenceTd">Boolean?</td><td class="confluenceTd">Is this card default</td></tr><tr><td class="confluenceTd">visualId</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Card visual identifier</td></tr><tr><td class="confluenceTd">firstName</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Card holder first name - send only when lastName is not blank</td></tr><tr><td class="confluenceTd">lastName</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">Card holder last name - send only when firstName is not blank</td></tr><tr><td>name</td><td>CharArray?</td><td>Card name</td></tr><tr><td>brand</td><td>CharArray?</td><td>Card brand</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-updatecard%28cardi"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

### verifyCard

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-32"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Card verification - verify card after 3ds.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-74"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">verifyCard</td><td class="confluenceTd" colspan="1">VerifyCard</td><td class="confluenceTd" colspan="1">An object containing card data to verify.</td></tr></tbody></table>

**VerifyCard**

<table class="relative-table confluenceTable" id="bkmrk-parameter-type-descr-75" style="width: 100%;"><colgroup><col style="width: 12.6082%;"></col><col style="width: 13.3445%;"></col><col style="width: 74.0474%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">cardId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Unique card id</td></tr><tr><td class="confluenceTd">amount</td><td class="confluenceTd">CharArray?</td><td class="confluenceTd">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).</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-2"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-verifycard%28cardi"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

## Device domain

### pairByPassword (deprecated in 2.14.6)  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-33"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="c7e7b47e-b586-4ee7-be43-abe9635bfa92">Pairs device using given password and user identifier.</span></p>

<p class="callout info"><span class="inline-comment-marker" data-ref="c7e7b47e-b586-4ee7-be43-abe9635bfa92">Deprecated, use pairByPassword(PairByPassword)</span></p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="920192c0-ccc2-4ba9-8659-438b7e5694bc">Input</span>**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-76" style="width: 100%; height: 579.2px;"><colgroup><col style="width: 16.933%;"></col><col style="width: 19.779%;"></col><col style="width: 22.0025%;"></col><col style="width: 41.2855%;"></col></colgroup><tbody><tr style="height: 35.4px;"><th class="confluenceTh" style="height: 35.4px;">**Parameter**</th><th class="confluenceTh" style="height: 35.4px;">**Type**</th><th class="confluenceTh" style="height: 35.4px;">**Description**</th><th class="confluenceTh" style="height: 35.4px;">**Validation conditions**

</th></tr><tr style="height: 102.6px;"><td class="confluenceTd" style="height: 102.6px;">userLoginType</td><td class="confluenceTd" style="height: 102.6px;">UserType</td><td class="confluenceTd" style="height: 102.6px;">User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]

</td><td class="confluenceTd" style="height: 102.6px;">Not empty</td></tr><tr style="height: 49.4px;"><td class="confluenceTd" colspan="1" style="height: 49.4px;">userLogin</td><td class="confluenceTd" colspan="1" style="height: 49.4px;">CharArray</td><td class="confluenceTd" colspan="1" style="height: 49.4px;">User identifier. Depends on user identifier type</td><td class="confluenceTd" colspan="1" style="height: 49.4px;">Email or Phone with country prefix

</td></tr><tr style="height: 63.4px;"><td class="confluenceTd" colspan="1" style="height: 63.4px;">userPassword</td><td class="confluenceTd" colspan="1" style="height: 63.4px;">CharArray</td><td class="confluenceTd" colspan="1" style="height: 63.4px;">User password</td><td class="confluenceTd" colspan="1" style="height: 63.4px;">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</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" colspan="1" style="height: 46.6px;">fcmToken</td><td class="confluenceTd" colspan="1" style="height: 46.6px;">CharArray</td><td class="confluenceTd" colspan="1" style="height: 46.6px;">Token for push notifications</td><td class="confluenceTd" colspan="1" style="height: 46.6px;">Not empty</td></tr><tr style="height: 281.8px;"><td class="confluenceTd" colspan="1" style="height: 281.8px;">biometricAuthType</td><td class="confluenceTd" colspan="1" style="height: 281.8px;">BiometricAuthType?</td><td class="confluenceTd" colspan="1" style="height: 281.8px;">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.

</td><td class="confluenceTd" colspan="1" style="height: 281.8px;">  
</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="cefb375f-5c7f-40f0-9218-4a314e3e4f3a">Output</span>**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-19"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="f3fc93ca-244a-4803-b401-00a97dfd323e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-pairbypassword%28-"><tbody><tr><td class="wysiwyg-macro-body">```
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
            }
        )
}
```

</td></tr></tbody></table>

### pairByPassword  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="bdb4f40b-16a6-466d-b7e8-9395322829c4" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-34"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="c7e7b47e-b586-4ee7-be43-abe9635bfa92">Pairs device using given password and user identifier.</span></p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="920192c0-ccc2-4ba9-8659-438b7e5694bc">Input</span>**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-77" style="width: 100%; height: 124px;"><colgroup><col style="width: 16.9345%;"></col><col style="width: 19.7775%;"></col><col style="width: 28.1787%;"></col><col style="width: 35.1093%;"></col></colgroup><tbody><tr style="height: 49.4px;"><th class="confluenceTh" style="height: 49.4px;">**Parameter**</th><th class="confluenceTh" style="height: 49.4px;">**Type**</th><th class="confluenceTh" style="height: 49.4px;">**Description**</th><th class="confluenceTh" style="height: 49.4px;">**Validation conditions**

</th></tr><tr style="height: 74.6px;"><td class="confluenceTd" style="height: 74.6px;">pairByPassword</td><td class="confluenceTd" style="height: 74.6px;">PairByPassword</td><td class="confluenceTd" style="height: 74.6px;">An object containing user information to pair device.

</td><td class="confluenceTd" style="height: 74.6px;">Not empty</td></tr></tbody></table>

**PairByPassword**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-78" style="width: 100%; height: 642.6px;"><colgroup><col style="width: 23.4858%;"></col><col style="width: 17.0581%;"></col><col style="width: 23.4858%;"></col><col style="width: 35.9703%;"></col></colgroup><tbody><tr style="height: 38.2px;"><th class="confluenceTh" style="height: 38.2px;">**Parameter**</th><th class="confluenceTh" style="height: 38.2px;">**Type**</th><th class="confluenceTh" style="height: 38.2px;">**Description**</th><th class="confluenceTh" style="height: 38.2px;">**Validation conditions**

</th></tr><tr style="height: 105.4px;"><td class="confluenceTd" style="height: 105.4px;">userLoginType</td><td class="confluenceTd" style="height: 105.4px;">UserType</td><td class="confluenceTd" style="height: 105.4px;">User identifier type. One of: \[PHONE, EMAIL, INTERNAL\_ID, EXTERNAL\_ID\]

</td><td class="confluenceTd" style="height: 105.4px;">Not empty</td></tr><tr style="height: 52.2px;"><td class="confluenceTd" style="height: 52.2px;">userLogin</td><td class="confluenceTd" style="height: 52.2px;">CharArray</td><td class="confluenceTd" style="height: 52.2px;">User identifier. Depends on user identifier type</td><td class="confluenceTd" style="height: 52.2px;">Email or Phone with country prefix

</td></tr><tr style="height: 80.2px;"><td class="confluenceTd" style="height: 80.2px;">userPassword</td><td class="confluenceTd" style="height: 80.2px;">CharArray</td><td class="confluenceTd" style="height: 80.2px;">User password</td><td class="confluenceTd" style="height: 80.2px;">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</td></tr><tr style="height: 46.6px;"><td class="confluenceTd" style="height: 46.6px;">cloudMessaging  
RegistrationToken</td><td class="confluenceTd" style="height: 46.6px;">CloudMessaging  
RegistrationToken</td><td class="confluenceTd" style="height: 46.6px;">An object containing cloud messaging registration token information</td><td class="confluenceTd" style="height: 46.6px;">Not empty</td></tr><tr style="height: 284.6px;"><td class="confluenceTd" style="height: 284.6px;">biometricAuthType</td><td class="confluenceTd" style="height: 284.6px;">BiometricAuthType?</td><td class="confluenceTd" style="height: 284.6px;">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.

</td><td class="confluenceTd" style="height: 284.6px;">  
</td></tr><tr style="height: 35.4px;"><td style="height: 35.4px;">externalDeviceId</td><td style="height: 35.4px;">String?</td><td style="height: 35.4px;">External device id

</td><td style="height: 35.4px;">  
</td></tr></tbody></table>

**CloudMessagingRegistrationToken**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-79" style="width: 100%; height: 168.2px;"><colgroup><col style="width: 17.7998%;"></col><col style="width: 19.7775%;"></col><col style="width: 34.2302%;"></col><col style="width: 28.1926%;"></col></colgroup><tbody><tr style="height: 53.2px;"><th class="confluenceTh" style="height: 53.2px;">**Parameter**</th><th class="confluenceTh" style="height: 53.2px;">**Type**</th><th class="confluenceTh" style="height: 53.2px;">**Description**</th><th class="confluenceTh" style="height: 53.2px;">**Validation conditions**

</th></tr><tr style="height: 65.4px;"><td class="confluenceTd" style="height: 65.4px;">type</td><td class="confluenceTd" style="height: 65.4px;">CloudMessagingType</td><td class="confluenceTd" style="height: 65.4px;">Mandatory. One of: \[FCM, EXTERNAL\].

FCM - Firebase Cloud Messaging  
EXTERNAL - External token for external source of RNS

</td><td class="confluenceTd" style="height: 65.4px;">Not empty</td></tr><tr style="height: 49.6px;"><td class="confluenceTd" style="height: 49.6px;">token</td><td class="confluenceTd" style="height: 49.6px;">String</td><td class="confluenceTd" style="height: 49.6px;">Token for push notifications

</td><td class="confluenceTd" style="height: 49.6px;">Not empty</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="cefb375f-5c7f-40f0-9218-4a314e3e4f3a">Output</span>**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7a415e9-e54f-418b-8638-8749fce6d79a" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-20"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="f3fc93ca-244a-4803-b401-00a97dfd323e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-val-cloudmessagingre"><tbody><tr><td class="wysiwyg-macro-body">```
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
            }
        )
}
```

</td></tr></tbody></table>

### pairByTrustedIdentity (deprecared in 2.14.6)  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="aee94788-bdc6-4a95-8224-e0f5ff3c59c1" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-35" style="width: 76.6667%; height: 106.8px;"><tbody><tr style="height: 106.8px;"><td class="wysiwyg-macro-body" style="width: 99.839%; height: 106.8px;"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Binds device to user in Mobile DC backend with Trusted Identity genetated by client server.</p>

<p class="callout info">Deprecated, use pairByTrustedIdentity(PairByTrustedIdentity).</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-80"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">trustedIdentity</td><td class="confluenceTd">String</td><td class="confluenceTd">JSON Web Token containing registration data

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">fcmRegistrationToken</td><td class="confluenceTd">CharArray</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="ce48baeb-cf63-42db-b50b-1a906bc791e9">FCM Cloud messaging registration token</span>

</td><td class="confluenceTd">Not empty

</td></tr></tbody></table>

**TrustedIdentity**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-81"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh" colspan="1">Parameter</th><th class="confluenceTh" colspan="1">Type</th><th class="confluenceTh" colspan="1">Description</th><th class="confluenceTh" colspan="1">Validation conditions

</th></tr><tr><td class="confluenceTd">userId</td><td class="confluenceTd">String</td><td class="confluenceTd">External user id given by the client

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="938b982f-76b9-472d-9776-9de893d5dbe0" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-21"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

Sample code for *trustedIdentity* generation (<span class="inline-comment-marker" data-ref="df185511-fdb4-471c-b2bb-17fe8f12383b">see also </span>*<span class="inline-comment-marker" data-ref="df185511-fdb4-471c-b2bb-17fe8f12383b">[Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption)</span>* chapter):

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-trustedidentit-0"><tbody><tr><td class="wysiwyg-macro-body">```
class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}
```

</td></tr></tbody></table>

Usage of trustedIdentity in application:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="f3fc93ca-244a-4803-b401-00a97dfd323e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-pairdevicebytrus"><tbody><tr><td class="wysiwyg-macro-body">```
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
            })
}
```

</td></tr></tbody></table>

### pairByTrustedIdentity  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="aee94788-bdc6-4a95-8224-e0f5ff3c59c1" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-36" style="width: 76.6667%; height: 110.6px;"><tbody><tr style="height: 110.6px;"><td class="wysiwyg-macro-body" style="width: 99.839%; height: 110.6px;"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Binds device to user in Mobile DC backend with Trusted Identity genetated by client server.</p>

  
</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-82"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">pairByTrustedIdentity</td><td class="confluenceTd">PairByTrustedIdentity</td><td class="confluenceTd">An object containing user information to pair device.

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**PairByTrustedIdentity**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-83" style="width: 100%;"><colgroup><col style="width: 27.8121%;"></col><col style="width: 28.6792%;"></col><col style="width: 26.945%;"></col><col style="width: 16.5637%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">trustedIdentity</td><td class="confluenceTd">String</td><td class="confluenceTd">JSON Web Token containing registration data

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">cloudMessagingRegistrationToken</td><td class="confluenceTd">CloudMessagingRegistrationToken</td><td class="confluenceTd">An object containing cloud messaging registration token information

</td><td class="confluenceTd">Not empty

</td></tr><tr><td>externalDeviceId</td><td>String?  
</td><td>External device id

</td><td></td></tr></tbody></table>

**TrustedIdentity**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-84" style="width: 98.5185%;"><colgroup><col style="width: 20.2663%;"></col><col style="width: 24.1124%;"></col><col style="width: 40.9763%;"></col><col style="width: 14.645%;"></col></colgroup><tbody><tr><th class="confluenceTh" colspan="1">**Parameter**</th><th class="confluenceTh" colspan="1">**Type**</th><th class="confluenceTh" colspan="1">**Description**</th><th class="confluenceTh" colspan="1">**Validation conditions**

</th></tr><tr><td class="confluenceTd">userId</td><td class="confluenceTd">String</td><td class="confluenceTd">External user id given by the client

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**CloudMessagingRegistrationToken**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-85" style="width: 100%; height: 168.2px;"><colgroup><col style="width: 17.7998%;"></col><col style="width: 19.7775%;"></col><col style="width: 34.2302%;"></col><col style="width: 28.1926%;"></col></colgroup><tbody><tr style="height: 53.2px;"><th class="confluenceTh" style="height: 53.2px;">**Parameter**</th><th class="confluenceTh" style="height: 53.2px;">**Type**</th><th class="confluenceTh" style="height: 53.2px;">**Description**</th><th class="confluenceTh" style="height: 53.2px;">**Validation conditions**

</th></tr><tr style="height: 65.4px;"><td class="confluenceTd" style="height: 65.4px;">type</td><td class="confluenceTd" style="height: 65.4px;">CloudMessagingType</td><td class="confluenceTd" style="height: 65.4px;">Mandatory. One of: \[FCM, EXTERNAL\].

FCM - Firebase Cloud Messaging  
EXTERNAL - External token for external source of RNS

</td><td class="confluenceTd" style="height: 65.4px;">Not empty</td></tr><tr style="height: 49.6px;"><td class="confluenceTd" style="height: 49.6px;">token</td><td class="confluenceTd" style="height: 49.6px;">String</td><td class="confluenceTd" style="height: 49.6px;">Token for push notifications

</td><td class="confluenceTd" style="height: 49.6px;">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="938b982f-76b9-472d-9776-9de893d5dbe0" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-22"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

Sample code for *trustedIdentity* generation (<span class="inline-comment-marker" data-ref="df185511-fdb4-471c-b2bb-17fe8f12383b">see also </span>*<span class="inline-comment-marker" data-ref="df185511-fdb4-471c-b2bb-17fe8f12383b">[Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption)</span>* chapter):

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="43fc608c-04c3-42b3-94c0-31190bb52ee0" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-class-trustedidentit-1"><tbody><tr><td class="wysiwyg-macro-body">```
class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}
```

</td></tr></tbody></table>

Usage of trustedIdentity in application:

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="f3fc93ca-244a-4803-b401-00a97dfd323e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-val-cloudmessagingre-0"><tbody><tr><td class="wysiwyg-macro-body">```
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
            }
        )
}
```

</td></tr></tbody></table>

###   


### pairByExternalCredentials (deprecated in 2.14.6)  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="501a32d9-eb50-4e3b-8c75-3c03cc79f384" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-37"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Binds device to user in Mobile DC backend using username and password.</p>

<p class="callout info">Deprecated, use pairByTrustedIdentity(PairByExternalCredentials).</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-86" style="width: 100%;"><colgroup><col style="width: 18.4178%;"></col><col style="width: 18.4125%;"></col><col style="width: 45.1228%;"></col><col style="width: 18.047%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">username</td><td class="confluenceTd">String</td><td class="confluenceTd">User identifier

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">password</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">User password</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">fcmRegistrationToken</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">FCM Cloud messaging registration token

</td><td class="confluenceTd">Not empty

</td></tr><tr><td class="confluenceTd" colspan="1">biometricAuthType</td><td class="confluenceTd" colspan="1">BiometricAuthType?</td><td class="confluenceTd" colspan="1">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.

</td><td class="confluenceTd" colspan="1">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="497eb30c-b59c-4a04-87a0-58683bec286d" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-23"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="593e803b-eaf5-4268-ac4b-633d7867af23" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-pairbyexternalcr"><tbody><tr><td class="wysiwyg-macro-body">```
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
            })
}
```

</td></tr></tbody></table>

### pairByExternalCredentials  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="501a32d9-eb50-4e3b-8c75-3c03cc79f384" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-38"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Binds device to user in Mobile DC backend using username and password.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-87" style="width: 100%;"><colgroup><col style="width: 22.4969%;"></col><col style="width: 23.4745%;"></col><col style="width: 35.9816%;"></col><col style="width: 18.047%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">pairByExternalCredentials</td><td class="confluenceTd">PairByExternalCredentials</td><td class="confluenceTd">An object containing user information to pair device.

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**PairByExternalCredentials**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-88" style="width: 104.938%;"><colgroup><col style="width: 28.5538%;"></col><col style="width: 29.7899%;"></col><col style="width: 28.3087%;"></col><col style="width: 13.3477%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">username</td><td class="confluenceTd">String</td><td class="confluenceTd">User identifier

</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">password</td><td class="confluenceTd">CharArray</td><td class="confluenceTd">User password</td><td class="confluenceTd">Not empty</td></tr><tr><td class="confluenceTd">cloudMessagingRegistrationToken</td><td class="confluenceTd">CloudMessagingRegistrationToken</td><td class="confluenceTd">FCM Cloud messaging registration token

</td><td class="confluenceTd">Not empty

</td></tr><tr><td class="confluenceTd">biometricAuthType</td><td class="confluenceTd">BiometricAuthType?</td><td class="confluenceTd">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.

</td><td class="confluenceTd">  
</td></tr><tr><td>externalDeviceId</td><td>String?  
</td><td>External device id

</td><td></td></tr></tbody></table>

**CloudMessagingRegistrationToken**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-89" style="width: 100%; height: 168.2px;"><colgroup><col style="width: 17.7998%;"></col><col style="width: 19.7775%;"></col><col style="width: 34.2302%;"></col><col style="width: 28.1926%;"></col></colgroup><tbody><tr style="height: 53.2px;"><th class="confluenceTh" style="height: 53.2px;">**Parameter**</th><th class="confluenceTh" style="height: 53.2px;">**Type**</th><th class="confluenceTh" style="height: 53.2px;">**Description**</th><th class="confluenceTh" style="height: 53.2px;">**Validation conditions**

</th></tr><tr style="height: 65.4px;"><td class="confluenceTd" style="height: 65.4px;">type</td><td class="confluenceTd" style="height: 65.4px;">CloudMessagingType</td><td class="confluenceTd" style="height: 65.4px;">Mandatory. One of: \[FCM, EXTERNAL\].

FCM - Firebase Cloud Messaging  
EXTERNAL - External token for external source of RNS

</td><td class="confluenceTd" style="height: 65.4px;">Not empty</td></tr><tr style="height: 49.6px;"><td class="confluenceTd" style="height: 49.6px;">token</td><td class="confluenceTd" style="height: 49.6px;">String</td><td class="confluenceTd" style="height: 49.6px;">Token for push notifications

</td><td class="confluenceTd" style="height: 49.6px;">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="497eb30c-b59c-4a04-87a0-58683bec286d" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-24"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="593e803b-eaf5-4268-ac4b-633d7867af23" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-val-cloudmessagingre-1"><tbody><tr><td class="wysiwyg-macro-body">```
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
            }
        )
}
```

</td></tr></tbody></table>

### isDevicePaired

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="3b5a673b-4913-48fc-a8fa-2109156c02e5" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-6"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Method allow to check is Device already paired with MDC Backend.  
</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="2d274cb7-d7ff-43cb-8d45-5c66f70e21f2" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-6"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="f45f933d-d457-4e35-a6e2-4ba9159c0256" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-25"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="e0152a11-495b-4976-a1f0-d52b84caf1b5">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="e7cf8263-8c60-44e0-a8c1-8921372f7cfc" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-isdevicepaired%28%29"><tbody><tr><td class="wysiwyg-macro-body">```
fun isDevicePaired() {
    mobileDcApi
        .deviceService
        .isDevicePaired()
        {
           // return is device paired state
		},
		{throwable ->  
           // some error occurred, check exception
        }
}
```

</td></tr></tbody></table>

### unPairDevice

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="3b5a673b-4913-48fc-a8fa-2109156c02e5" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-39"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Removes all data collected by SDK and binding between user and device in Mobile DC backend.</p>

<p class="callout info">Pairing device to user can be made by &lt;&lt;pairBy...&gt;&gt; methods.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="2d274cb7-d7ff-43cb-8d45-5c66f70e21f2" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters-7"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="f45f933d-d457-4e35-a6e2-4ba9159c0256" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-26"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="b7021ba3-2ffd-47e7-980f-04c69342b040" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-fun-unpairdevice%28%29-%7B"><tbody><tr><td class="wysiwyg-macro-body">```
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
        })
}
```

</td></tr></tbody></table>

## Cloud messaging domain

### process

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a08899fb-56fd-4a6a-8d48-6cda5cec88b7" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-7" style="height: 175px; width: 100%;"><tbody><tr><td class="wysiwyg-macro-body" style="width: 99.8765%;"><p class="callout info">Asynchronous. Online. User login session not required.</p>

<p class="callout info">Method could perform background online actions eg. for VCP SDK token management.   
</p>

<p class="callout info">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.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-90"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">pushData</td><td class="confluenceTd">Map&lt;String, String&gt;</td><td class="confluenceTd">Data received from notification service in *RemoteMessage* object

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success%2Ffailure-call-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success/failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
//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 Verestro sender Id

    if (isVerestroSenderId(senderId)) {
        mobileDcApi
            .cloudMessagingService
            .process(pushData, {
               //push sent to SDK
            }, {
                //some error
            })

    } else {
        //proceed push from another source different then Verestro
    }
}
```

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="28e5697f-9e96-4bf0-9a9a-22065da37fb2" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%C2%A0-16"><tbody><tr><td class="wysiwyg-macro-body">  
</td></tr></tbody></table>

### getSource (Deprecated in 2.14.6)  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a08899fb-56fd-4a6a-8d48-6cda5cec88b7" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-offlin-8" style="height: 175px; width: 100%;"><tbody><tr><td class="wysiwyg-macro-body" style="width: 99.8765%;"><p class="callout info">Asynchronous. Offline.</p>

<p class="callout info">Checks Verestro Backend service source of push content.</p>

<p class="callout info">Application should check senderId in RemoteMessage object (RemoteMessage::from method) before passing data to this method.</p>

<p class="callout info">Deprecated, no longer required to use. Use simply method process() for push message providing.  
</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-91"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">pushData</td><td class="confluenceTd">Map&lt;String, String&gt;</td><td class="confluenceTd">Data received from notification service in *RemoteMessage* object

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-12"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with *source* of push.</p>

</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-92"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">source</td><td class="confluenceTd">String</td><td class="confluenceTd">Source of push content, where push data should be passed. Possible values: UCP

</td></tr></tbody></table>

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="9a1aecba-262a-443a-b44b-6bfa16a49156" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-failure-callback-6"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="28e5697f-9e96-4bf0-9a9a-22065da37fb2" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%2F%2Ffirebasemessagings-0"><tbody><tr><td class="wysiwyg-macro-body">```
//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<String, String>) {
    ucpApi
        .cloudMessagingService
        .process(pushData, {
            //push processed in UCP
        }, {
            //some error
        })
}
```

</td></tr></tbody></table>

### updateRegistrationToken  


<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="f1626ffe-a12b-447f-b149-7a02e012eaf1" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-40"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online. User login session not required  
</p>

<p class="callout info">Updates FCM Cloud Messaging registation token.</p>

<p class="callout info">Method should be called when application receive new registration token from FCM service.</p>

<p class="callout info">When updated application should still receive push notifications from Verestro Backend.</p>

<p class="callout info">Application should always retry update FCM Registration token if method failed.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-94" style="width: 100%;"><colgroup><col style="width: 29.1718%;"></col><col style="width: 30.1578%;"></col><col style="width: 24.1067%;"></col><col style="width: 16.5637%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">cloudMessagingRegistrationToken</td><td class="confluenceTd">CloudMessagingRegistrationToken</td><td class="confluenceTd">An object containing user information to update registration token</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

CloudMessagingRegistrationToken

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-95" style="width: 100%;"><colgroup><col style="width: 29.1718%;"></col><col style="width: 30.1607%;"></col><col style="width: 24.1038%;"></col><col style="width: 16.5637%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">type</td><td class="confluenceTd">CloudMessagingType</td><td class="confluenceTd">Mandatory. One of: \[FCM, EXTERNAL\].

FCM - Firebase Cloud Messaging  
EXTERNAL - External token for external source of RNS

</td><td class="confluenceTd">Not empty</td></tr><tr><td>token  
</td><td>String  
</td><td>Registration token

</td><td>Not empty  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="35d28b20-4678-4cd1-bc05-f634edb199b8" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-27"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="926bcb5a-198c-4e54-8349-39e6f1854961" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-%2F%2Fapplication-should"><tbody><tr><td class="wysiwyg-macro-body">```
//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
        })
}
```

</td></tr></tbody></table>

### updateFcmRegistrationToken (deprecated in 2.14.6)

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="f1626ffe-a12b-447f-b149-7a02e012eaf1" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-41"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Updates Cloud Messaging registation token for selected token type (FCM).</p>

<p class="callout info">Method should be called when application receive new registration token from FCM service.</p>

<p class="callout info">When updated application should still receive push notifications from Verestro Backend.</p>

<p class="callout info">Application should always retry update FCM Registration token if method failed.</p>

<p class="callout info">Deprecated, use updateRegistrationToken.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-96"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**

</th></tr><tr><td class="confluenceTd">fcmToken</td><td class="confluenceTd">String</td><td class="confluenceTd">Registration token received from FCM service

</td><td class="confluenceTd">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="35d28b20-4678-4cd1-bc05-f634edb199b8" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-%2F-failure-ca-28"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success / failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
//application should listen for FCM token changes in FirebaseMessagingService::onNewToken method

private fun updateFcmToken(newFcmToken: String) {
    mobileDcApi
        .deviceService
        .isDevicePaired({ isPaired ->
            //token update is required only if device is already paired
            if (isPaired) {
                mobileDcApi
                    .cloudMessagingService
                    .updateFcmRegistrationToken(newFcmToken, {
                        //token updated
                    }, {
                        //some error, always retry action until success
                        //when internet or server connection is not reachable try again later
                    })
            }
        }, {
            //some error
        })
```

## TransactionsHistory domain

### getTransactionsHistory

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-42"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="d014bdc7-2c29-4e0b-a454-68e89e83bd22">Provides transaction history from Mobile DC backend with selected transactions filters.  
</span></p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-97" style="width: 100%;"><colgroup><col style="width: 11.0012%;"></col><col style="width: 20.5175%;"></col><col style="width: 53.2773%;"></col><col style="width: 15.204%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">filters</td><td class="confluenceTd">TransactionsFilters?</td><td class="confluenceTd">Filters for transactions history. Leave null to get all user's transactions with limit equals 10</td><td class="confluenceTd">  
</td></tr><tr><td class="confluenceTd">nextPage</td><td class="confluenceTd">TransactionsNextPage?</td><td class="confluenceTd">Indicates starting point of downloaded transaction history

Pass null for first request or pass object from getTransactionHistory result

</td><td class="confluenceTd">  
</td></tr></tbody></table>

**TransactionsFilters**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-98" style="width: 100%; height: 945px;"><colgroup><col style="width: 17.02381%;"></col><col style="width: 11.547619%;"></col><col style="width: 60.595238%;"></col><col style="width: 10.714286%;"></col></colgroup><tbody><tr style="height: 45px;"><th class="confluenceTh" style="height: 45px;">**Parameter**</th><th class="confluenceTh" style="height: 45px;">**Type**</th><th class="confluenceTh" style="height: 45px;">**Description**</th><th class="confluenceTh" style="height: 45px;">**Validation conditions**</th></tr><tr style="height: 29px;"><td class="confluenceTd" style="height: 29px;">cardId</td><td class="confluenceTd" style="height: 29px;">String?</td><td class="confluenceTd" style="height: 29px;">Selected card id or null</td><td class="confluenceTd" style="height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">transactionId</span></td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">Transaction UUID</span></td><td style="height: 29px;">  
</td></tr><tr style="height: 45px;"><td class="confluenceTd" style="height: 45px;">paymentTokenId</td><td class="confluenceTd" style="height: 45px;">String?</td><td class="confluenceTd" style="height: 45px;">Selected paymentTokenId or null

Field is available in PaymentInstrument object in UCP module

</td><td class="confluenceTd" style="height: 45px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;">ibanId</td><td style="height: 29px;">String?</td><td style="height: 29px;">Selected iban id or null

</td><td style="height: 29px;">  
</td></tr><tr style="height: 45px;"><td class="confluenceTd" style="height: 45px;">area</td><td class="confluenceTd" style="height: 45px;">String?</td><td class="confluenceTd" style="height: 45px;">Area of transaction, specific per project (e.g. "UCP"). Could be null in order to avoid filtering by area of transaction.</td><td class="confluenceTd" style="height: 45px;">  
</td></tr><tr style="height: 77px;"><td class="confluenceTd" style="height: 77px;">timestampFrom</td><td class="confluenceTd" style="height: 77px;">String?</td><td class="confluenceTd" style="height: 77px;">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.</td><td class="confluenceTd" style="height: 77px;">  
</td></tr><tr style="height: 77px;"><td class="confluenceTd" style="height: 77px;">timestampTo</td><td class="confluenceTd" style="height: 77px;">String?</td><td class="confluenceTd" style="height: 77px;">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.</td><td class="confluenceTd" style="height: 77px;">  
</td></tr><tr style="height: 77px;"><td class="confluenceTd" style="height: 77px;">amountMinorMin</td><td class="confluenceTd" style="height: 77px;">Long?</td><td class="confluenceTd" style="height: 77px;">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.

</td><td class="confluenceTd" style="height: 77px;">  
</td></tr><tr style="height: 77px;"><td class="confluenceTd" style="height: 77px;">amountMinorMax</td><td class="confluenceTd" style="height: 77px;">Long?</td><td class="confluenceTd" style="height: 77px;">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.</td><td class="confluenceTd" style="height: 77px;">  
</td></tr><tr style="height: 45px;"><td class="confluenceTd" style="height: 45px;">amountType</td><td class="confluenceTd" style="height: 45px;">AmountType?</td><td class="confluenceTd" style="height: 45px;">Transaction amount type. One of POSITIVE, NEGATIVE</td><td class="confluenceTd" style="height: 45px;">  
</td></tr><tr style="height: 61px;"><td style="height: 61px;">contrahent</td><td style="height: 61px;">TransactionContrahent?</td><td style="height: 61px;">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

<span style="background-color: rgb(255, 255, 255);">Deprecated. Use contrahentIban, contrahentName, contrahentBic instead.</span>

</td><td style="height: 61px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;">description</td><td style="height: 29px;">String?</td><td style="height: 29px;">Description of transaction</td><td style="height: 29px;">  
</td></tr><tr style="height: 61px;"><td style="height: 61px;">status</td><td style="height: 61px;">Set&lt;String&gt;?</td><td style="height: 61px;">List of transaction statuses. Possible values: \[DECLINED, CLEARED, AUTHORIZED, REVERSED\]. For example: status=AUTHORIZED&amp;status=CLEARED</td><td style="height: 61px;">  
</td></tr><tr style="height: 29px;"><td class="confluenceTd" style="height: 29px;">limit</td><td class="confluenceTd" style="height: 29px;">Int?</td><td class="confluenceTd" style="height: 29px;">Limit of transactions to get. When not changed default value is 10</td><td class="confluenceTd" style="height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;">balanceId</td><td style="height: 29px;">String?</td><td style="height: 29px;" valign="top" width="253">Balance identifier

</td><td style="height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">deliveryMode</span></td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 29px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Transaction delivery mode \[STANDARD, EXPRESS\]</span>

</td><td style="height: 29px;">  
</td></tr><tr style="height: 45px;"><td style="height: 45px;"><span style="background-color: rgb(255, 255, 255);">paymentSystem</span></td><td style="height: 45px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 45px;"><span style="background-color: rgb(255, 255, 255);">Transaction payment system \[INTERNAL, INTERNAL\_BANK, SEPA, SORBNET, ELIXIR, ELIXIR\_EXPRESS, SWIFT\]</span>

</td><td style="height: 45px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">contrahentIban</span></td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 29px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Contrahent International Bank Account Number. The value must be an alphanumeric string (letters A-Z, a-z, and digits 0-9), without spaces and special characters.</span>

</td><td style="height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">contrahentName</span></td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 29px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Contrahent name</span>

</td><td style="height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">contrahentBic</span></td><td style="height: 29px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 29px;"><span style="background-color: rgb(255, 255, 255);">Contrahent Bank Identifier Code. The value must be an alphanumeric string (letters A-Z, a-z, and digits 0-9), without spaces and special characters.</span>

</td><td style="height: 29px;">  
</td></tr></tbody></table>

<span style="background-color: rgb(255, 255, 255);">**TransactionContrahent (Deprecated for TransactionFilters)**</span>

<table border="1" id="bkmrk-parameter-type-descr-99"><tbody><tr><td><span style="background-color: rgb(255, 255, 255);">**Parameter**</span></td><td><span style="background-color: rgb(255, 255, 255);">**Type**</span></td><td><span style="background-color: rgb(255, 255, 255);">**Description**</span></td><td><span style="background-color: rgb(255, 255, 255);">**Validation conditions**</span></td></tr><tr><td><span style="background-color: rgb(255, 255, 255);">iban</span></td><td><span style="background-color: rgb(255, 255, 255);">String</span></td><td><span style="background-color: rgb(255, 255, 255);">Contrahent International Bank Account Number</span></td><td>  
</td></tr><tr><td><span style="background-color: rgb(255, 255, 255);">bic</span></td><td><span style="background-color: rgb(255, 255, 255);">String</span></td><td><span style="background-color: rgb(255, 255, 255);">Contrahent Bank Identifier Code</span></td><td>  
</td></tr><tr><td><span style="background-color: rgb(255, 255, 255);">name</span></td><td><span style="background-color: rgb(255, 255, 255);">String</span></td><td><span style="background-color: rgb(255, 255, 255);">Contrahent name</span></td><td>  
</td></tr></tbody></table>

**TransactionsNextPage**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-100"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">seekId</td><td class="confluenceTd">String</td><td class="confluenceTd">Seek id of next transaction</td><td class="confluenceTd">  
</td></tr><tr><td class="confluenceTd">seekTimestamp</td><td class="confluenceTd">String</td><td class="confluenceTd">Seek timestamp of next transaction</td><td class="confluenceTd">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-13"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with list of transactions history.</p>

</td></tr></tbody></table>

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-101" style="width: 100%;"><colgroup><col style="width: 18.1665%;"></col><col style="width: 11.6234%;"></col><col style="width: 70.2101%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">transactionHistory</td><td class="confluenceTd" colspan="1">TransactionHistory</td><td class="confluenceTd" colspan="1">An object containing list of TransactionDetails and TransactionNextPage to show transaction history</td></tr></tbody></table>

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-102" style="width: 89.8765%;"><colgroup><col style="width: 19.7917%;"></col><col style="width: 30.9028%;"></col><col style="width: 49.3056%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**

</th></tr><tr><td class="confluenceTd">transactions</td><td class="confluenceTd">List&lt;TransactionDetails&gt;</td><td class="confluenceTd">List of transactions history</td></tr><tr><td class="confluenceTd">nextPage</td><td class="confluenceTd">TransactionsNextPage?</td><td class="confluenceTd">Object for getting next transactions history items</td></tr></tbody></table>

**TransactionDetails**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-8" style="width: 100%; height: 2234px;"><colgroup><col style="width: 18.452381%;"></col><col style="width: 11.309524%;"></col><col style="width: 70.119048%;"></col></colgroup><tbody><tr style="height: 34px;"><th class="confluenceTh" style="height: 34px;">**Field**</th><th class="confluenceTh" style="height: 34px;">**Type**</th><th class="confluenceTh" style="height: 34px;">**Description**</th></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">id</td><td class="confluenceTd" style="height: 34px;">Long</td><td class="confluenceTd" style="height: 34px;">Internal transaction id</td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">transactionId</span></td><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">String</span></td><td style="height: 34px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Transaction UUID</span>

</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">clientTransactionId</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">Client id of transaction</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">amountMinor</td><td class="confluenceTd" style="height: 54px;">Long</td><td class="confluenceTd" style="height: 54px;">The transaction monetary count in terms of the minor units of the currency</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">currency</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">Currency of the transaction amount. 3-digits ISO 4217 currency code</td></tr><tr style="height: 74px;"><td class="confluenceTd" style="height: 74px;">type</td><td class="confluenceTd" style="height: 74px;">String</td><td class="confluenceTd" style="height: 74px;">Transaction type. One of: PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">status</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">Transaction status. One of: DECLINED, CLEARED, AUTHORIZED, REVERSED</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">timestamp</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">The date/time when the transaction occurred. In ISO8601 extended format</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">description</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Description of transaction</td></tr><tr style="height: 34px;"><td style="height: 34px;">comment</td><td style="height: 34px;">String?</td><td style="height: 34px;">Comment for the transaction</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">cardId</td><td class="confluenceTd" style="height: 34px;">Long?</td><td class="confluenceTd" style="height: 34px;">Card id of transaction</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">paymentTokenId</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">Id of payment token</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">cardLastFourDigits</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">Last four digits of card</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">merchantName</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">The merchant name. Deprecated, please use contrahent.name field</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">merchantPostalCode</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">The postal code of the merchant</td></tr><tr style="height: 54px;"><td style="height: 54px;">merchantTransactionId</td><td style="height: 54px;">String?</td><td style="height: 54px;">Identifier given by merchant for transaction</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">transactionCountryCode</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">The country in which the transaction was performed. Expressed as a 3-letter country code as defined in ISO 3166-1</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">comboCardAccountType</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">Indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: CREDIT, DEBIT</td></tr><tr style="height: 194px;"><td class="confluenceTd" style="height: 194px;">issuerResponseInformation</td><td class="confluenceTd" style="height: 194px;">String?</td><td class="confluenceTd" style="height: 194px;">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

</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">transactionChannel</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">Information about transaction channel. One of: CONTACTLESS, CLOUD, MONEYSEND

</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">ibanId</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Id of iban as *sha256Hex*</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">mcc</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">4 digits merchant category code</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">mccCategory</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Category of merchant category code</td></tr><tr style="height: 94px;"><td style="height: 94px;">originalAmountMinor</td><td style="height: 94px;">Long?</td><td style="height: 94px;">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</td></tr><tr style="height: 54px;"><td style="height: 54px;">originalCurrency</td><td style="height: 54px;">String?  
</td><td style="height: 54px;">3-character ISO 4217 original currency code of the transaction</td></tr><tr style="height: 34px;"><td style="height: 34px;">exchangeRate</td><td style="height: 34px;">Double?  
</td><td style="height: 34px;">Exchange rate of the original currency into the base currency</td></tr><tr style="height: 74px;"><td style="height: 74px;">balanceMinorValueAfterTransaction</td><td style="height: 74px;">Long?  
</td><td style="height: 74px;">Account balance value after transaction in terms of the minor units</td></tr><tr style="height: 54px;"><td style="height: 54px;">commissionMinorValue</td><td style="height: 54px;">Long?  
</td><td style="height: 54px;">Commission value in terms of the minor units</td></tr><tr style="height: 54px;"><td style="height: 54px;">clearingTimestamp</td><td style="height: 54px;">String?</td><td style="height: 54px;">The date/time when the transaction changed status on CLEARED. In ISO 8601 extended format</td></tr><tr style="height: 74px;"><td style="height: 74px;">contrahent</td><td style="height: 74px;">TransactionContrahent?  
</td><td style="height: 74px;">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</td></tr><tr style="height: 34px;"><td style="height: 34px;">parentId</td><td style="height: 34px;">Long?  
</td><td style="height: 34px;">Id of base transaction</td></tr><tr style="height: 54px;"><td style="height: 54px;">attachmentStatus</td><td style="height: 54px;">String?  
</td><td style="height: 54px;">Attachment status of transaction. One of: \[EMPTY, INCORRECT, TO\_APPROVE, APPROVED\]</td></tr><tr style="height: 74px;"><td style="height: 74px;">incorrectAttachmentStatusReason</td><td style="height: 74px;">String?  
</td><td style="height: 74px;">Reason of INCORRECT attachment status. Required only for this status. One of: \[ATTACHMENT\_UNREADABLE, ATTACHMENT\_INCORRECT, OTHER\]</td></tr><tr style="height: 94px;"><td style="height: 94px;">categoriesInfo</td><td style="height: 94px;">TransactionCategoriesInfo?</td><td style="height: 94px;">Transaction categories</td></tr><tr style="height: 54px;"><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">walletReference</span></td><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">In the case of a transaction with a digitized card, this field contains information from which xPay was initiated.</span></td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">balanceId</span></td><td style="height: 34px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 34px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Balance identifier</span>

</td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">deliveryMode</span></td><td style="height: 34px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 34px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Transaction delivery mode \[STANDARD, EXPRESS\]</span>

</td></tr><tr style="height: 54px;"><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">paymentSystem</span></td><td style="height: 54px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 54px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Transaction payment system \[INTERNAL, INTERNAL\_BANK, SEPA, SORBNET, ELIXIR, ELIXIR\_EXPRESS, SWIFT\]</span>

</td></tr><tr style="height: 54px;"><td style="height: 54px;" valign="top" width="142"><span style="background-color: rgb(255, 255, 255);">walletReference</span>

</td><td style="height: 54px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 54px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">In the case of a transaction with a digitized card, this field contains information from which xPay was initiated.</span>

</td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">riskScore</span>

</td><td style="height: 34px;" valign="top" width="145"><span style="background-color: rgb(255, 255, 255);">Long?</span>

</td><td style="height: 34px;" valign="top" width="253"><span style="background-color: rgb(255, 255, 255);">Score a transaction for AML risk</span>

</td></tr></tbody></table>

<span style="background-color: rgb(255, 255, 255);">**TransactionContrahent**</span>

<table border="1" id="bkmrk-parameter-type-descr-103" style="width: 100%;"><tbody><tr><td style="width: 13.603819%;"><span style="background-color: rgb(255, 255, 255);">**Parameter**</span></td><td style="width: 12.284635%;"><span style="background-color: rgb(255, 255, 255);">**Type**</span></td><td style="width: 48.574554%;"><span style="background-color: rgb(255, 255, 255);">**Description**</span></td><td style="width: 25.536993%;"><span style="background-color: rgb(255, 255, 255);">**Validation conditions**</span></td></tr><tr><td style="width: 13.603819%;"><span style="background-color: rgb(255, 255, 255);">iban</span></td><td style="width: 12.284635%;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="width: 48.574554%;"><span style="background-color: rgb(255, 255, 255);">Contrahent International Bank Account Number</span></td><td style="width: 25.536993%;">  
</td></tr><tr><td style="width: 13.603819%;"><span style="background-color: rgb(255, 255, 255);">bic</span></td><td style="width: 12.284635%;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="width: 48.574554%;"><span style="background-color: rgb(255, 255, 255);">Contrahent Bank Identifier Code</span></td><td style="width: 25.536993%;">  
</td></tr><tr><td style="width: 13.603819%;"><span style="background-color: rgb(255, 255, 255);">name</span></td><td style="width: 12.284635%;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="width: 48.574554%;"><span style="background-color: rgb(255, 255, 255);">Contrahent name</span></td><td style="width: 25.536993%;">  
</td></tr><tr><td style="width: 13.603819%;"><span style="background-color: rgb(255, 255, 255);">address</span></td><td style="width: 12.284635%;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="width: 48.574554%;"><span style="background-color: rgb(255, 255, 255);">Contrahent address</span></td><td style="width: 25.536993%;">  
</td></tr></tbody></table>

<span style="background-color: rgb(255, 255, 255);">**TransactionCategoriesInfo**</span>

<table border="1" id="bkmrk-parameter-type-descr-104"><tbody><tr><td>**Parameter**</td><td>**Type**</td><td>**Description**</td><td>**Validation conditions**</td></tr><tr><td>categories</td><td>List&lt;TransactionCategory&gt;?</td><td>Transaction categories list</td><td>  
</td></tr></tbody></table>

**TransactionCategory**

<table border="1" id="bkmrk-parameter-type-descr-105" style="width: 100%;"><tbody><tr><td style="width: 10.754%;">**Parameter**</td><td style="width: 9.88372%;">**Type**</td><td style="width: 63.4167%;">**Description**</td><td style="width: 15.9456%;">**Validation conditions**</td></tr><tr><td style="width: 10.754%;">id</td><td style="width: 9.88372%;">Long</td><td style="width: 63.4167%;">Category id</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">amountMinor</td><td style="width: 9.88372%;">Long</td><td style="width: 63.4167%;">Part of the transaction monetary amount which is related to the given category (minor units of the currency)</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">idName</td><td style="width: 9.88372%;">String</td><td style="width: 63.4167%;">Category name</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">name</td><td style="width: 9.88372%;">String</td><td style="width: 63.4167%;">Category name in the language that was sent in the request header</td><td style="width: 15.9456%;">  
</td></tr></tbody></table>

**TransactionsNextPage**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-106"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">seekId</td><td class="confluenceTd">String</td><td class="confluenceTd">Seek id of next transaction</td><td class="confluenceTd">  
</td></tr><tr><td class="confluenceTd">seekTimestamp</td><td class="confluenceTd">String</td><td class="confluenceTd">Seek timestamp of next transaction</td><td class="confluenceTd">  
</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6ad54252-40fd-478e-b5c5-1f5e0e53c4f5" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-%2F%2Fsample-filters-val"><tbody><tr><td class="wysiwyg-macro-body">```
//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
            })
}
```

</td></tr></tbody></table>

### getTransactionDetails

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-43"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="d014bdc7-2c29-4e0b-a454-68e89e83bd22">Provides transaction details from Mobile DC backend for selected transactionId.  
</span></p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-107" style="width: 100%;"><colgroup><col style="width: 18.9122%;"></col><col style="width: 21.1325%;"></col><col style="width: 27.446%;"></col><col style="width: 32.5093%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">getTransactionDetails</td><td class="confluenceTd">GetTransactionDetails</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="de9e84bc-c339-467e-b2f4-e5ab2bd83f78">Contains id for requested transactionId</span></td><td class="confluenceTd">transactionId greater than 0 and not null</td></tr></tbody></table>

**GetTransactionDetails**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-108" style="width: 100.37%;"><colgroup><col style="width: 18.9214%;"></col><col style="width: 20.8808%;"></col><col style="width: 27.4413%;"></col><col style="width: 32.7565%;"></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">transactionId</td><td class="confluenceTd">Long</td><td class="confluenceTd"><span class="inline-comment-marker" data-ref="54903450-46ae-443f-a363-47a20c244035">Selected id of transaction</span></td><td class="confluenceTd">Greater than 0 and not null</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-14"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with transaction details.</p>

</td></tr></tbody></table>

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-109"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">getTransactionDetailsResult</td><td class="confluenceTd" colspan="1">GetTransactionDetailsResult</td><td class="confluenceTd" colspan="1">An object containing details for requested transaction</td></tr></tbody></table>

**GetTransactionDetailsResult**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-9" style="width: 100%; height: 2362px;"><colgroup><col style="width: 23.928571%;"></col><col style="width: 16.309524%;"></col><col style="width: 59.642857%;"></col></colgroup><tbody><tr style="height: 34px;"><th class="confluenceTh" style="height: 34px;">**Field**</th><th class="confluenceTh" style="height: 34px;">**Type**</th><th class="confluenceTh" style="height: 34px;">**Description**</th></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">id</td><td class="confluenceTd" style="height: 34px;">Long</td><td class="confluenceTd" style="height: 34px;">Internal transaction id</td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">transactionId</span></td><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">String</span></td><td style="height: 34px;" valign="top"><span style="background-color: rgb(255, 255, 255);">Unique transaction UUID</span>

</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">clientTransactionId</td><td class="confluenceTd" style="height: 34px;">String</td><td class="confluenceTd" style="height: 34px;">Client id of transaction</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">amountMinor</td><td class="confluenceTd" style="height: 54px;">Long</td><td class="confluenceTd" style="height: 54px;">The transaction monetary count in terms of the minor units of the currency</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">currency</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">Currency of the transaction amount. 3-digits ISO 4217 currency code</td></tr><tr style="height: 94px;"><td class="confluenceTd" style="height: 94px;">type</td><td class="confluenceTd" style="height: 94px;">String</td><td class="confluenceTd" style="height: 94px;">Transaction type. One of: PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">status</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">Transaction status. One of: DECLINED, CLEARED, AUTHORIZED, REVERSED</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">timestamp</td><td class="confluenceTd" style="height: 54px;">String</td><td class="confluenceTd" style="height: 54px;">The date/time when the transaction occurred. In ISO8601 extended format</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">description</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Description of transaction</td></tr><tr style="height: 34px;"><td style="height: 34px;">comment</td><td style="height: 34px;">String?</td><td style="height: 34px;">Comment for the transaction</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">cardId</td><td class="confluenceTd" style="height: 34px;">Long?</td><td class="confluenceTd" style="height: 34px;">Card id of transaction</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">paymentTokenId</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Id of payment token</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">cardLastFourDigits</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Last four digits of card</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">merchantName</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">The merchant name. Deprecated, please use contrahent.name field</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">merchantPostalCode</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">The postal code of the merchant</td></tr><tr style="height: 74px;"><td class="confluenceTd" style="height: 74px;">transactionCountryCode</td><td class="confluenceTd" style="height: 74px;">String?</td><td class="confluenceTd" style="height: 74px;">The country in which the transaction was performed. Expressed as a 3-letter country code as defined in ISO 3166-1</td></tr><tr style="height: 74px;"><td class="confluenceTd" style="height: 74px;">comboCardAccountType</td><td class="confluenceTd" style="height: 74px;">String?</td><td class="confluenceTd" style="height: 74px;">Indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: CREDIT, DEBIT</td></tr><tr style="height: 234px;"><td class="confluenceTd" style="height: 234px;">issuerResponseInformation</td><td class="confluenceTd" style="height: 234px;">String?</td><td class="confluenceTd" style="height: 234px;">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

</td></tr><tr style="height: 54px;"><td class="confluenceTd" style="height: 54px;">transactionChannel</td><td class="confluenceTd" style="height: 54px;">String?</td><td class="confluenceTd" style="height: 54px;">Information about transaction channel. One of: CONTACTLESS, CLOUD, MONEYSEND

</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">ibanId</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Id of iban as *sha256Hex*</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;"><span class="inline-comment-marker" data-ref="9d402d21-64fa-4fc5-b380-53ff7f8c0108">mcc</span></td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">4 digits merchant category code</td></tr><tr style="height: 34px;"><td class="confluenceTd" style="height: 34px;">mccCategory</td><td class="confluenceTd" style="height: 34px;">String?</td><td class="confluenceTd" style="height: 34px;">Category of merchant category code</td></tr><tr style="height: 94px;"><td style="height: 94px;">originalAmountMinor</td><td style="height: 94px;">Long?</td><td style="height: 94px;">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</td></tr><tr style="height: 54px;"><td style="height: 54px;">originalCurrency</td><td style="height: 54px;">String?  
</td><td style="height: 54px;">3-character ISO 4217 original currency code of the transaction</td></tr><tr style="height: 54px;"><td style="height: 54px;">exchangeRate</td><td style="height: 54px;">Double?  
</td><td style="height: 54px;">Exchange rate of the original currency into the base currency</td></tr><tr style="height: 54px;"><td style="height: 54px;">balanceMinorValueAfterTransaction</td><td style="height: 54px;">Long?  
</td><td style="height: 54px;">Account balance value after transaction in terms of the minor units</td></tr><tr style="height: 54px;"><td style="height: 54px;">commissionMinorValue</td><td style="height: 54px;">Long?  
</td><td style="height: 54px;">Commission value in terms of the minor units</td></tr><tr style="height: 82px;"><td style="height: 82px;">clearingTimestamp</td><td style="height: 82px;">String?  
</td><td style="height: 82px;">The date/time when the transaction changed status on CLEARED. In ISO 8601 extended format</td></tr><tr style="height: 34px;"><td style="height: 34px;">parentId</td><td style="height: 34px;">Long?  
</td><td style="height: 34px;">Id of base transaction</td></tr><tr style="height: 94px;"><td style="height: 94px;">contrahent</td><td style="height: 94px;">TransactionContrahent?</td><td style="height: 94px;">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</td></tr><tr style="height: 54px;"><td style="height: 54px;">attachmentStatus</td><td style="height: 54px;">String?  
</td><td style="height: 54px;">Attachment status of transaction. One of: \[EMPTY, INCORRECT, TO\_APPROVE, APPROVED\]</td></tr><tr style="height: 94px;"><td style="height: 94px;">incorrectAttachmentStatusReason</td><td style="height: 94px;">String?  
</td><td style="height: 94px;">Reason of INCORRECT attachment status. Required only for this status. One of: \[ATTACHMENT\_UNREADABLE, ATTACHMENT\_INCORRECT, OTHER\]</td></tr><tr style="height: 74px;"><td style="height: 74px;">attachments  
</td><td style="height: 74px;">List&lt;TransactionDetails  
Attachment&gt;  
</td><td style="height: 74px;">Transaction attachments list  
</td></tr><tr style="height: 74px;"><td style="height: 74px;">categoriesInfo</td><td style="height: 74px;">TransactionCategoriesInfo?</td><td style="height: 74px;">Transaction categories</td></tr><tr style="height: 74px;"><td style="height: 74px;">walletReference</td><td style="height: 74px;">String?</td><td style="height: 74px;">In the case of a transaction with a digitized card, this field contains information from which xPay was initiated.</td></tr><tr style="height: 54px;"><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">partialReversals</span></td><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">List&lt;PartialReversal&gt;?</span></td><td style="height: 54px;"><span style="background-color: rgb(255, 255, 255);">Transaction partial reversals list</span></td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">deliveryMode</span></td><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">Transaction delivery mode \[STANDARD, EXPRESS\]</span></td></tr><tr style="height: 74px;"><td style="height: 74px;"><span style="background-color: rgb(255, 255, 255);">paymentSystem</span></td><td style="height: 74px;"><span style="background-color: rgb(255, 255, 255);">String?</span></td><td style="height: 74px;"><span style="background-color: rgb(255, 255, 255);">Transaction payment system \[INTERNAL, INTERNAL\_BANK, SEPA, SORBNET, ELIXIR, ELIXIR\_EXPRESS, SWIFT\]</span></td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">riskScore</span></td><td style="height: 34px;" valign="top"><span style="background-color: rgb(255, 255, 255);">Long?</span>

</td><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">Score a transaction for AML risk</span></td></tr><tr style="height: 34px;"><td style="height: 34px;"><span style="background-color: rgb(255, 255, 255);">merchantId</span></td><td style="height: 34px;" valign="top"><span style="background-color: rgb(255, 255, 255);">String?</span>

</td><td style="height: 34px;" valign="top"><span style="background-color: rgb(255, 255, 255);"><span class="apple-converted-space"> </span>Merchant identifier</span>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="82b7f0d4-a085-40ee-b730-5ce1ff173ee1">TransactionDetailsAttachment</span>**

<table class="confluenceTable wrapped" id="bkmrk-parameter-type-descr-110" style="width: 100%;"><colgroup><col style="width: 14.4623%;"></col><col style="width: 10.1315%;"></col><col style="width: 75.4062%;"></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th></tr><tr><td class="confluenceTd" colspan="1">id</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Attachment id</td></tr><tr><td class="confluenceTd" colspan="1">name</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">File name</td></tr><tr><td class="confluenceTd" colspan="1">mimeType</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Mime type</td></tr><tr><td class="confluenceTd" colspan="1">link</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">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</td></tr><tr><td class="confluenceTd" colspan="1">linkExpirationDate</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Url expiration date for given link in ISO 8601 extended format. Given link will be valid only short period of time</td></tr></tbody></table>

**TransactionCategoriesInfo**

<table border="1" id="bkmrk-parameter-type-descr-111"><tbody><tr><td>**Parameter**</td><td>**Type**</td><td>**Description**</td><td>**Validation conditions**</td></tr><tr><td>categories</td><td>List&lt;TransactionCategory&gt;?</td><td>Transaction categories list</td><td>  
</td></tr></tbody></table>

**TransactionCategory**

<table border="1" id="bkmrk-parameter-type-descr-112" style="width: 100%;"><tbody><tr><td style="width: 10.754%;">**Parameter**</td><td style="width: 10.387%;">**Type**</td><td style="width: 62.9134%;">**Description**</td><td style="width: 15.9456%;">**Validation conditions**</td></tr><tr><td style="width: 10.754%;">id</td><td style="width: 10.387%;">Long</td><td style="width: 62.9134%;">Category id</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">amountMinor</td><td style="width: 10.387%;">Long</td><td style="width: 62.9134%;">Part of the transaction monetary amount which is related to the given category (minor units of the currency)</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">idName</td><td style="width: 10.387%;">String</td><td style="width: 62.9134%;">Category name</td><td style="width: 15.9456%;">  
</td></tr><tr><td style="width: 10.754%;">name</td><td style="width: 10.387%;">String</td><td style="width: 62.9134%;">Category name in the language that was sent in the request header</td><td style="width: 15.9456%;">  
</td></tr></tbody></table>

**PartialReversal**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-113" style="width: 100%;"><tbody><tr><th class="confluenceTh" style="width: 19.1595%;">**Parameter**</th><th class="confluenceTh" style="width: 12.3541%;">**Type**</th><th class="confluenceTh" style="width: 53.777%;">**Description**</th><th class="confluenceTh" style="width: 14.7095%;">**Validation conditions**</th></tr><tr><td class="confluenceTd" style="width: 19.1595%;">amountMinor</td><td class="confluenceTd" style="width: 12.3541%;">Double</td><td class="confluenceTd" style="width: 53.777%;">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</td><td class="confluenceTd" style="width: 14.7095%;">  
</td></tr><tr><td class="confluenceTd" style="width: 19.1595%;">currency</td><td class="confluenceTd" style="width: 12.3541%;">String</td><td class="confluenceTd" style="width: 53.777%;">3-character ISO 4217 currency code of the transaction reversal</td><td class="confluenceTd" style="width: 14.7095%;">  
</td></tr><tr><td style="width: 19.1595%;">date</td><td style="width: 12.3541%;">String</td><td style="width: 53.777%;">The date/time of the transaction reversal. In ISO 8601 extended format</td><td style="width: 14.7095%;">  
</td></tr><tr><td style="width: 19.1595%;">balanceMinorValueAfterTransaction</td><td style="width: 12.3541%;">Double</td><td style="width: 53.777%;">Account balance value after transaction reversal in terms of the minor units</td><td style="width: 14.7095%;">  
</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6ad54252-40fd-478e-b5c5-1f5e0e53c4f5" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-%2F%2Fsample-entry-data-"><tbody><tr><td class="wysiwyg-macro-body">```
//sample entry data
val getTransactionDetails = GetTransactionDetails(1210L)

fun getTransactionDetails(getTransactionDetails: GetTransactionDetails) {
    mobileDcApi
        .transactionsHistoryService
		.getTransactionDetails(getTransactionDetails, { getTransactionDetailsResult ->
                //succes
            }, {
                //something went wrong, check exception
            })
}
```

</td></tr></tbody></table>

### storeAttachment

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-44"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="d014bdc7-2c29-4e0b-a454-68e89e83bd22">Stores attachment file in Mobile DC backend for selected transactionId.  
</span></p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-114"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">transactionAttachment</td><td class="confluenceTd">TransactionAttachment</td><td class="confluenceTd">Contains all data required to save attachment</td></tr></tbody></table>

**TransactionAttachment**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-115"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh">**Validation conditions**</th></tr><tr><td class="confluenceTd">transactionId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Selected id of transaction</td><td class="confluenceTd">not null and greater or equal 0</td></tr><tr><td class="confluenceTd" colspan="1">attachmentInputStream</td><td class="confluenceTd" colspan="1">InputStream</td><td class="confluenceTd" colspan="1">Stream of file data</td><td class="confluenceTd" colspan="1">not null</td></tr><tr><td class="confluenceTd" colspan="1">mimeType</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="50414dc9-eb9b-4e64-a3b4-ebeade9cb080">MIME type of file. For example image/jpeg image/png</span></td><td class="confluenceTd" colspan="1">Is not empty</td></tr><tr><td class="confluenceTd" colspan="1">fileName</td><td class="confluenceTd" colspan="1">String?</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="d407bbcb-ffb2-4b81-a1c6-6187cc67e5c4">Name of file. If null or blank then it is generated randomly with unique name. File extension is optional.</span></td><td class="confluenceTd" colspan="1">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-1"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback.</p>

</td></tr></tbody></table>

**Sample**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6ad54252-40fd-478e-b5c5-1f5e0e53c4f5" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-%2F%2Fsample-entry-data--0"><tbody><tr><td class="wysiwyg-macro-body">```
//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
            })
}

```

</td></tr></tbody></table>

### generateAttachmentLink

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-45"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info"><span class="inline-comment-marker" data-ref="d014bdc7-2c29-4e0b-a454-68e89e83bd22">Provides new link to load attachment when existing one fails with 403 HTTP status.</span></p>

</td></tr></tbody></table>

**Input**

<table class="wrapped relative-table confluenceTable" id="bkmrk-parameter-type-descr-116"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">generateAttachmentLink

</td><td class="confluenceTd">GenerateAttachmentLink

</td><td class="confluenceTd">Contains transactionId and attachmentId</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="ac253e8b-dea6-4975-9ed1-62c07858b52c">GenerateAttachmentLink</span>**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-117"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">Parameter</th><th class="confluenceTh">Type</th><th class="confluenceTh">Description</th><th class="confluenceTh">Validation conditions</th></tr><tr><td class="confluenceTd">transactionId</td><td class="confluenceTd">Long</td><td class="confluenceTd">Selected id of transaction</td><td class="confluenceTd">not null and greater or equal 0</td></tr><tr><td class="confluenceTd" colspan="1">attachmentId</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1">Selected attachment ID</td><td class="confluenceTd" colspan="1">is not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-15"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with new attachment link and expiration date.</p>

</td></tr></tbody></table>

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-118"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">generateAttachmentLinkResult</td><td class="confluenceTd" colspan="1">GenerateAttachmentLinkResult</td><td class="confluenceTd" colspan="1">An object containing new link and link expiry date</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="007ba296-09e9-4b16-a423-61b75c9eca94">GenerateAttachmentLinkResult</span>**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-10"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Field**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd">link</td><td class="confluenceTd">String</td><td class="confluenceTd">Url address</td></tr><tr><td class="confluenceTd">linkExpirationDate</td><td class="confluenceTd">String</td><td class="confluenceTd">Url expiration date for given link in ISO 8601 extended format. Given link will be valid only short period of time</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="cee97680-b5a5-45ca-a6d6-cc2508a6063f">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="6ad54252-40fd-478e-b5c5-1f5e0e53c4f5" data-macro-name="code" data-macro-schema-version="1" id="bkmrk-%2F%2Fsample-entry-data--1"><tbody><tr><td class="wysiwyg-macro-body">```
//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<TransactionDetailsAttachment> = getTransactionDetailsResult.attachments
	attachments.forEach { transactionDetailAttachment ->
		loadImage(getTransactionDetailsResult.id, transactionDetailAttachment)
	}
}


private fun loadImage(attachment: TransactionDetailsAttachment, transactionId: Long) {
    //downloading file may differ in your project. This is only example in synchronised code
    val request = Request.Builder().url(attachment.link).build()
    val response = OkHttpClient().newCall(request).execute()
    val httpCode = response.code()
    when (httpCode) {
        403 -> {
            refreshAttachment(transactionId, attachment.id)
        }
        200 -> {
            //convert stream to bitmap and load into image view
        }
        else -> {
            //check other status
        }
    }
}

private fun refreshAttachment(transactionId: Long, attachmentId: String) {
    mobileDcApi
        .transactionsHistoryService
        .generateAttachmentLink(
            GenerateAttachmentLink(transactionId, attachmentId), { generateAttachmentLinkResult ->
				//sample with Glide library usage
				Glide.with(context).asBitmap()
					.load(generateAttachmentLinkResult.link)
					.into(nextImageView)
      	}, {
           //something went wrong, check exception
        })
}
```

</td></tr></tbody></table>

### deleteAttachment

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b6521ea5-fcb7-4b2d-bb43-bed6b3d36ace" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-46"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Delete attachment associated with provided transa<span class="inline-comment-marker" data-ref="9d791dca-ba39-4c37-b255-d74d8678d6a2">ction.</span></p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-119" style="width: 77.1605%; height: 96.1876px;"><colgroup><col style="width: 20.32%;"></col><col style="width: 20.64%;"></col><col style="width: 35.36%;"></col><col style="width: 23.36%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><th class="confluenceTh" style="height: 46.5938px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5938px;">**Type**</th><th class="confluenceTh" style="height: 46.5938px;">**Description**</th><th class="confluenceTh" colspan="1" style="height: 46.5938px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd" colspan="1" style="height: 49.5938px;">deleteAttachment</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">DeleteAttachment</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">Plain object of DeleteAttachment

</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">Not empty</td></tr></tbody></table>

**DeleteAttachment** object contains following fields.

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-120"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th><th class="confluenceTh" colspan="1">**Validation conditions**</th></tr><tr><td class="confluenceTd" colspan="1">transactionId</td><td class="confluenceTd" colspan="1">Long</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="56fea856-c937-4384-8eed-c82cf68c4707">Identifier of selected transaction. Id can be taken from GetTransactionDetailsResult object, check [getTransactionDetails](https://wiki.verestro.com/display/UCP/getTransactionDetails) method  
</span>

</td><td class="confluenceTd" colspan="1">Not empty</td></tr><tr><td class="confluenceTd" colspan="1">attachmentId</td><td class="confluenceTd" colspan="1">String</td><td class="confluenceTd" colspan="1"><span class="inline-comment-marker" data-ref="cf6f7c75-04fd-4886-bffc-66760a2cf6d8">Identifier of selected attachment. Id can be taken from TransactionDetailsAttachment, check [getTransactionDetails](https://wiki.verestro.com/display/UCP/getTransactionDetails) method  
</span></td><td class="confluenceTd" colspan="1">Not empty</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-3"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="ee3ba144-2030-4661-b02f-95315f9ebcc2">Sample</span>**

<table class="wysiwyg-macro" data-macro-body-type="PLAIN_TEXT" data-macro-id="8df40eef-c58c-4cd5-9453-d934b38c602e" data-macro-name="code" data-macro-parameters="theme=Eclipse" data-macro-schema-version="1" id="bkmrk-val-transactiondetai"><tbody><tr><td class="wysiwyg-macro-body">```
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
            })
}
```

</td></tr></tbody></table>

### updateSingleTransactionData

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b6521ea5-fcb7-4b2d-bb43-bed6b3d36ace" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-47"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Updates single transaction data in Mobile DC backend by transactionId.</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-121" style="width: 107.901%; height: 96.1876px;"><colgroup><col style="width: 26.0816%;"></col><col style="width: 25.3399%;"></col><col style="width: 30.2985%;"></col><col style="width: 18.28%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><th class="confluenceTh" style="height: 46.5938px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5938px;">**Type**</th><th class="confluenceTh" style="height: 46.5938px;">**Description**</th><th class="confluenceTh" style="height: 46.5938px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd mceSelected">updateSingleTransactionData

</td><td class="confluenceTd mceSelected">UpdateSingleTransactionData

</td><td class="confluenceTd mceSelected">Transaction data to be updated</td><td class="confluenceTd mceSelected">Not empty</td></tr></tbody></table>

**UpdateSingleTransactionData**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-122" style="width: 100%; height: 96.1876px;"><colgroup><col style="width: 26.0816%;"></col><col style="width: 25.3399%;"></col><col style="width: 30.2843%;"></col><col style="width: 18.2942%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><th class="confluenceTh" style="height: 46.5938px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5938px;">**Type**</th><th class="confluenceTh" style="height: 46.5938px;">**Description**</th><th class="confluenceTh" style="height: 46.5938px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd mceSelected">transactionId

</td><td class="confluenceTd mceSelected">Long

</td><td class="confluenceTd mceSelected">Transaction ID</td><td class="confluenceTd mceSelected">Not empty</td></tr><tr><td>description

</td><td>String?

</td><td>Description of transaction</td><td>  
</td></tr><tr><td>comment

</td><td>String

</td><td>Comment for the transaction</td><td>  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-4"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
fun updateSingleTransactionData(updateSingleTransactionData: UpdateSingleTransactionData) {
    mobileDcApi
        .transactionsHistoryService
        .updateSingleTransactionData(updateSingleTransactionData, {
            //Transaction updated successfully
        }, {
            //Something went wrong, check exception with documentation
        })
}
```


### updateTransactionCategory

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b6521ea5-fcb7-4b2d-bb43-bed6b3d36ace" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-48"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">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).</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-123" style="width: 100%; height: 96.6563px;"><colgroup><col style="width: 26.0923%;"></col><col style="width: 25.3504%;"></col><col style="width: 30.2968%;"></col><col style="width: 18.3017%;"></col></colgroup><tbody><tr style="height: 47.0625px;"><th class="confluenceTh" style="height: 47.0625px;">**Parameter**</th><th class="confluenceTh" style="height: 47.0625px;">**Type**</th><th class="confluenceTh" style="height: 47.0625px;">**Description**</th><th class="confluenceTh" style="height: 47.0625px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd mceSelected" style="height: 49.5938px;">updateTransactionCategory

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">UpdateTransactionCategory

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Category data to be updated in the transaction</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Not empty</td></tr></tbody></table>

**UpdateTransactionCategory**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-124" style="width: 100%; height: 168.422px;"><colgroup><col style="width: 26.0816%;"></col><col style="width: 25.3399%;"></col><col style="width: 30.2843%;"></col><col style="width: 18.2942%;"></col></colgroup><tbody><tr style="height: 47.0625px;"><th class="confluenceTh" style="height: 47.0625px;">**Parameter**</th><th class="confluenceTh" style="height: 47.0625px;">**Type**</th><th class="confluenceTh" style="height: 47.0625px;">**Description**</th><th class="confluenceTh" style="height: 47.0625px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd mceSelected" style="height: 49.5938px;">transactionId

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Long

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Transaction ID</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Not empty</td></tr><tr style="height: 35.8828px;"><td style="height: 35.8828px;">categoriesInfo

</td><td style="height: 35.8828px;">List&lt;TransactionCategoryUpdateInfo&gt;

</td><td style="height: 35.8828px;">List of new transaction categories</td><td style="height: 35.8828px;">Not empty</td></tr></tbody></table>

**TransactionCategoryUpdateInfo**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-125" style="width: 100%; height: 168.422px;"><colgroup><col style="width: 26.0816%;"></col><col style="width: 25.3399%;"></col><col style="width: 30.2843%;"></col><col style="width: 18.2942%;"></col></colgroup><tbody><tr style="height: 47.0625px;"><th class="confluenceTh" style="height: 47.0625px;">**Parameter**</th><th class="confluenceTh" style="height: 47.0625px;">**Type**</th><th class="confluenceTh" style="height: 47.0625px;">**Description**</th><th class="confluenceTh" style="height: 47.0625px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd mceSelected" style="height: 49.5938px;">id

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Long

</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Category id</td><td class="confluenceTd mceSelected" style="height: 49.5938px;">Not empty</td></tr><tr style="height: 35.8828px;"><td style="height: 35.8828px;">amountMinor

</td><td style="height: 35.8828px;">Double?

</td><td style="height: 35.8828px;">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</td><td style="height: 35.8828px;">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="29129aa9-d04e-4dd6-9aad-94c44cdc43db" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback%2F-fa-5"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback/ Failure callback.</p>

</td></tr></tbody></table>

**Sample**

```
fun updateTransactionCategory(updateTransactionCategory: UpdateTransactionCategory) {
    mobileDcApi
        .transactionsHistoryService
        .updateTransactionCategory(updateTransactionCategory, {
            //Transaction caegories updated successfully
        }, {
            //Something went wrong, check exception with documentation
        })
}
```

###   


### getTransactionUserCategories

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b6521ea5-fcb7-4b2d-bb43-bed6b3d36ace" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-49"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">Method returns user categories.</p>

</td></tr></tbody></table>

**Input**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="2d274cb7-d7ff-43cb-8d45-5c66f70e21f2" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-no-input-parameters."><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">No input parameters.</p>

</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-16"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with user categories details.</p>

</td></tr></tbody></table>

**GetTransactionUserCategoriesResponse**

<table class="wrapped confluenceTable" id="bkmrk-parameter-type-descr-126"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th class="confluenceTh">**Parameter**</th><th class="confluenceTh">**Type**</th><th class="confluenceTh">**Description**</th></tr><tr><td class="confluenceTd" colspan="1">categories</td><td class="confluenceTd" colspan="1">List&lt;TransactionUserCategory&gt;</td><td class="confluenceTd" colspan="1">User categories.</td></tr></tbody></table>

**<span class="inline-comment-marker" data-ref="007ba296-09e9-4b16-a423-61b75c9eca94">TransactionUserCategory</span>**

<table class="relative-table wrapped confluenceTable" id="bkmrk-field-type-descripti-11" style="width: 140.864%; height: 232.031px;"><colgroup><col style="width: 31.0451%;"></col><col style="width: 28.442%;"></col><col style="width: 40.5747%;"></col></colgroup><tbody><tr style="height: 47.0625px;"><th class="confluenceTh" style="height: 47.0625px;">**Field**</th><th class="confluenceTh" style="height: 47.0625px;">**Type**</th><th class="confluenceTh" style="height: 47.0625px;">**Description**</th></tr><tr style="height: 30.2812px;"><td class="confluenceTd" style="height: 30.2812px;">id</td><td class="confluenceTd" style="height: 30.2812px;">String</td><td class="confluenceTd" style="height: 30.2812px;">Category identifier</td></tr><tr style="height: 47.0625px;"><td class="confluenceTd" style="height: 47.0625px;">idName</td><td class="confluenceTd" style="height: 47.0625px;">String</td><td class="confluenceTd" style="height: 47.0625px;">Category name in english</td></tr><tr style="height: 47.0625px;"><td style="height: 47.0625px;">name</td><td style="height: 47.0625px;">String</td><td style="height: 47.0625px;">Category name in the language that was sent in the request header</td></tr><tr style="height: 30.2812px;"><td style="height: 30.2812px;">type</td><td style="height: 30.2812px;">String</td><td style="height: 30.2812px;">Category type, one of: \[SYSTEM, USER\]</td></tr><tr style="height: 30.2812px;"><td style="height: 30.2812px;">childrenCategories</td><td style="height: 30.2812px;">List&lt;TransactionUserCategory&gt;?</td><td style="height: 30.2812px;">Children categories</td></tr></tbody></table>

**Sample**

```
fun getTransactionUserCategories() {
    mobileDcApi
        .transactionsHistoryService
        .getTransactionUserCategories({ userCategories ->
            //get user caegories success
            	val categories = userCategories.categories
                showUserCategories(categories)
        }, {
            //Something went wrong, check exception with documentation
        })
}
```

###   


### getMonthlySpendingAmount

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="b6521ea5-fcb7-4b2d-bb43-bed6b3d36ace" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-asynchronous.-online-50"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Asynchronous. Online.</p>

<p class="callout info">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</p>

</td></tr></tbody></table>

**Input**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-127" style="width: 91.9753%; height: 96.1876px;"><colgroup><col style="width: 20.3634%;"></col><col style="width: 20.6841%;"></col><col style="width: 35.4356%;"></col><col style="width: 23.4099%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><th class="confluenceTh" style="height: 46.5938px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5938px;">**Type**</th><th class="confluenceTh" style="height: 46.5938px;">**Description**</th><th class="confluenceTh" colspan="1" style="height: 46.5938px;">**Validation conditions**</th></tr><tr style="height: 49.5938px;"><td class="confluenceTd" colspan="1" style="height: 49.5938px;">getMonthlySpending</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">GetMonthlySpending</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">Plain object of GetMonthlySpending

</td><td class="confluenceTd" colspan="1" style="height: 49.5938px;">Not empty</td></tr></tbody></table>

**GetMonthlySpending**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-128" style="width: 91.9753%; height: 167.625px;"><colgroup><col style="width: 20.3634%;"></col><col style="width: 20.6841%;"></col><col style="width: 35.4356%;"></col><col style="width: 23.4099%;"></col></colgroup><tbody><tr style="height: 46.5833px;"><th class="confluenceTh" style="height: 46.5833px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5833px;">**Type**</th><th class="confluenceTh" style="height: 46.5833px;">**Description**</th><th class="confluenceTh" style="height: 46.5833px;">**Validation conditions**</th></tr><tr style="height: 49.5833px;"><td class="confluenceTd" style="height: 49.5833px;">balanceId</td><td class="confluenceTd" style="height: 49.5833px;">String</td><td class="confluenceTd" style="height: 49.5833px;">Account identifier which can be related to multiple cards

</td><td class="confluenceTd" style="height: 49.5833px;">Not empty</td></tr><tr style="height: 35.7292px;"><td style="height: 35.7292px;">targetCurrency</td><td style="height: 35.7292px;">String</td><td style="height: 35.7292px;">Target currency of spending amount represented by 3-character ISO 4217 currency code.

</td><td style="height: 35.7292px;">Not empty</td></tr><tr style="height: 35.7292px;"><td style="height: 35.7292px;">date</td><td style="height: 35.7292px;">String?</td><td style="height: 35.7292px;">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.

</td><td style="height: 35.7292px;">  
</td></tr></tbody></table>

**Output**

<table class="wysiwyg-macro" data-macro-body-type="RICH_TEXT" data-macro-id="a7062c21-5902-48ed-9040-1d0367ebc93e" data-macro-name="info" data-macro-schema-version="1" id="bkmrk-success-callback-wit-17"><tbody><tr><td class="wysiwyg-macro-body"><p class="callout info">Success callback with user monthly spending amount.</p>

</td></tr></tbody></table>

**GetMonthlySpendingResult**

<table class="relative-table wrapped confluenceTable" id="bkmrk-parameter-type-descr-129" style="width: 91.9753%; height: 131.854px;"><colgroup><col style="width: 20.3634%;"></col><col style="width: 20.6841%;"></col><col style="width: 35.4356%;"></col><col style="width: 23.4099%;"></col></colgroup><tbody><tr style="height: 46.5625px;"><th class="confluenceTh" style="height: 46.5625px;">**Parameter**</th><th class="confluenceTh" style="height: 46.5625px;">**Type**</th><th class="confluenceTh" style="height: 46.5625px;">**Description**</th><th class="confluenceTh" style="height: 46.5625px;">**Validation conditions**</th></tr><tr style="height: 49.5625px;"><td class="confluenceTd" style="height: 49.5625px;">amountMinor</td><td class="confluenceTd" style="height: 49.5625px;">Long</td><td class="confluenceTd" style="height: 49.5625px;">Calculated spending amount in minor units

</td><td class="confluenceTd" style="height: 49.5625px;">Not empty</td></tr><tr style="height: 35.7292px;"><td style="height: 35.7292px;">currency</td><td style="height: 35.7292px;">String</td><td style="height: 35.7292px;">3-character ISO 4217 currency code of spending amount

</td><td style="height: 35.7292px;">Not empty</td></tr></tbody></table>


**Sample**

```
fun getMonthlySpendingAmount() {
    
	val getMonthlySpending = GetMonthlySpending(
  	  	balanceId = "99f552bd-b7b3-418d-9b0e-2aa6deeb2a77",
   	 	targetCurrency = "USD",
    	date = "2022-12"
	)    
    
    mobileDcApi
        .transactionsHistoryService
        .getMonthlySpendingAmount(getMonthlySpending, { monthlySpendingResult ->
            	// monthly spending result
                showMonthlySpending(monthlySpendingResult)
        }, {
            //Something went wrong, check exception with documentation
        })
}
```

## DOCUMENT CHANGELOG

<span style="background-color: rgb(255, 255, 255);">Version 2.17.6</span>

- Added field walletId to NewUser model and methods addUser, getUser

<span style="background-color: rgb(255, 255, 255);">Version 2.17.5</span>

- MDC is now built as a [fused library](https://developer.android.com/build/publish-library/fused-library)
- Updated AGP to 9.0.1
- Updated Gradle to 9.3.1

<span style="background-color: rgb(255, 255, 255);">Version 2.17.4</span>

- <span style="background-color: rgb(255, 255, 255);">Added new fields to requests and responses in methods getTransactionHistory and getTransactionDetails. Including transactionId, paymentSystem, deliveryMode, balanceId and contrahent address. Set field contrahent as deprecated in TransactionFilter</span>
- Updated key dependencies to address known security risks and align with the highest currently safe supported versions, including Jackson 2.15.4, Guava 33.4.0, OkHttp 4.12.0, Retrofit 2.11.0 and Coroutines 1.7.3
- <span style="background-color: rgb(255, 255, 255);">Improved stability</span>

Version 2.17.3

- Updated library Nimbus-jose-jwt to version 10.5 and removed net.minidev:json-smart
- Added possibility to handle Huawei devices for device pairing in Verestro system and reveiving push messsages (dependencies not included in SDK, added on application side)
- Added possibility to handle Huawei devices for device pairing in Verestro system and receiving push messages.  
     Important: Huawei / HMS integrations require additional Huawei dependency on the application side:  *'com.huawei.hms:safetydetect:6.3.0.301'*
- Added new methods - *registrationResendEmail, resendOtp, getAuthenticationTokenBySignature* and *getAuthenticationTokenByWPin*

Version 2.17.0

- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1

Version 2.16.12

- Added new parameters for Card model (*name, brand*) in methods *addCard*, *updateCard* and *getCards*
- Added new method for getting cards with pagination - see *Cards::getAll*

Version 2.16.10

- Security tools updated to newest version  
    **IMPORTANT: Recommneded update when using version 2.16.x due to changes fixes in security tools**

Version 2.16.7

- Updated dependencies and internal changes

Version 2.16.4

- Important: Apply security and functional certification changes due to update security tools. Changes in security thread management and working in background
- Removed configuration DeveloperOptions:enableAdditionalSecurityChecks as there is no longer supported
- Added field prefferedLanguage to NewUser model and methods addUser, updateUser, getUser

Version 2.15.8

- Added Mobile DC reset method to reset data along MDC and related SDKs

Version 2.15.7

- Added new methods related to device pair with two factor authenication: finalizePairDeviceWithTwoFactorAuthentication and dispatchOtpForPairDeviceWithTwoFactor
- Update Android API compile version to 34

Version 2.15.5

- Added new CloudMessagingType: EXTERNAL used in CloudMessagingRegistrationToken to indicate token for external RNS source.
- Added optional configuration withOptionalMobileDcTransactionEventListener for MobileDcApiConfigurationBuilder
- Internal improvements.

Version 2.15.3

- Minor improvements in user session.
- Internal improvements.

Version 2.15.1

- Added new methods related to transaction history in TransactionsHistoryService:   
    
    - *updateTransactionCategory*,
    - *getTransactionUserCategories*,
    - *getMonthlySpendingAmount*
- Small fixes Cloud Messaging SSE device registration during pairDevice
- Internal improvements

Version 2.15.0

- Upate security mechanism with scanning packages
- Fixed bug with access of security mechanism to multiple accounts on Android system
- Added to whitelist one false-positive security check
- Koin dependency is now bundled as part of SDK (Koin is no longer visible in pom.xml file)
- Updated R8 dependency

Version 2.14.7.2

- Added additional mechanism for catching errors visible on Google Play

Version 2.14.7.1 Hotfix

- **Important** Hotfix possible OutOfMemoryException in 2.14.7

Version 2.14.7 - don't use, could cause OOM exception

- **Important** Fixed security check for non-ascii system languages. Security check is enabled only if flag *DevelopeOptions::enableAddiotionalSecurityChecks* is set to true.
- Added new fields to *addUser* response: *acceptedRegualations* and *acceptedMarketingReceiving.*
- Added new input field *comment* for method *updateSingleTransaction.* Fileld is present in response of methods *getTransactionHistory* and *getTransactionDetails.*

Version 2.14.6

- **Important!** Introduced Play Integrity API instead Safetynet Attestation API - could require additional configuration. Read more in *Security processes overview* chapter*.* Enabling requires Google API console changes. Added new BackendException statues related to Attestation API.
- **Important!** Introduced new delivery message from server service which uses different channle: SSE, RNS as an alternative for only cloud messaging service (FCM). Enabled by default for not paired devices.
- **Important!** Added optional configuration method - *MobileDcCloudMessagingConfiguration.* Interface allows to register non-paired devices in new delivery message from server sevice. Significally optimizes RNS message delivery, usage is strongly recommended. If this interface is present, already paired device, will be registered in new delivery message server service, during first *login()* call.
- Added method *updateSingleTransactionData* in transactions history service.
- Added new methods for device pairing - old methods became deprecated.
- Added new optional fileld to all new *pair device* methods - *externalDeviceId.*
- Introduced *RefreshSession* mechanism for user HTTP token management - extends a duration of session and allows to use SDK methods longer. Usage is transparent for application which still should handle USER\_UNATHORIZED error status.

Version 2.13.6

- Added new returned fields to methods: *getTransactionsHistory* and *getTransactionDetails.*

Version 2.13.5

- Added new value in additional DeveloperOptions, responsible for verification SDK code obfuscation.
- Added information about using SDK on Android API 31+ in [Basic Configuration](https://wiki.verestro.com/pages/viewpage.action?pageId=67340661) chapter.
- Wraped in try-catch block callbacks from setup method to prevent process breaking in SDK.

Version 2.13.3

- **IMPORTANT** Removed security check for disabling permission QUERY\_ALL\_PACKAGES i application AndroidManifest file.
    
    Read more in Basic configuration : Android permission chapter.

Version 2.13.2

- Updated documentation for Application Isolated Process with Magisk information.
- Updated <u>recommended configuration</u> and documentation for *extractNativeLibs* flag configuration, native libs should be in uncompressed form. Read more in Basic configuration section.
- Isolated security process mechanism improvements (related to *enableAdditionalSecurityChecks* configuration flag).
- Update Kotlin version to Kotlin version to 1.5.31 and Koin to 2.1.6.
- Updated Jackson dependency to 2.13.2 (with jackson-databind 1.13.2.2 security patch).
- Added new methods:
    
    
    - initialize3DSv2 in Cards domain,
    - finalize3DSv2 in Cards domain,
    - deleteUser in User domain.
- Added new field "nip" in AddUser model.
- Added logs for all facade methods (available in SDK debug version).

Version 2.12.1

- Fixed aggressive security process check from MDC SDK 2.12.0.

Version 2.12.0

- IMPORTANT Updated security tools after EMV Security Evaluation. Please refer to [setup.](https://wiki.verestro.com/pages/viewpage.action?pageId=67340696) and [Application Isolated Process](https://wiki.verestro.com/display/UCP/Application+Isolated+Process).
    
    
    - added new security checks which which requires additional action on application side,
    - added new fields in DeveloperOptions object - allowDebug and enableAdditionalSecurityChecks.
- Updated Gradle and R8 tools.
- Added new methods related to transaction history and attachment in TransactionsHistoryService:
    
    
    - getTransactionDetails,
    - storeAttachment,
    - generateAttachmentLink,
    - deleteAttachment.
- Added new fields related to MCC (mcc, mccCategory) in methods getTransactionHistory and getTransactionDetails.

Version 2.11.12

- Added more protections for Android Keystore issues related to access by retrying and adding multi-thread synchronization.

Version 2.11.10

- Added new chapter Firebase Cloud Messaging configuration.
- Updated Security processes overview with Error codes handling in application.
- Introduced new approach to handling security issue. To provide better experience new status was added CoreSdkException with reason SECURITY\_EVENT\_OCCURRED. Error could be provided in every SDK methods if security issue was detected. Change doesn't impact on onSecurityIssue callback.

Version 2.11.8

- Added new method for initializing reset user password with InitializeResetUserPassword model. Previous method is deprecated now.

Version 2.11.6

- Minor fixes in user session.

Version 2.11.5

- Added new optional to DeveloperOptions, introducing new security checks.
- Added method verifyCard to verify card after 3DS. Card domain.
- Extended TransactionsFilters in getTransactionHistory. Transaction history domain.
- Added new method to addCard with AddCard model. The old method was marked as deprecated. Card domain.
- Added new response parameter to getAll method. Card domain.
- Added new request parameter to updateCard method. Card domain.
- Added new permission: <span class="devsite-heading">QUERY\_ALL\_PACKAGES</span> for security checks.

Version 2.11.3

- Updated security libraries.

Version 2.11.2

- Added DeveloperOptions configuration in setup.
- Added logout method.

Version 2.10.1

- Removed false-positive security rules.
- Improved security reports sent to Wallet Server.

Version 2.10.0

- Added new method for adding address with NewAddress model. Previous method is deprecated now.
- Added new method in Cards service: updateCard.
- Added new methods in Addresses servive: updateAddress, deleteAddres.

Version 2.9.3

- Device un-pairing device with *unPaidDevice* is now avaliable for not logged in users.
- Un-pair process (*unPaidDevice* method) requires application restart if UCP SDK is used and card was already digitized for another user.
- Login methods now clearing SDK data when device is removed from server
    
    When any login method fails with *BackendException* and *CANT\_FIND\_DEVICE* reason application should proceed with device pairing again.

Version 2.9.0

- Security issue codes are more precisely and give us more information about issue.
- Marked addAddress as deprecated.
- Added new one addAddress method which returning addressId of added address.

Version 2.8.0

- Added addresses service to facade.
- Fixed checksum sending.
- Added apk certificate description.
- Added updateUser method to User domain.

Version 2.7.0

- Added addresses service to facade.

Version 2.6.1

- Disabled sending native checksum in pairDevice process.

Version 2.6.0

- Added addUser method.

Version 2.5.0

- Added getUser method.

Version 2.4.0

- Added optional log handler to MobileDcCoreConfigurationBuilder.
- Added disableBiometricAuthentication method.
- Added BiometricTypeAuth paramter to pairing methods.

Version 2.3.1

- Added new methods in user domain (isBiometricAuthenticationEnabled, enableBiometricAuthentication, startBiometricAuthentication, authenticateByBiometric, loginBySignature).
- Fixed security reports sending.
- Consumer proguard rules update.

Version 2.2.0

- Improved Mobile DC SDK startup time.

<span class="inline-comment-marker" data-ref="1f222a31-867a-4ab1-8476-cee93df3dead">Version 2.1.1</span>

- Added information about SDK size.
- Added information about SDK ingetration on lower Android API level.

Version 2.1.0

- <span class="inline-comment-marker" data-ref="1f222a31-867a-4ab1-8476-cee93df3dead">Added new methods in User domain (authenticateByPin, loginByPin, changeWalletPin, resetWalletPin, initializeResetUserPassword, finilizeResetUserPassword).  
    </span>
- <span class="inline-comment-marker" data-ref="1f222a31-867a-4ab1-8476-cee93df3dead">Added new methods in Cards domain (addCard, initialize3ds, finalize3ds, deleteCard).</span>

Version 2.0.0

- Changed approach to SDK setup.
- Removed methods used to fingerprint authentication.
- Added NetworkConnection exception and CoreSdkException.
- Added new reason codes to existing exceptions.
- New methods in user domain: addUser, loginByTrustedIdentity, changePassword.
- New methods in device domain: pairByPassword, pairByExternalCredentials, unPairDevice.
- New methods in cards domain: getAll.
- New domains: ibans, transactionsHistory.

Version 1.0.1

- Created.

# Frequently Asked Questions

### Frequently Asked Questions (FAQ)


Below you will find answers to the most common questions about the **User** **Lifecycle** module.

If you can't find the answer you're looking for, please contact our Support team.

**[Go to the User Lifecycle FAQ](https://developer.verestro.com/books/faq/page/faq#bkmrk-faq---user-lifecycle)**

# FCM configuration - Grant permission for another Project

##### Configuration for forwarding Cloud Messages from Verestro FCM to Client's FCM.

1. Visit [console.cloud.google.com/iam-admin](http://console.cloud.google.com/iam-admin)
2. Select **Grant Access** [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/0s9image.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/0s9image.png)
3. In **Assign roles** section select a role from a list  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/K2Kimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/K2Kimage.png)
4. Select option **Manage roles**  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/WBoimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/WBoimage.png)
5. Select **Create role**  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/RdPimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/RdPimage.png)
6. Fill title (1) and ID (2) fields, and click on **Add permissions** (3)  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/9Kyimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/9Kyimage.png)
7. In **Add permissions** window, using filter field find **cloudmessaging.messages.create** value  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/hh6image.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/hh6image.png)
8. Mark found permission, and add it  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/MEEimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/MEEimage.png)
9. After adding permission, create the role  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/rvAimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/rvAimage.png)
10. There should appear our new created role  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/P40image.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/P40image.png)
11. Visit [https://console.cloud.google.com/iam-admin/iam](https://console.cloud.google.com/iam-admin/iam)
12. Select **Grant access** option again  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/Qadimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/Qadimage.png)
13. Input e-mail in New principals field (1) for account which will be using the new role (**principal provided directly or in configuration file**), and next in **Assign roles** section **select a role** (2) from a list  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/sGdimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/sGdimage.png)
14. Using filter field, find new created role  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/0UFimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/0UFimage.png)
15. After choosing a role, save the principal access  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/nB3image.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/nB3image.png)
16. There should appear new principal with new role on the list  
      
    [![image.png](https://developer.verestro.com/uploads/images/gallery/2025-11/scaled-1680-/GApimage.png)](https://developer.verestro.com/uploads/images/gallery/2025-11/GApimage.png)

# Obtain HCM Credentials

Instruction for retrieving credentials in Huawei Cloud Messaging (HCM), needed for seamless sending notifications from Verestro servers to existing user devices.

1. Log in to AppGallery Connect [https://developer.huawei.com/consumer/en/service/josp/agc/index.html,,AppGalleryConnect#/](https://developer.huawei.com/consumer/en/service/josp/agc/index.html,,AppGalleryConnect#/)
2. Choose Development and services tab and then select preferred project
3. Copy following values and share with Verestro representative in secure way 
    1. Project ID
    2. Client ID
    3. Client secret

 Values can be found the same as on screen below:

1. 1. ![hcm_config.png](https://developer.verestro.com/uploads/images/gallery/2026-01/scaled-1680-/hcm-config.png)

# Trusted Identity

# Trusted Identity

Trusted Identity is a signed JWS token (in JWT format) that the **Partner/Tenant backend** passes to the Verestro backend to authenticate the request and initiate an end-user session. The token is verified cryptographically (signature + certificate chain in `x5c`) and organizationally (verification of `CN` according to the onboarding configuration).

***

## 1) Purpose and Use

### What it is
- Trusted Identity is a token that **must be generated on the Partner/Tenant backend side**, in an isolated and secure environment. It is passed to Verestro as proof that the Partner/Tenant confirms the identity of the end user identified by `userId` (see the [Payload (claims)](#32-payload-claims) section).

### Why it is used
- To start an end-user session in a component (e.g., SDK) communicating with the Verestro backend.
- To simplify integration: the token is self-contained because it includes `x5c` (certificate chain), so Verestro can verify the signature and trust without querying an external JWKS endpoint at runtime.
- To protect against replay attacks: short TTL based on `iat`.

### Token Issuance and Verification – sample usage


@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "Partner/Tenant (Backend)" as A
participant "Verestro (API)" as B
User -> A: Session start request
A -> A: Build payload (userId, iat, jti)
A -> A: Add x5c (leaf + intermediates)
A -> A: Sign JWS (RS256, private key)
A -> B: Send Trusted Identity (JWS)
B -> B: Read Root CA + expected CN
B -> B: Validate x5c chain to Root CA
B -> B: Validate CN/DN === expected
B -> B: Verify JWS signature
B -> B: Check iat TTL (10 min)
B -> B: Start user session for userId
B --> User: Session active
@enduml

## 2) Integration / Onboarding

### Variant A (recommended): Partner/Tenant provides CSR
The Partner/Tenant:
- generates an RSA key pair (RSA 2048),
- generates a CSR with `CN=V-TenantName-ApplicationName` (instructions for correctly generating a CSR are available in the [documentation](https://developer.verestro.com/books/connecting-to-our-services-and-sandbox/page/connecting-to-server-to-server-apis-fe-sandbox)),
- submits the CSR to Verestro.

Verestro:
- signs the CSR with its internal CA and delivers the signed certificate to the Partner/Tenant.

The Partner/Tenant:
- uses the private key from the generated key pair to sign Trusted Identity tokens,
- includes the leaf + intermediate certificates in `x5c` (if applicable).

### Variant B: Partner/Tenant provides Root CA
The Partner/Tenant provides:
- The Root CA to be added as trusted in Verestro's systems.
- The expected `CN`/`DN` of the certificate used for signing.
- The above must be provided by the Partner/Tenant during the onboarding process.

Verestro:
- configures the Root CA in its systems,
- stores the expected `CN`/`DN` for the Partner/Tenant,
- accepts tokens whose `x5c` builds a chain to this Root CA and satisfies the CN/DN requirement.

### Onboarding variants

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "Partner/Tenant" as C
participant "Verestro" as P
alt Variant A (recommended): CSR signed by our CA
C -> C: Generate RSA keypair
C -> P: Send CSR (CN=uniquePartner/TenantName)
P -> P: Sign CSR with our CA
P -> C: Return certificate (+ intermediates if any)
P -> P: Configure our Root CA + expected CN/DN
else Variant B: Partner/Tenant provides Root CA
C -> P: Provide Root CA + expected CN/DN
P -> P: Configure Root CA + expected CN/DN
end
@enduml

***

## 3) Structure

The token has the following format:
`{base64url(header)}.{base64url(payload)}.{base64url(signature)}`

### 3.1 Header
Required fields:
- `alg`: signature algorithm (recommended: `RS256`, RSA 2048).
- `x5c`: X.509 certificate chain in Base64(DER) format, where:
  - the first element is the `leaf` certificate (containing the public key used to verify the signature),
  - subsequent elements are intermediate certificates,
  - the root CA is typically not included (Verestro holds it in its trust store).

Example:
```json
{
  "alg": "RS256",
  "typ": "JWT",
  "x5c": [
    "MIIC... (leaf)",
    "MIID... (intermediate)"
  ]
}
```

### 3.2 Payload (claims)
Required fields:
- `userId`: user identifier:
  - accepted values: **internal ID** (identifier from Verestro) or **external ID** (end-user identifier in the Partner/Tenant system),
  - preferred: **external ID — must be unique within the Partner/Tenant system**,
- `iat`: token issuance time (UNIX epoch in seconds).
- `jti`: unique token identifier (UUID).

Example:
```json
{
  "userId": "external-987654",
  "iat": 1739191200,
  "jti": "a3f1c3d6-0d3b-4f2e-9c24-8d6b9b2a9f0d"
}
```

### 3.3 Signature
- The token must be signed with the Partner/Tenant's private key corresponding to the certificate provided in `x5c`.
- Minimum requirements:
  - RSA 2048
  - `RS256`

***

## 4) Security Requirements (TTL)

### TTL (token validity)
- TTL: **default: 10 minutes** from `iat` (this value can be changed). Once the token expires, a new one must be generated.

***

## 5) Trust Based on `x5c` and CN/DN Validation

### What Verestro verifies
1. Construction and validation of the certificate chain from `x5c` up to the configured Root CA.
2. Validation of the certificate's `CN` against the value established during the onboarding process.
3. JWS signature verification using the public key from the leaf certificate.
4. Validation of `iat` (TTL) and `jti` (replay protection), and presence of `userId`.

### CN rule (integration requirement)
- The `CN` (or agreed `DN`) of the certificate is the permanent identifier of the Partner/Tenant.
- The `CN`/`DN` must not change during certificate renewal without prior notification; key/certificate rotations within the same DN are permitted.

***

## 7. Examples and Test Methods – those should be used for development and testing purposes only.

### 7.1 Trusted Identity example:
Token generated with the following payload will look like this:
```json
{
  "iat": "1770981506093",
  "jti": "1b290b62-8e1e-4168-bb24-5c29d22ee699",
  "userId": "some-external-user-id-1234"
}

"eyJhbGciOiJSUzI1NiIsIng1YyI6WyJNSUlGeFRDQ0E2MmdBd0lCQWdJVWNMWmtmN0EyZFdvNHdKT1NlVEdpbnMvdlVQTXdEUVlKS29aSWh2Y05BUUVMQlFBd2NqRUxNQWtHQTFVRUJoTUNVRXd4RkRBU0JnTlZCQWdNQzAxaGVtOTNhV1ZqYTJsbE1ROHdEUVlEVlFRSERBWlhZWEp6WVhjeEZEQVNCZ05WQkFvTUMxWmxjbVZ6ZEhKdklGTkJNUXd3Q2dZRFZRUUxEQU5FUlZZeEdEQVdCZ05WQkFNTUQxWmxjbVZ6ZEhKdlgwTkJYMFJsZGpBZUZ3MHlNVEF5TURnd056TTVOVEZhRncweU5qQXlNRGN3TnpNNU5URmFNSEl4Q3pBSkJnTlZCQVlUQWxCTU1SUXdFZ1lEVlFRSURBdE5ZWHB2ZDJsbFkydHBaVEVQTUEwR0ExVUVCd3dHVjJGeWMyRjNNUlF3RWdZRFZRUUtEQXRXWlhKbGMzUnlieUJUUVRFTU1Bb0dBMVVFQ3d3RFJFVldNUmd3RmdZRFZRUUREQTlXWlhKbGMzUnliMTlEUVY5RVpYWXdnZ0lpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElDRHdBd2dnSUtBb0lDQVFEbkZIZzB4Q0prckYwNFVSc0p0em5aVndxOWxrVUd2Z3J3K2RVVzh5aS9MV0VoMC9QU2hLVmUxNEFqWktXSXJaU3FRNDR6d0Mwbk04c0NyRjgvWnJxVFYvc0Q3dTQ5WnMzeko2TkVOQk83VTI0blZpeUxiaDNQQkZReEcyYWd6Q0ZTUXpEMTdpR0ZxckxYa29vQWVOMVllczRUc0FSdzlzK21aMlhydzlEaGdVa3pFZUZwcXo1c3J2N3huMFpLdjh4czMrZjd1SUlGdWdSWFhYVWltUmdCWXQ3dzk0SmgxblRpQis0SU1RSXBFR2Vmd29HTmlKL0IvWThsVXJVLzd1TnhKTHc2UU54dG52ZkFNaVJReGV4ektPc21RMWVxd1MrWWlQTVc3MG8vOVJHMmRRaWZyYWRpOU9JRjlqZmUxbzhxSVRQUG1nRG9aVWI1dWYrSGFybXdrSEs1SjBUcWpkZWZaNjlwYTVwWUppQzNsOUNOYlh1YzI3VVhuZmQxK2dwckdZMjdhMjgyemMwQnZad1FjL085blZIclVBeVh4OGR3MjIwK3RkUDZzSkFKMUV6YUpaVWltcDBka0hENkhLbmp3WjJ1L2RtMi83RzFYSnpiY0IzSStDMWlmbXdEYXhoWlVUbGpweGRBbklpbFU5WUpmOU14UVUwRGJ6bGVxMS9Sc01DWU9rSUpoZjVwZXdPMXFmSVlLK0V2a05iRzI5VzRqdGtNOFNISTdVRUFNN3hrWk1qVkNaamNMZnBzUk5LMWNjTnpFTEF3V2lHWG8yaVhEVmdBUStVUVU2cHBQdFQyb0ZVWWU3aWpFSit0RnEzQWd3UzIvMldnL1RvOVlhbitWM2luN2IxUURmTlJVc1BxeDgrTFlLcHhCRGVhMjBlR3FBZ1VTYzNEVFFJREFRQUJvMU13VVRBZEJnTlZIUTRFRmdRVWlteVhrSDE4bGhzRXc1ai9UaldCZ0d2NDNhSXdId1lEVlIwakJCZ3dGb0FVaW15WGtIMThsaHNFdzVqL1RqV0JnR3Y0M2FJd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBTkJna3Foa2lHOXcwQkFRc0ZBQU9DQWdFQVhlM0ZGMm1zRC9qdllyYW03SnBpQlUvbFB0dEx0bmdpL3pCTGM4Y0dKbGlhcTM2S1h1ZWdpRWp3cjJtT1ExeXNaUXRQSnUrZjg4TXBPWU9QdDFBZm1QN1RRZ0ZZTjRyOFJVU2RxOEMwVTlUOFZvNUJxaXh4WFl6Z0xBSi8wTkZpZmx3YVJLN2FKOUdza1MrNkFoRUppRTdyNkl1cTZScWVyS3VvYkZvaEtQdHZLZkM5ZjBvcEwxVDBlV296L3BVNTBOTDM5QXpETkk5Tkh5MWdPQnNGNElYSHRUeHN1eTJCNjVyTkpjSjdKbmNkc0xhdWVhL3doa1hoUWRkUTVrN25MbUJ4eFl2M0RWZmNkZ2dYUXF0S3ZKQnh4SE9Gak1yUzdDYXVud2h6WDlJQW05Ny82MU8zNXVkd1dKVHZ0eFJnNEFWTGNOWXhjRHZTNlN3WVhud0dQak5BS0QvNXdpcStTMlZib1Z4UkJqSm12cEVhRU5WQ3djQnlvZ3ZidnlXcEd6WkhOUGdDRmVUVFRIYU51ZWJxL05XYmJ4QWM2bWhxM3d5bC9mYnBwakRhTno1U2hlbVFCdVVhbVZ1WlBZNVJDS2FUc2twSElTT0UyT1RrMkEzVkpuajA1cm0wQUY1QWlRbjJjWThJM3dYODlseFZRc3YrRjQyR2VMalVRMnVqMDR5dEliSjNnYUlBVFE3ODMvRjVuRkFVY0o0VWNGcXRFRXZEYVVkMEkrbFRtZkQzTEc0Y3E2STRheUd2Z04zS2NURW1PUU43ZlZPNWlvRjJFSk5oK1dRTHNuQ1RaTkgxc2dOSk53ajRRSlduSzVaYThPcTNzZk9jRDVraVE0ZmoxbW9HNmhRWkxQM3J6OVZZR2lCWTF2aWlGVG5RcWhJYjlOdzlrQ1NDaWEwPSJdfQ.eyJpYXQiOiIxNzcwOTgxNTA2MDkzIiwianRpIjoiMWIyOTBiNjItOGUxZS00MTY4LWJiMjQtNWMyOWQyMmVlNjk5IiwidXNlcklkIjoic29tZS1leHRlcm5hbC11c2VyLWlkLTEyMzQifQ.m75hzT1Wn4RW4wxVLdNm5wukVMtT-5J6h8PldaHfQ19WGqlx2x4wa5Ut2xKORaoMZOOkGMP1VKbOa-_MgFWeSR6nwyiUXoa7zDh7MNnUD7C1yCk-eVQDdSoFIQIg7UBjVj0uJZYkUOmScz0MjCpeZ-hhFVQInnHK-8YNdR1A5L-S5-d57pubz0C2GarIJu7z1d-qytfQFGdqvMAMuu9cPwc4oIfB4VajYqsz_NWWqSrsBNGnZIhuVKsWs1KXki3B2Z1v55tbET61bvZzuc7lEK27HzYaELC_za4zK0OP0GlqEl0gYzbj60E2sEE23jlUbiGj1Craq4KRrGpBAMDsgX0_kOicfQDjeYJ2wIouU2svDxLtI_BBiz7yT-opRTu0A-uDworfyWyt5IaZi9ZGOc_4--gwTWvrv1Bp9BPLZ8t6huSeJ4pjQTWMAZ_T2s2m69HWIIkIp0xDgkWBWlByEh-3ptzY_X3tZGtt7wjRH8AJrSeOXKPCDn9nZKu_sfaNFaDJGb28FajHR7u5xXUgif4DK9yFisaZf_SaXCkcO1KYO0oZD5Vy0gX-ZNJSVGX0yKm7wxHXBG1JPmHrvL-ieztM0PLBSR38I5CUJCHNLBlL2Cbw8YBuo-ubU0JxpgZ0i1g25Rxv1wVgYuw8x5ckxNpTjgsm08m-m-WcDxEAk_s"
```
### 7.2 Test methods

 - Generating Trusted Identity:
```bash
curl --location 'https://datacore.verestro.dev/test/generate-jws-x5c-token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Issuer-Code: YOUR_TENANT_ID' \
--header 'Application-Id: YOUR_TENANT_APP_ID' \
--header 'Authorization: Basic dGVzdDE6dGVzdDEyMw==' \
--header 'Collection: internal' \
--data '{
    "iat": "1770981506093",
    "jti": "1b290b62-8e1e-4168-bb24-5c29d22ee699",
    "userId": "some-external-user-id-1234"
}'
```
 - Validating Trusted Identity:
```bash
curl --location 'https://datacore.verestro.dev/test/read-jws-x5c-token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Issuer-Code: YOUR_TENANT_ID' \
--header 'Application-Id: YOUR_TENANT_APP_ID' \
--header 'Authorization: Basic dGVzdDE6dGVzdDEyMw==' \
--header 'Collection: internal' \
--data '{
    "token": "eyJhbGciOiJSUzI1NiIsIng1YyI6WyJNSUlGeF..................0qYz-H_0LEK0M"
}'
```
Output:
```json
{
  "verified": true,
  "token": {
    "iat": "1770981506093",
    "jti": "1b290b62-8e1e-4168-bb24-5c29d22ee699",
    "userId": "some-external-user-id-1234"
  }
}
```