Version. 1.0.0
2.1. Basic information
2.2. Basic configuration
2.3. Receivers SDK Setup
2.4. Error handling
3.1. addExternalReceiver
3.2. addWalletReceiver
3.3. deleteReceiver
3.4. getActiveAccounts
3.5. getReceivers
3.6. updateReceiver
4.1 Version 1.0.0
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.
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
SDK is based on semantic versioning.
For example: 1.0.0 ( MAJOR.MINOR.PATCH )
Changes not breaking compatibility:
This section describes basic information about Mobile DC SDK, Receivers SDK setup and available methods.
Facade is entry point to communication with Receivers SDK.
P2P Receivers SDK provides two public API's with same functionalities, the API's are:
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).
Every method description has same structure.
Execution type:
Method type:
Input
Input parameters with name, type and description.
Output
Result delivered by standard Callback with data or result is suspended until the Coroutine completes <
The minSdkVersion must be at least 23 (Android 6.0).
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.upaid.pl/artifactory/libs-release-local/"
}
}
Receivers SDK is available in two versions: debug and release.
The difference between version is debug allows to use application with debugger connected.
Debug version is ended with appendix "-debug" in version name.
Samples below:
For release version, used on production environment in application uploaded to Google Play:
dependencies{
implementation "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:{version}-debug'
}
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
Available configuration methods:
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 |
ReceiversStdApi
fun init(configuration: Configuration) {
ReceiversStdApi.init(configuration)
}
ReceiversCoroutineApi
fun init(configuration: Configuration) {
ReceiversCoroutineApi.init(configuration)
}
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.
Asynchronous. Online.
This method allows user to add external receiver.
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. |
Success callback with AddExternalReceiverResult model. AddExternalReceiverResult is empty class.
Failure callback with throwable.
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)
Asynchronous. Online.
This method allows user to add wallet receiver which are already added to database.
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. |
Success callback with AddWalletReceiverResult model.
AddWalletReceiverResult
Failure callback with throwable.
Standard Callback
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)
Asynchronous. Online.
This method allow user to delete a friend.
DeleteReceiverData
Parameter | Type | Description |
---|---|---|
receiverId | Long | Receiver identifier. |
Success callback with DeleteReceiverResult model.
DeleteReceiverResult
Failure callback with throwable.
Standard Callback
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)
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.
ActiveAccountsData
Parameter | Type | Description |
---|---|---|
phoneNumbers | Set |
Phone numbers each of which identifiers one user. Size must be between 1 and 100 inclusive. |
Success callback with GetActiveAccountsResult model.
GetActiveAccountsResult
Parameter | Type | Description |
---|---|---|
activeAccounts | Set |
Set of active accounts. |
ActiveAccountModel
Parameter | Type | Description |
---|---|---|
phoneNumber | String | Phone number. |
userId | Long | User identifier. |
cardId | Long | Card identifier. |
Failure callback with throwable.
Possible types of exceptions:
Exception | Description |
---|---|
InvalidPhoneNumbers | Phone numbers has incorrect format. |
Standard Callback
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)
Asynchronous. Online.
This method is used to get receivers list.
No input parameters.
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 | One of: [WALLET], [EXTERNAL]. |
lastFourDigits | String? | Conditional. Card last 4 digits. Empty for [WALLET] type. |
bin | String? | Card bin. Conditional. Card bin. Empty for [WALLET] type. |
ReceiverType
Type | Description |
---|---|
WALLET | Wallet card receiver. |
EXTERNAL | External card receiver. |
Failure callback with throwable.
Standard Callback
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()
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.
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. |
Success callback with UpdateReceiverResult model.
UpdateReceiverResult
Failure callback with throwable.
Standard Callback
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)