Receivers SDK

Version. 2.0.9

Receivers SDK Overview

1.1. What is Receivers SDK?

1.2. How Receivers SDK works?

1.3. Versioning and backward compatibility
Technical overview

2.1. Basic information

2.2. Basic configuration

2.3. Receivers SDK Setup

2.4. Error handling
Receivers service

3.1. addExternalReceiver

3.2. addWalletReceiver

3.3. deleteReceiver

3.4. getActiveAccounts

3.5. getReceivers

3.6. updateReceiver
1. DOCUMENT CHANGELOG
  
  4.1. Version 1.0.0
  
  4.2. Version 1.0.5
  
  4.3. Version 1.0.6
  
  4.4. Version 1.0.8
  
  4.5. Version 1.0.9
  
  4.6. Version 1.0.10
  
  4.7. Version 2.0.0
  
  4.8. Version 2.0.1
  
  4.9 Version 2.0.2
  
  4.10 Version 2.0.3
  
  4.11 Version 2.0.4
  
  4.12 Version 2.0.5
  
  4.13 Version 2.0.6
  
  4.14 Version 2.0.7
  
  4.15 Version 2.0.8
  
  4.16 Version 2.0.9

1. Receivers SDK Overview

1.1. What is Receivers SDK?

The P2P Receivers SDK is a module dedicated for receivers management. Receivers contains useful data
required in transaction process. Receivers are represented by phone numbers and associated cards.
SDK includes functions such as: get, add, update and delete receivers.

1.2. How Receivers SDK works?

Receivers SDK requires Mobile DC SDK as a dependency.
It’s required for the Receivers SDK to work correctly and handles user’s session and data (e.g.
cards).

Please read the Mobile DC SDK’s documentation to see more details about the installation and
integration process.

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

1.3. Versioning and backward compatibility

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

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

Changes not breaking compatibility:

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

2. Technical overview

This section describes basic information about Mobile DC SDK, Receivers SDK setup and available
methods.

2.1. Basic information

2.1.1 Facade

Facade is entry point to communication with Receivers SDK.

2.1.2 Multiple facade types

P2P Receivers SDK provides two public API's with same functionalities, the API's are:

receiversCoroutineService for projects which uses Kotlin programming language and Coroutines.
receiversStdService for projects which uses Kotlin or Java programming language and standard
Callback.

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

2.1.3 Method structure

Every method description has same structure.

Execution type:

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

Method type:

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

Input
Input parameters with name, type and description.

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

2.2 Basic configuration

2.2.1 Min SDK Version

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

2.2.2 Artifactory

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

Username and password is provided by Verestro.

repositories{  
    maven {       credentials {          username "<enter_username_here>"          password "<enter_password_here>"       }       url "https://artifactory.verestro.com/artifactory/android-release/"    }}

2.2.3 SDKs version

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

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

dependencies{  
    implementation "pl.upaid.module:mobiledc:{version}"    implementation 'com.verestro.module:receivers:{version}'}

For debugging purposes:

dependencies{  
    implementation "pl.upaid.module:mobiledc:{version}-debug"    implementation 'com.verestro.module:receivers:debug-{version}'}

2.2.1 Source code obfuscation and optimization

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

android {  
    ...    kotlinOptions {        freeCompilerArgs = [                '-Xno-param-assertions',                '-Xno-call-assertions',                '-Xno-receiver-assertions'        ]    }  
    packagingOptions {        exclude '/kotlin_metadata/**'    }    ...}

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

android.enableR8=true

2.3 Receivers SDK Setup

Available configuration methods:

ReceiversCoroutineApi.init(configuration: Configuration)
ReceiversStdApi.init(configuration: Configuration)

2.3.1 Input

Configuration

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

Configuration

| Parameter | Type | Description | |-------------------|---------------|-------------------------|
| productNam | String | API product name |
| url | String | API hostname URL |
| certificateHashes | List<String> | API hostname Pin SHA256 |

2.3.2 Sample

ReceiversStdApi

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

ReceiversCoroutineApi

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

2.4 Error handling

SDK returns errors by ReceiversSdkException, which could be catched by application and shown on UI
with detailed message.
Table below describes general exception types.

ReceiversSdkException

Exception	Parameters	Description
CryptographyError		Cryptography error.
InternalServerError		Internal application error.
ProductNotFound		Product not found based on sent header: Product-Name.
RequestCancelled		Request was canceled.
TechnicalException	message:String?	Technical exception.
NoSessionException		Session expired.
ValidationException	validationErrors: List<ValidationError>	List of validation errors.
UnknownErrorStatus	status: String	An unknown error occurred.
HttpApiException	code:Int, message:String?	HTTP API exception.

ValidationError

Parameter	Type	Description
fieldName	String	Name of field which not passed validation.
errorMessages	List<String>	List of error messages.

Specific types of exceptions are described for each method.

3 Receivers service

3.1 addExternalReceiver

Asynchronous. Online.  

This method allows user to add external receiver.

3.1.1 Input

AddExternalReceiverData

Parameter	Type	Description
phoneNumber	String	Phone number.
displayName	String	Display name.
firstName	String?	Optional. First name.
lastName	String?	Optional. Last name.
cardNumber	CharArray?	Receiver card number.

3.1.2 Output

3.1.2.1 Success

Success callback with AddExternalReceiverResult model.

AddExternalReceiverResult

Parameter	Type	Description
receiver	AddReceiverModel	Added receiver.

AddReceiverModel

Parameter	Type	Description
id	Long	Receiver identifier.
firstName	String	First name.
lastName	String	Last name.
phoneNumber	String	Phone number.
displayName	String	Display name.
lastFourDigits	String?	Conditional. Card last 4 digits.
bin	String?	Conditional. Card bin.
receiverType	ReceiverTypeValue	Value class encapsulating sample type as a [EXTERNAL] String field.

3.1.2.2 Failure

Failure callback with throwable.

3.1.3 Sample

Standard Callback

fun addExternalReceiver(addExternalReceiverData: AddExternalReceiverData) {  
    ReceiversStdApi        .receiversStdService        .addExternalReceiver(            addExternalReceiverData = addExternalReceiverData,            callback = object : ApiCallback<AddExternalReceiverResult> {                override fun onSuccess(response: AddExternalReceiverResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun addExternalReceiver(addExternalReceiverData: AddExternalReceiverData): AddExternalReceiverResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .addExternalReceiver(addExternalReceiverData = addExternalReceiverData)```  

### 3.2 addWalletReceiver

Asynchronous. Online.

This method allows user to add wallet receiver which are already added to database.

#### 3.2.1 Input  

**`AddWalletReceiverData`**  

| Parameter    | Type    | Description           |  
|--------------|---------|-----------------------|  
| phoneNumber  | String  | Phone number.         |  
| displayName  | String  | Display name.         |  
| firstName    | String? | Optional. First name. |  
| lastName     | String? | Optional. Last name.  |  
| dcReceiverId | Int     | User identifier.      |  

#### 3.2.2 Output  

##### 3.2.2.1 Success

Success callback with AddWalletReceiverResult model.

**`AddWalletReceiverResult`**  

| Parameter | Type             | Description     |  
|-----------|------------------|-----------------|  
| receiver  | AddReceiverModel | Added receiver. |  

**`AddReceiverModel`**  

| Parameter      | Type              | Description                                                       |  
|----------------|-------------------|-------------------------------------------------------------------|  
| id             | Long              | Receiver identifier.                                              |  
| firstName      | String            | First name.                                                       |  
| lastName       | String            | Last name.                                                        |  
| phoneNumber    | String            | Phone number.                                                     |  
| displayName    | String            | Display name.                                                     |  
| lastFourDigits | String?           | Conditional. Card last 4 digits. Empty for [WALLET] type.         |  
| bin            | String?           | Conditional. Card bin. Empty for [WALLET] type.                   |  
| receiverType   | ReceiverTypeValue | Value class encapsulating sample type as a [WALLET] String field. |  

##### 3.2.2.2 Failure

Failure callback with throwable.

#### 3.2.3 Sample  

**`Standard Callback`**  

```kotlin  
fun addWalletReceiver(addWalletReceiverData: AddWalletReceiverData) {  
    ReceiversStdApi        .receiversStdService        .addWalletReceiver(            addWalletReceiverData = addWalletReceiverData,            callback = object : ApiCallback<AddWalletReceiverResult> {                override fun onSuccess(response: AddWalletReceiverResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun addWalletReceiver(addWalletReceiverData: AddWalletReceiverData): AddWalletReceiverResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .addWalletReceiver(addWalletReceiverData = addWalletReceiverData)```  

### 3.3 deleteReceiver

Asynchronous. Online.

This method allow user to delete a friend.

#### 3.3.1 Input  

**`DeleteReceiverData`**  

| Parameter  | Type | Description          |  
|------------|------|----------------------|  
| receiverId | Long | Receiver identifier. |  

#### 3.3.2 Output  

##### 3.3.2.1 Success

Success callback with DeleteReceiverResult model.

**`DeleteReceiverResult`**  

##### 3.3.2.2 Failure

Failure callback with throwable.

#### 3.3.3 Sample  

**`Standard Callback`**  

```kotlin  
fun deleteReceiver(deleteReceiverData: DeleteReceiverData) {  
    ReceiversStdApi        .receiversStdService        .deleteReceiver(            deleteReceiverData = deleteReceiverData,            callback = object : ApiCallback<DeleteReceiverResult> {                override fun onSuccess(response: DeleteReceiverResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun deleteReceiver(deleteReceiverData: DeleteReceiverData): DeleteReceiverResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .deleteReceiver(deleteReceiverData = deleteReceiverData)```  

### 3.4 getActiveAccounts

Asynchronous. Online.

Method is used to find users with valid card (not expired, strong verified). Response will contain phone numbers with user and card identifiers. Users without accepted terms of service or without valid card will not be returned in response. If user has multiple cards that match criteria response will contain only user’s default card id.

#### 3.4.1 Input  

**`ActiveAccountsData`**  

| Parameter    | Type        | Description                                                                                  |  
|--------------|-------------|----------------------------------------------------------------------------------------------|  
| phoneNumbers | Set<String> | Phone numbers each of which identifiers one user.  Size must be between 1 and 100 inclusive. |  

#### 3.4.2 Output  

##### 3.4.2.1 Success

Success callback with GetActiveAccountsResult model.

**`GetActiveAccountsResult`**  

| Parameter      | Type                    | Description             |  
|----------------|-------------------------|-------------------------|  
| activeAccounts | Set<ActiveAccountModel> | Set of active accounts. |  

**`ActiveAccountModel`**  

| Parameter   | Type   | Description      |  
|-------------|--------|------------------|  
| phoneNumber | String | Phone number.    |  
| userId      | Long   | User identifier. |  
| cardId      | Long   | Card identifier. |  

##### 3.4.2.2 Failure

Failure callback with throwable.

Possible types of exceptions:  

| Exception           | Description                         |  
|---------------------|-------------------------------------|  
| InvalidPhoneNumbers | Phone numbers has incorrect format. |  

#### 3.4.3 Sample  

**`Standard Callback`**  

```kotlin  
fun getActiveAccounts(getActiveAccountsData: GetActiveAccountsData) {  
    ReceiversStdApi        .receiversStdService        .getActiveAccounts(            getActiveAccountsData = getActiveAccountsData,            callback = object : ApiCallback<GetActiveAccountsResult> {                override fun onSuccess(response: GetActiveAccountsResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun getActiveAccounts(getActiveAccountsData: GetActiveAccountsData): GetActiveAccountsResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .getActiveAccounts(getActiveAccountsData = getActiveAccountsData)```  

### 3.5 getReceivers

Asynchronous. Online.

This method is used to get receivers list.

#### 3.5.1 Input

No input parameters.

#### 3.5.2 Output  

##### 3.5.2.1 Success

Success callback with GetReceiversResult model.

**`GetReceiversResult`**  

| Parameter | Type                 | Description        |  
|-----------|----------------------|--------------------|  
| receivers | List\<ReceiverModel> | List of receivers. |  

**`ReceiverModel`**  

| Parameter             | Type                       | Description                   |  
|-----------------------|----------------------------|-------------------------------|  
| firstName             | String                     | First name.                   |  
| lastName              | String                     | Last name.                    |  
| phoneNumber           | String                     | Phone number.                 |  
| displayName           | String                     | Display name.                 |  
| receiverWalletEntries | List\<ReceiverWalletModel> | Receiver wallet entries list. |  

**`ReceiverWalletModel`**  

| Parameter         | Type              | Description                                                     |  
|-------------------|-------------------|-----------------------------------------------------------------|  
| receiverId        | Long              | Receiver identifier.                                            |  
| receiverType      | ReceiverType      | Deprecated. One of: [WALLET], [EXTERNAL].                       |  
| receiverTypeValue | ReceiverTypeValue | Value class encapsulating sample type as a [value] String field |  
| lastFourDigits    | String?           | Conditional. Card last 4 digits. Empty for [WALLET] type.       |  
| bin               | String?           | Card bin. Conditional. Card bin. Empty for [WALLET] type.       |  
| phoneNumber       | String            | Receiver phone number.                                          |  

**`ReceiverType (deprecated)`**  

| Type     | Description               |  
|----------|---------------------------|  
| WALLET   | Wallet card receiver.     |  
| EXTERNAL | External card receiver.   |  
| UNKNOWN  | Unknown type of receiver. |  

**`ReceiverTypeValue`**  

| Value    | Description             | Supporting const           |  
|----------|-------------------------|----------------------------|  
| WALLET   | Wallet card receiver.   | ReceiverTypeValue.WALLET   |  
| EXTERNAL | External card receiver. | ReceiverTypeValue.EXTERNAL |  

##### 3.5.2.2 Failure

Failure callback with throwable.

#### 3.5.3 Sample  

**`Standard Callback`**  

```kotlin  
fun getReceivers() {  
    ReceiversStdApi        .receiversStdService        .getReceivers(            callback = object : ApiCallback<GetReceiversResult> {                override fun onSuccess(response: GetReceiversResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun getReceivers(): GetReceiversResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .getReceivers()```  

### 3.6 updateReceiver

Asynchronous. Online.

This method allow user to update receiver. For a receiver of the type WALLET you can update only the field: displayName. For a receiver of the type EXTERNAL you can update the fields: phoneNumber, displayName, firstName, lastName, cardNumber.

#### 3.6.1 Input  

**`UpdateReceiverData`**  

| Parameter          | Type       | Description                     |  
|--------------------|------------|---------------------------------|  
| receiverId         | Long       | Receiver identifier.            |  
| displayName        | String?    | Optional. Display name.         |  
| phoneNumber        | String?    | Optional. Phone number.         |  
| cardNumber         | CharArray? | Optional. Card number.          |  
| cardExpirationDate | CharArray? | Optional. Card expiration date. |  

#### 3.5.2 Output  

##### 3.5.2.1 Success

Success callback with UpdateReceiverResult model.

**`UpdateReceiverResult`**  

##### 3.5.2.2 Failure

Failure callback with throwable.

#### 3.5.3 Sample  

**`Standard Callback`**  

```kotlin  
fun updateReceiver(updateReceiverData: UpdateReceiverData) {  
    ReceiversStdApi        .receiversStdService        .updateReceiver(            updateReceiverData = updateReceiverData,            callback = object : ApiCallback<UpdateReceiverResult> {                override fun onSuccess(response: UpdateReceiverResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun updateReceiver(updateReceiverData: UpdateReceiverData): UpdateReceiverResult =  
    ReceiversCoroutineApi        .receiversCoroutineService        .updateReceiver(updateReceiverData = updateReceiverData)```  

___  

## 4. DOCUMENT CHANGELOG

### 4.1. Version 1.0.0

- Created.  

### 4.2. Version 1.0.5

- Disables obfuscation and pinning for debug.  

### 4.3 Version 1.0.6

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

### 4.4 Version 1.0.8

- Updates internal mechanism responsible for date encryption.  

### 4.5 Version 1.0.9

- Added `UNKNOWN` type to `ReceiverType` enum model.  
- Marked `receiverType` field in `ReceiverWalletModel` model with @Deprecated.  
- Added corresponding value class field `receiverTypeValue` for deprecated field.  

### 4.6 Version 1.0.10

- Improved SDKs deploying.  

### 4.7 Version 2.0.0

- Added missing `phoneNumber` field in `ReceiverWalletModel`  

### 4.8 Version 2.0.1

- Internal changes have been introduced to improve build process.  

### 4.9 Version 2.0.2

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

### 4.10 Version 2.0.3

- Internal changes improving SDK delivery process.  

### 4.11 Version 2.0.4

- Added `receiver` field to `AddExternalReceiverResult` and `AddWalletReceiverResult` models.  

### 4.12 Version 2.0.5

- Internal. Updates build utilities.  

### 4.13 Version 2.0.6

- Internal changes improving SDK.  

- ### 4.14 Version 2.0.7

- Internal changes regarding `getActiveAccounts` method  

### 4.15 Version 2.0.8

- Internal changes. Updated supported token handling.  

### 4.16 Version 2.0.9

- Internal changes improving SDK.

Receivers SDK

Table of Contents

1. Receivers SDK Overview

1.1. What is Receivers SDK?

1.2. How Receivers SDK works?

1.3. Versioning and backward compatibility

2. Technical overview

2.1. Basic information

2.1.1 Facade

2.1.2 Multiple facade types

2.1.3 Method structure

2.2 Basic configuration

2.2.1 Min SDK Version

2.2.2 Artifactory

2.2.3 SDKs version

2.2.1 Source code obfuscation and optimization

2.3 Receivers SDK Setup

2.3.1 Input

2.3.2 Sample

2.4 Error handling

3 Receivers service

3.1 addExternalReceiver

3.1.1 Input

3.1.2 Output

3.1.2.1 Success

3.1.2.2 Failure

3.1.3 Sample