Transfers SDK
Version. 1.0.18
Table of Contents
-
2.1. Basic information
2.2. Basic configuration
2.3. Transfers SDK Setup
2.4. Error handling
-
3.1. calculateCommission
3.2. getCurrencyRate
3.3. determineCurrency
3.6. mcSend
3.7. sendMoney
-
4.1 Version 1.0.0
4.2 Version 1.0.7
4.3 Version 1.0.8
4.4 Version 1.0.9
4.5 Version 1.0.11
4.6 Version 1.0.12
4.7 Version 1.0.13
4.8 Version 1.0.14
4.9 Version 1.0.15
4.10 Version 1.0.16
4.11 Version 1.0.17
4.12 Version 1.0.18
1. Transfers SDK Overview
1.1. What is Transfers SDK?
The Transfers SDK is a module dedicated for making transactions from one user payment card to
another user payment card with associated phone number as an identifier.
1.2. How Transfers SDK works?
Transfers SDK requires Mobile DC SDK as a dependency.
It’s required for the Transfers 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, Transfers SDK setup and available
methods.
2.1. Basic information
2.1.1 Facade
Facade is entry point to communication with Transfers SDK.
2.1.2 Multiple facade types
P2P Transfers SDK provides two public API's with same functionalities, the API's are:
- TransfersCoroutineService for projects which uses Kotlin programming language and Coroutines.
- TransfersStdService 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
Transfers 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:transfers:{version}'} For debugging purposes:
dependencies{
implementation "pl.upaid.module:mobiledc:{version}-debug" implementation 'com.verestro.module:transfers: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 Transfers SDK Setup
Available configuration methods:
- TransfersCoroutineApi.init(configuration: Configuration)
- TransfersStdApi.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
TransfersStdApi
fun init(configuration: Configuration) {
TransfersStdApi.init(configuration)} TransfersCoroutineApi
fun init(configuration: Configuration) {
TransfersCoroutineApi.init(configuration)} 2.4 Error handling
SDK returns errors by TransfersSdkException, which could be catched by application and shown on UI
with detailed message.
Table below describes general exception types.
TransfersSdkException
| 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 Transfers service
3.1 calculateCommission
Asynchronous. Online.
This method is used to receive information about the commission that will be charged for the transaction. 3.1.1 Input
CalculateCommissionData
| Parameter | Type | Description |
|---|---|---|
| amount | Long | Amount in minor currency unit. |
| type | CalculateCommissionType | One of [RECEIVER] or [SENDER]. |
| sender | CalculateCommissionSender | Sender data. |
| receiver | CalculateCommissionReceiver | Receiver data. |
CalculateCommissionType
| Type | Description |
|---|---|
| RECEIVER | The transaction will be sent with given amount. |
| SENDER | The transaction will be received with given amount. |
CalculateCommissionSender
| Parameter | Type | Description |
|---|---|---|
| cardId | String | Wallet cardId belongs to sender account. |
| currency | String | Transaction currency. |
CalculateCommissionReceiver
| Parameter | Type | Description |
|---|---|---|
| userId | Long? | Conditional. Receiver wallet user id. Required if receiverType is [WALLET_CARD_ID]. |
| card | CharArray? | Conditional. Card data (bare card number, card id, empty). Depends of receiverType property. |
| receiverType | CalculateCommissionReceiverType | Receiver type. One of: [EMPTY, WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER]. |
| currency | String | Receiver currency. |
CalculateCommissionReceiverType
| Type | Description |
|---|---|
| EMPTY | Means that the receiver have the same card data like sender. |
| WALLET_CARD_ID | Wallet card identifier. |
| FRIEND_ID | Receiver identifier. |
| BARE_CARD_NUMBER | Card PAN number. |
3.1.2 Output
3.1.2.1 Success
Success callback with CalculateCommissionResult model. CalculateCommissionResult
| Parameter | Type | Description |
|---|---|---|
| commission | Long | Commission value. |
| transactionCommissions | List<CalculateCommissionTransactionCommission> | Transaction commissions. |
| revaluationResult | CalculateCommissionRevaluationResult | Amount (in pennies) of funding transaction in fundingCurrency. |
| isInternalTransaction | Boolean | Flag determining whether the transaction path is internal. |
CalculateCommissionTransactionCommission
| Parameter | Type | Description |
|---|---|---|
| value | Long | Value of calculated commission (in pennies). |
| bigDecimalValue | Double | Value of calculated commission. |
| currencyExponent | Long | Decimal places in currency. |
| currency | String | Commission value currency code the same as sender’s card currency when commission is for Funding or the same as receiver’s card currency when commission is for Payment. |
| commissionConfiguration | CalculateCommissionConfiguration | Commission configuration. |
CalculateCommissionConfiguration
| Parameter | Type | Description |
|---|---|---|
| currency | String | Partner/Merchant currency. |
| commissionType | String | Commission type [PROVISION, PARTNER, FENIGE, ACCEPTANCE NETWORK]. |
| reconciliationType | CalculateCommissionReconciliationType | Deprecated. [PLUS, MINUS, DEPOSITED] |
| reconciliationTypeValue | CalculateCommissionReconciliationTypeValue | Value class encapsulating sample type as a [value] String field. |
| geographicScope | String | Type of transaction scope [DOMESTIC, CROSSBORDER]. |
| transactionTypeData | CalculateCommissionTransactionTypeData | Transaction type for MoneySend Funding or MoneySend Payment. |
CalculateCommissionReconciliationType (deprecated)
| Type | Description |
|---|---|
| PLUS | Means that the commission will be added to the amount sent (the amount charged from the sender will be increased by a commission). |
| MINUS | Means that the commission will be deducted from the amount received (the amount that will be received by the receiver will be reduced by the commission). |
| DEPOSITED | Means that the commission during the transaction will neither be subtracted nor added (the amount to be received by the receiver is the same as the amount sent). |
| UNKNOWN | Unknown type. |
CalculateCommissionReconciliationTypeValue
| Value | Description | Supporting const |
|---|---|---|
| PLUS | Means that the commission will be added to the amount sent (the amount charged from the sender will be increased by a commission). | CalculateCommissionReconciliationTypeValue.PLUS |
| MINUS | Means that the commission will be deducted from the amount received (the amount that will be received by the receiver will be reduced by the commission). | CalculateCommissionReconciliationTypeValue.MINUS |
| DEPOSITED | Means that the commission during the transaction will neither be subtracted nor added (the amount to be received by the receiver is the same as the amount sent). | CalculateCommissionReconciliationTypeValue.DEPOSITED |
CalculateCommissionTransactionTypeData
| Parameter | Type | Description |
|---|---|---|
| id | String | Id of transaction: funding or payment. |
| name | String | Name of transaction’s type: MoneySend Funding or MoneySend Payment. |
CalculateCommissionRevaluationResult
| Parameter | Type | Description |
|---|---|---|
| revaluationFundingAmount | Long | Amount of funding transaction in fundingCurrency. |
| bigDecimalRevaluationFundingAmount | Double | Currency code the same as sender’s card currency. |
| fundingCurrency | String | Amount (in pennies) of payment transaction in paymentCurrency. |
| revaluationPaymentAmount | Long | Amount of payment transaction in paymentCurrency. |
| bigDecimalRevaluationPaymentAmount | Double | Currency code the same as receiver’s card currency. |
| paymentCurrency | String | Details about conversion. |
| determineCurrencyRate | CalculateCommissionDeterminedCurrencyRate | Determine currency rate. |
CalculateCommissionDeterminedCurrencyRate
| Parameter | Type | Description |
|---|---|---|
| from | String | Currency from which exchange rate should be calculated 3-letters ISO 4217 code. |
| to | String | Currency to which exchange rate should be calculated 3-letters ISO 4217 code. |
| currencyRate | String | Currency rate. |
3.1.2.2 Failure
Failure callback with throwable. Possible types of exceptions:
| Exception | Description |
|---|---|
| ReceiverCountryCodeObtainingError | Could not get card country code for receiver. |
| SenderCountryCodeObtainingError | Could not get card country code for sender. |
| FriendDoesNotExist | Receiver not found. |
| SenderCardNotActive | Sender card is not active. |
| ReceiverCardNotActive | Receiver card is not active. |
3.1.3 Sample
Standard Callback
fun calculateCommission(calculateCommissionData: CalculateCommissionData) {
TransfersStdApi .transfersStdService .calculateCommission( calculateCommissionData = calculateCommissionData, callback = object : ApiCallback<CalculateCommissionResult> { override fun onSuccess(response: CalculateCommissionResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun calculateCommission(calculateCommissionData: CalculateCommissionData): CalculateCommissionResult =
TransfersCoroutineApi .transfersCoroutineService .calculateCommission(calculateCommissionData = calculateCommissionData)```
### 3.2 getCurrencyRate Asynchronous. Online.
Method is used to determine currency rate for revaluation from funding to payment (lowerRate) and payment to funding (higherRate).
Notice that lowerRate is used to transaction processing.
Select the direction of revaluation by providing type value.
SENDER - defines amount of funding in given currency. This amount is collected from sender card in selected currency.
RECEIVER - defines amount of payment in given currency. This amount is transferred to receiver card in selected currency.
In case where there’s need of revaluation from one currency to another, system uses lowerRate for SENDER type and higherRate for RECEIVER type.
#### 3.2.1 Input
**`CurrencyRateData`**
| Parameter | Type | Description |
|--------------|--------|------------------------------------------------------------------------------------|
| currencyFrom | String | Currency from which exchange rate should be calculated. 3-letters `ISO 4217` code. |
| currencyTo | String | Currency to which exchange rate should be calculated. 3-letters `ISO 4217` code. |
#### 3.2.2 Output
##### 3.2.2.1 Success Success callback with CurrencyRateResult model.
**`CurrencyRateResult`**
| Parameter | Type | Description |
|------------|--------|-----------------------|
| lowerRate | String | Lower rate exchange. |
| higherRate | String | Higher rate exchange. |
##### 3.2.2.2 Failure Failure callback with throwable.
#### 3.2.3 Sample
**`Standard Callback`**
```kotlin
fun currencyRate(currencyRateData: CurrencyRateData) {
TransfersStdApi .transfersStdService .getCurrencyRate( currencyRateData = currencyRateData, callback = object : ApiCallback<CurrencyRateResult> { override fun onSuccess(response: CurrencyRateResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun currencyRate(currencyRateData: CurrencyRateData): CurrencyRateResult =
TransfersCoroutineApi .transfersCoroutineService .getCurrencyRate(currencyRateData = currencyRateData)```
### 3.3 determineCurrency Asynchronous. Online.
Determines currencies applied for given sender and receiver cards.
#### 3.3.1 Input
**`DetermineCurrencyData`**
| Parameter | Type | Description |
|--------------|---------------------------|-----------------------------------------------|
| senderCardId | String | Wallet cardId that belongs to sender account. |
| receiver | DetermineCurrencyReceiver | Receiver data. |
**`DetermineCurrencyReceiver`**
| Parameter | Type | Description |
|--------------|-------------------------------|--------------------------------------------------------------------------------------------------|
| userId | String? | Conditional. Receiver wallet user id. Required if receiverType is set to: [WALLET_CARD_ID]. |
| receiverType | DetermineCurrencyReceiverType | Receiver type. One of: [EMPTY, WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER]. |
| card | CharArray? | Conditional. Card data. Depends of receiverType property [WALLET_CARD_ID] or [BARE_CARD_NUMBER]. |
**`DetermineCurrencyReceiverType`**
| Type | Description |
|------------------|--------------------------------------------------------------|
| EMPTY | Means that the receiver have the same card data like sender. |
| WALLET_CARD_ID | Wallet card identifier. |
| FRIEND_ID | Friend identifier. |
| BARE_CARD_NUMBER | Card PAN number. |
#### 3.3.2 Output
##### 3.3.2.1 Success Success callback with DetermineCurrencyResult model
**`DetermineCurrencyResult`**
| Parameter | Type | Description |
|-------------------------|----------------|-----------------------------------------------|
| senderCurrencies | List\<String> | Sender card supported currencies. |
| senderDefaultCurrency | String | Sender default currency. |
| receiverCurrencies | List\<String>? | Optional. Receiver card supported currencies. |
| receiverDefaultCurrency | String? | Optional. Receiver default currency. |
##### 3.3.2.2 Failure Failure callback with throwable
Possible types of exceptions:
| Exception | Description |
|-----------------------|------------------------------|
| FriendDoesNotExist | Receiver not found. |
| SenderCardNotActive | Sender card is not active. |
| ReceiverCardNotActive | Receiver card is not active. |
#### 3.3.3 Sample
**`Standard Callback`**
```kotlin
fun determineCurrency(determineCurrencyData: DetermineCurrencyData) {
TransfersStdApi .transfersStdService .determineCurrency( determineCurrencyData = determineCurrencyData, callback = object : ApiCallback<DetermineCurrencyResult> { override fun onSuccess(response: DetermineCurrencyResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun determineCurrency(determineCurrencyData: DetermineCurrencyData): DetermineCurrencyResult =
TransfersCoroutineApi .transfersCoroutineService .determineCurrency(determineCurrencyData = determineCurrencyData)```
### 3.4 finalizeAuthentication Asynchronous. Online.
This method is used to finalize authentication using 3-D Secure 2.0 standard.
#### 3.4.1 Input
**`FinalizeAuthenticationData`**
| Parameter | Type | Description |
|------------------|--------|---------------------------------------------------------------------------------|
| authenticationId | String | Authentication id used in previous methods in the 3-D Secure 2.0 standard flow. |
#### 3.4.2 Output
##### 3.4.2.1 Success Success callback with FinalizeAuthenticationResult model
**`FinalizeAuthenticationResult`**
| Parameter | Type | Description |
|-----------------------------|-----------------------------|-----------------------------------|
| finalizeAuthenticationModel | FinalizeAuthenticationModel | Unique authentication identifier. |
**`FinalizeAuthenticationModel`**
| Parameter | Type | Description |
|-------------------------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| authenticationId | String | Unique authentication identifier. |
| authenticationStatusType | AuthenticationStatusType | Deprecated. Indicates whether a transaction qualifies as an authenticated transaction or account verification. |
| authenticationStatusTypeValue | AuthenticationStatusTypeValue | Value class encapsulating sample type as a [value] String field |
| transactionXId | String | Indicates the transaction Xid from recurring initial authentication. |
| cavv | String | This property will be valid if the authenticationStatusType is [VERIFICATION_SUCCESSFUL] or [ATTEMPTS_PROCESSING_PERFORMED]. May be used to provide proof of authentication. |
| eci | String | This property will be valid if the authenticationStatusType is [VERIFICATION_SUCCESSFUL] or [ATTEMPTS_PROCESSING_PERFORMED]. Contains the two digit ECI (Electronic Commerce Indicator) value. |
**`AuthenticationStatusType (deprecated)`**
| Type | Description |
|------------------------------------|-------------------------------------------------------------|
| VERIFICATION_SUCCESSFUL | Authentication/account verification successful. |
| NOT_AUTHORIZED | Not authenticated/ not verified. |
| COULD_NOT_BE_PERFORMED | Authentication/account verification could not be performed. |
| ATTEMPTS_PROCESSING_PERFORMED | Attempts processing performed. |
| CHALLENGE_REQUIRED | Challenge required. |
| AUTHENTICATION_REJECTED | Authentication/account verification rejected. |
| DECOUPLED_AUTHENTICATION_CONFIRMED | Challenge required. |
| INFORMATIONAL_ONLY | Information only. |
| UNKNOWN | Unknown. |
**`AuthenticationStatusTypeValue`**
| Value | Description | Supporting const |
|-------|-------------------------------------------------------------|------------------------------------------------------------------|
| Y | Authentication/account verification successful. | AuthenticationStatusTypeValue.VERIFICATION_SUCCESSFUL |
| N | Not authenticated/ not verified. | AuthenticationStatusTypeValue.NOT_AUTHORIZED |
| U | Authentication/account verification could not be performed. | AuthenticationStatusTypeValue.COULD_NOT_BE_PERFORMED |
| A | Attempts processing performed. | AuthenticationStatusTypeValue.ATTEMPTS_PROCESSING_PERFORMED |
| C | Challenge required. | AuthenticationStatusTypeValue.CHALLENGE_REQUIRED |
| R | Authentication/account verification rejected. | AuthenticationStatusTypeValue.AUTHENTICATION_REJECTED |
| D | Challenge required. | AuthenticationStatusTypeValue.DECOUPLED_AUTHENTICATION_CONFIRMED |
| I | Information only. | AuthenticationStatusTypeValue.INFORMATIONAL_ONLY |
##### 3.4.2.2 Failure Failure callback with throwable
#### 3.4.3 Sample
**`Standard Callback`**
```kotlin
fun finalizeAuthentication(finalizeAuthenticationData: FinalizeAuthenticationData) {
TransfersStdApi .transfersStdService .finalizeAuthentication( finalizeAuthenticationData = finalizeAuthenticationData, callback = object : ApiCallback<FinalizeAuthenticationResult> { override fun onSuccess(response: FinalizeAuthenticationResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun finalizeAuthentication(finalizeAuthenticationData: FinalizeAuthenticationData): FinalizeAuthenticationResult =
TransfersCoroutineApi .transfersCoroutineService .finalizeAuthentication(finalizeAuthenticationData = finalizeAuthenticationData)```
### 3.5 initializeAuthentication Asynchronous. Online.
This method is used to initialize authentication using 3-D Secure 2.0 standard.
#### 3.5.1 Input
**`InitializeAuthenticationData`**
| Parameter | Type | Description |
|---------------------------------------------|---------------------------------------------|----------------------------------------------------------------------------------|
| authenticationId | String | Authentication id used in previous methods in the 3-D Secure 2.0 standard flow . |
| amount | Long | Authentication amount. |
| currency | String | Authentication currency (for example `PLN`, `USD`). `ISO 4217` Alpha-3. |
| cardId | String | Wallet cardId belongs to sender account. |
| initializeAuthenticationAdditionalInfoModel | InitializeAuthenticationAdditionalInfoModel | Additional info model. |
| initializeAuthenticationConfigModel | InitializeAuthenticationConfigModel | Authentication config model. |
**`InitializeAuthenticationAdditionalInfoModel`**
| Parameter | Type | Description |
|--------------|--------|----------------------------------------------------------------------------------------------------|
| screenHeight | String | This field contains the total height of the cardholder’s screen in pixels. Pattern: `^[0-9]{1,6}$` |
| screenWidth | String | This field contains the total width of the cardholder’s screen in pixels. Pattern: `^[0-9]{1,6}$` |
| userAgent | String | This field contains the exact content of the HTTP User-Agent header. ISO 4217 Alpha-3. |
**`InitializeAuthenticationConfigModel`**
| Parameter | Type | Description |
|------------------------------|---------------------------------------------------|----------------------------------------------------------------------------------------------------|
| threeDsMethodNotificationUrl | String | The URL to which the ACS will post threeDsMethodData when the hidden iframe post form from browse. |
| challengeNotificationUrl | String | The URL to which the final challenge response is POSTed. |
| requestChallengeIndicator | InitializeAuthenticationRequestChallengeIndicator | Indicates whether a challenge is requested for this transaction. |
| authenticationType | InitializeAuthenticationType | Configuration prepared for specific type. |
**`InitializeAuthenticationRequestChallengeIndicator`**
| Type | Description |
|-----------------------------------|-------------------------------------------|
| NO_PREFERENCE | No preference |
| CHALLENGE_NOT_REQUESTED | Challenge not requested. |
| CHALLENGE_REQUESTED_MANDATE | Challenge requeseted mandate. |
| CHALLENGE_PREFER_BY_REQUESTOR_3DS | Challenge prefer by 3-D Secure requestor. |
**`InitializeAuthenticationType`**
| Type | Description |
|----------------------|-----------------------|
| ADD_CARD | Add card. |
| VERIFY_CARDHOLDER | Verify cardholder. |
| QUASI_CASH | Quasi cash. |
| PAYMENT | Payment. |
| COF_INITIAL | COF initial. |
| INSTALLMENT_PAYMENT | Installment payment. |
| RECURRING_INITIAL | Recurring initial. |
| MOTO | Moto. |
| RECURRING_SUBSEQUENT | Recurring subsequent. |
**`InitializeAuthenticationCallback`**
| Function | Parameter |
|---------------------|----------------------------------------------------------------------------------------|
| onThreeDsFinished | initializeAuthenticationFrictionlessResult: InitializeAuthenticationFrictionlessResult |
| onChallengeRequired | initializeAuthenticationChallengeResult: InitializeAuthenticationChallengeResult |
| onFailure | error: Throwable |
#### 3.5.2 Output
##### 3.5.2.1 Success Success InitializeAuthenticationResult or onChallengeRequired callback with theirs result models.
**`InitializeAuthenticationResult`**
| Parameter | Type | Description |
|--------------------------------|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| initializeAuthenticationResult | InitializeAuthenticationResult | Object return InitializeAuthenticationChallengeModel for challenge mode or return InitializeAuthenticationFrictionlessResult for 3-D Secure success. |
**`InitializeAuthenticationFrictionlessResult`**
| Parameter | Type | Description |
|-------------------------------------------|-------------------------------------------|--------------------------|
| initializeAuthenticationFrictionlessModel | InitializeAuthenticationFrictionlessModel | Frictionless data model. |
**`InitializeAuthenticationFrictionlessModel`**
| Parameter | Type | Description |
|-------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| authenticationId | String | Unique authentication identifier. |
| authenticationStatusType | AuthenticationStatusType | Deprecated. Authentication status type. |
| authenticationStatusTypeValue | AuthenticationStatusTypeValue | Value class encapsulating sample type as a [value] String field |
| transactionXId | String | This field indicates the transactionXid from recurring initial authentication. |
| cavv | String | This property is determined by the Access Control Server. This property will be valid if the authenticationStatusType is [VERIFICATION_SUCCESSFUL] or [ATTEMPTS_PROCESSING_PERFORMED]. The value may be used to provide proof of authentication. |
| eci | String | This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the authenticationStatusType is [VERIFICATION_SUCCESSFUL] or [ATTEMPTS_PROCESSING_PERFORMED]. |
| threeDsMode | InitializeAuthenticationThreeDsMode | Deprecated. Status should be [FRICTIONLESS]. |
| threeDsModeValue | InitializeAuthenticationThreeDsModeValue | Value class encapsulating sample type as a [value] String field. Value should be [FRICTIONLESS]. |
**`InitializeAuthenticationChallengeResult`**
| Parameter | Type | Description |
|----------------------------------------|----------------------------------------|-----------------------|
| initializeAuthenticationChallengeModel | InitializeAuthenticationChallengeModel | Challenge data model. |
**`InitializeAuthenticationChallengeModel`**
| Parameter | Type | Description |
|-------------------------|------------------------------------------|------------------------------------------------------------------------------------------------|
| authenticationId | String | Unique authentication identifier. |
| acsUrl | String | Data for building a form such as challengeHtmlFormBase64. |
| creq | String | Data for building a form such as challengeHtmlFormBase64. |
| challengeHtmlFormBase64 | String | This field is a `BASE64` encrypted html source file containing the challenge 3-D Secure frame. |
| threeDsSessionData | String | ThreeDsSessionData value. |
| threeDsMode | InitializeAuthenticationThreeDsMode | Deprecated. Status should be [CHALLENGE]. |
| threeDsModeValues | InitializeAuthenticationThreeDsModeValue | Value class encapsulating sample type as a [value] String field. Value should be [CHALLENGE]. |
**`InitializeAuthenticationThreeDsMode (deprecated)`**
| Type | Description |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------|
| FRICTIONLESS | Successful authentication. The authentication process was finished. |
| THREE_DS_METHOD | The case will no longer be supported. |
| CHALLENGE | Required authentication challenge process from given data and then continue with the result using finalizeAuthentication method. |
| UNKNOWN | May appear in case of a parsing error. |
**`InitializeAuthenticationThreeDsModeValue`**
| Value | Description | Supporting const |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| FRICTIONLESS | Successful authentication. The authentication process was finished. | InitializeAuthenticationThreeDsModeValue.FRICTIONLESS |
| THREE_DS_METHOD | The case will no longer be supported. | InitializeAuthenticationThreeDsModeValue.THREE_DS_METHOD |
| CHALLENGE | Required authentication challenge process from given data and then continue with the result using finalizeAuthentication method. | InitializeAuthenticationThreeDsModeValue.CHALLENGE |
**`AuthenticationStatusType (deprecated)`**
| Type | Description |
|------------------------------------|-------------------------------------------------------------|
| VERIFICATION_SUCCESSFUL | Authentication/account verification successful. |
| NOT_AUTHORIZED | Not authenticated/ not verified. |
| COULD_NOT_BE_PERFORMED | Authentication/account verification could not be performed. |
| ATTEMPTS_PROCESSING_PERFORMED | Attempts processing performed. |
| CHALLENGE_REQUIRED | Challenge required. |
| AUTHENTICATION_REJECTED | Authentication/account verification rejected. |
| DECOUPLED_AUTHENTICATION_CONFIRMED | Challenge required. |
| INFORMATIONAL_ONLY | Information only. |
| UNKNOWN | Unknown. |
**`AuthenticationStatusTypeValue`**
| Value | Description | Supporting const |
|-------|-------------------------------------------------------------|------------------------------------------------------------------|
| Y | Authentication/account verification successful. | AuthenticationStatusTypeValue.VERIFICATION_SUCCESSFUL |
| N | Not authenticated/ not verified. | AuthenticationStatusTypeValue.NOT_AUTHORIZED |
| U | Authentication/account verification could not be performed. | AuthenticationStatusTypeValue.COULD_NOT_BE_PERFORMED |
| A | Attempts processing performed. | AuthenticationStatusTypeValue.ATTEMPTS_PROCESSING_PERFORMED |
| C | Challenge required. | AuthenticationStatusTypeValue.CHALLENGE_REQUIRED |
| R | Authentication/account verification rejected. | AuthenticationStatusTypeValue.AUTHENTICATION_REJECTED |
| D | Challenge required. | AuthenticationStatusTypeValue.DECOUPLED_AUTHENTICATION_CONFIRMED |
| I | Information only. | AuthenticationStatusTypeValue.INFORMATIONAL_ONLY |
##### 3.5.2.2 Failure Failure callback with throwable
Possible types of exceptions:
| Exception | Description |
|---------------------|----------------------------|
| SenderCardNotActive | Sender card is not active. |
#### 3.5.3 Sample
**`Standard Callback`**
```kotlin
fun initializeAuthentication(
initializeAuthenticationData: InitializeAuthenticationData) {
TransfersStdApi .transfersStdService .initializeAuthentication( initializeAuthenticationData = initializeAuthenticationData, callback = object : InitializeAuthenticationCallback { override fun onThreeDsFinished(initializeAuthenticationFrictionlessResult: InitializeAuthenticationFrictionlessResult) { // handle successful frictionless case } override fun onChallengeRequired(initializeAuthenticationChallengeResult: InitializeAuthenticationChallengeResult) { // handle successful challenge case }
override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun initializeAuthentication(
initializeAuthenticationData: InitializeAuthenticationData) {
val result: InitializeAuthenticationResult = TransfersCoroutineApi .transfersCoroutineService .initializeAuthentication(initializeAuthenticationData = initializeAuthenticationData) when (result) { is InitializeAuthenticationFrictionlessResult -> { // handle successful frictionless case } is InitializeAuthenticationChallengeResult -> { // handle successful challenge case } }} 3.6 mcSend
Asynchronous. Online.
Method allows sending money in MasterCard Send 2.0. 3.6.1 Input
McSendData
| Parameter | Type | Description |
|---|---|---|
| transactionId | String | A unique transaction reference ID for the transaction. |
| amount | Long | The transaction amount, in the currency identified by the currency field. The decimal point is implied based on the currency. For example, a $1 transaction will be a value of 100. |
| currency | String | The currency for the transaction amount in the amount field. See Currency Codes. For example, for U.S. Dollars, the value is USD. 3-character ISO 4217 alpha-3 code. |
| merchantCategoryCode | String? | Optional. Mastercard-defined merchant category code. This identifies the type of business of the merchant. If provided, this merchant category code should match one of the valid codes set by the Mastercard rules. |
| sender | McSendSender | Sender data. |
| recipient | McSendRecipient | Receiver data. |
| qrData | String? | Optional. The Mastercard QR data for P2M payments. Max length = 237 . |
| transactionPurpose | String? | Optional. The purpose of the transaction. - Valid numeric values: 00 = Family Support, 01 = Regular Labor Transfers (expatriates), 02 = Travel & Tourism, 03 = Education, 04 = Hospitalization and Medical Treatment, 05 = Emergency Need, 06 = Savings, 07 = Gifts, 08 = Other, 09 – 15 = Reserved. |
| additionalMessage | String? | Optional. Message a financial institution will associate to the transfer and may display. Max length is 65. |
McSendSender
| Parameter | Type | Description |
|---|---|---|
| account | String | One of: {Iban id, Wallet Card ID}. Iban id - represented as sha256Hex. |
| cvc2 | CharArray? | Conditional. Sender currency. 3 digits. Required if paymentAccountType is set to: [WALLET_CARD_ID]. |
| addressId | String? | Optional. Address id of user address. If id will be null the default user address will be chosen. |
| paymentAccountType | McSendPaymentAccountType | Depends of sender account. If sender account is set to: [WALLET_CARD_ID]. If sender account is set to: [IBAN_ID]}. |
McSendPaymentAccountType
| Type | Description |
|---|---|
| IBAN_ID | Sender account field should be iban id. |
| WALLET_CARD_ID | Sender account field should be wallet card id. |
McSendRecipient
| Parameter | Type | Description |
|---|---|---|
| name | String | The full name of the recipient. Recommended format: Last Name/Family Name + space + First Name + space . |
| accountUri | String | Conditional. A deposit account or generic account number. Depends of recipient.receiverType property. Required if receiverType is set to: [WALLET_CARD_ID] or [BARE_CARD_NUMBER] |
| address | McSendRecipientAddress | Recipient address. |
| nationality | String? | Optional. The country in which the recipient is a citizen. The 3-character ISO 3166-1 alpha-3 code |
| dateOfBirth | String? | Optional. The date of birth of the recipient. ISO 8601 full date format (YYYY-MM-DD) |
| phone | String? | Optional. The phone number of the receiver. |
| String? | Optional. The email address of the recipient. | |
| governmentIds | List<String>? | Optional. This array contains data strings that each identify a Government ID number for the recipient. |
McSendRecipientAddress
| Parameter | Type | Description |
|---|---|---|
| country | String | The country of the individual. 3-character ISO 3166-1 alpha-3 code. |
| street | String? | Optional. The street address of the individual or merchant. |
| city | String? | Optional. The city of the individual or merchant. |
| state | String? | Optional. State or province of the individual or merchant. If the recipient’s country is USA or CAN, the country’s state or Province is required. |
| postalCode | String? | Optional. The ZIP Code or postal code of the individual or merchant. |
3.6.2 Output
3.6.2.1 Success
Success callback with McSendResult model. McSendResult
| Parameter | Type | Description |
|---|---|---|
| transactionStatus | McSendTransactionStatus | Deprecated. The status of the transaction. |
| transactionStatusValue | McSendTransactionStatusValue | Value class encapsulating sample type as a [value] String field |
| transactionStatusReason | String | Network status description for the transaction. |
McSendTransactionStatus (deprecated)
| Type | Description |
|---|---|
| APPROVED | Transaction approved. |
| DECLINED | Transaction declined. |
| PENDING | The transaction does not currently have a status due to an issue processing the transaction, such as a network communication issue. |
| UNKNOWN | Unknown status. |
McSendTransactionStatusValue
| Value | Description | Supporting const |
|---|---|---|
| APPROVED | Transaction approved. | McSendTransactionStatusValue.APPROVED |
| DECLINED | Transaction declined. | McSendTransactionStatusValue.DECLINED |
| PENDING | The transaction does not currently have a status due to an issue processing the transaction, such as a network communication issue. | McSendTransactionStatusValue.PENDING |
3.6.2.2 Failure
Failure callback with throwable 3.6.3 Sample
Standard Callback
fun mcSend(mcSendData: McSendData) {
TransfersStdApi .transfersStdService .mcSend( mcSendData = mcSendData, callback = object : ApiCallback<McSendResult> { override fun onSuccess(response: McSendResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun mcSend(mcSendData: McSendData): McSendResult =
TransfersCoroutineApi .transfersCoroutineService .mcSend(mcSendData = mcSendData)```
### 3.7 sendMoney Asynchronous. Online.
This method is used to full MoneySend transaction (funding and payment). It is also adding friend as sender after successful transaction.
#### 3.7.1 Input
**`SendMoneyData`**
| Parameter | Type | Description |
|------------------------|----------------------------------|---------------------------------|
| cvc2 | CharArray | Sender card cvc2/cvv2. 3 digits |
| transaction | SendMoneyTransaction | Transaction data. |
| senderDetails | SendMoneySenderDetails | Sender details data. |
| senderAddress | SendMoneySenderAddress | Sender address data. |
| senderCard | SendMoneySenderCard | Sender card data. |
| receiver | SendMoneyReceiver | Receiver data. |
| externalAuthentication | SendMoneyExternalAuthentication? | Optional. Three DS data. |
**`SendMoneyTransaction`**
| Parameter | Type | Description |
|------------------|--------------------------|------------------------------------------------|
| amount | Long | Amount |
| senderCurrency | String | Sender currency. |
| receiverCurrency | String | Receiver currency. |
| transactionType | SendMoneyTransactionType | [SENDER] or [RECEIVER] type transaction payer. |
**`SendMoneyTransactionType`**
| Type | Description |
|----------|----------------------------------------------------------------------------------------------------------------|
| SENDER | Defines amount of funding in given currency. This amount is collected from sender card in selected currency. |
| RECEIVER | Defines amount of payment in given currency. This amount is transferred to receiver card in selected currency. |
**`SendMoneySenderDetails`**
| Parameter | Type | Description |
|------------|---------|------------------------|
| email | String | Email address. |
| personalId | String? | Optional. Personal ID. |
**`SendMoneySenderAddress`**
| Parameter | Type | Description |
|-------------|---------|------------------------------------|
| firstName | String | Sender first name. |
| lastName | String | Sender last name. |
| street | String? | Optional. Street. |
| houseNumber | String? | Optional. House number. |
| city | String? | Optional. City. |
| postalCode | String? | Optional. Postal code. |
| flatNumber | String? | Optional. Flat (apartment) number. |
**`SendMoneySenderCard`**
| Parameter | Type | Description |
|----------------|--------|------------------------------------------|
| expirationDate | String | Sender card expiration date. |
| cardId | String | Wallet cardId belongs to sender account. |
**`SendMoneyReceiver`**
| Parameter | Type | Description |
|--------------|-----------------------|---------------------------------------------------------------------------------------------|
| firstName | String | Receiver first name. |
| lastName | String | Receiver last name. |
| phoneNumber | String | Phone number with prefix. `E.164` standard. |
| displayName | String | Display name. |
| userId | String? | Conditional. Receiver wallet user id. Required if receiverType is set to: [FRIEND_ID]. |
| card | CharArray? | Conditional. Receiver card number. Required if receiverType is set to: [BARE_CARD_NUMBER]. |
| receiverType | SendMoneyReceiverType | Receiver type. One of: [WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER]. |
| walletCardId | String? | Conditional. Receiver wallet card id. Required if receiverType is set to: [WALLET_CARD_ID]. |
**`SendMoneyReceiverType`**
| Type | Description |
|------------------|--------------------------------------------------------------|
| WALLET_CARD_ID | Wallet card identifier. |
| FRIEND_ID | Receiver identifier. |
| EMPTY | Means that the receiver have the same card data like sender. |
| BARE_CARD_NUMBER | Card PAN number. |
**`SendMoneyExternalAuthentication`**
| Parameter | Type | Description |
|----------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| authenticationId | String | Unique authentication identifier. |
| cavv | String | Indicates whether a transaction qualifies as an authenticated transaction or account verification. |
| eci | String | This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. |
| authenticationStatus | String | Information about the status of the process. |
| transactionXId | String | This field indicates the transactionXid from recurring initial authentication. |
#### 3.7.2 Output
##### 3.7.2.1 Success Success callback with SendMoneyResult model.
**`SendMoneyResult`**
| Parameter | Type | Description |
|---------------|--------|-----------------|
| transactionId | String | Transaction id. |
##### 3.6.2.2 Failure Failure callback with throwable.
Possible types of exceptions:
| Exception | Description |
|-----------------------------------|-----------------------------------------------|
| ReceiverCountryCodeObtainingError | Could not get card country code for receiver. |
| SenderCountryCodeObtainingError | Could not get card country code for sender. |
| FriendDoesNotExist | Receiver not found. |
| SenderCardNotActive | Sender card is not active. |
| ReceiverCardNotActive | Receiver card is not active. |
#### 3.7.3 Sample
**`Standard Callback`**
```kotlin
fun sendMoney(sendMoneyData: SendMoneyData) {
TransfersStdApi .transfersStdService .sendMoney( sendMoneyData = sendMoneyData, callback = object : ApiCallback<SendMoneyResult> { override fun onSuccess(response: SendMoneyResult) { // handle success } override fun onFailure(error: Throwable) { // handle error } } )} Kotlin Coroutines
suspend fun sendMoney(sendMoneyData: SendMoneyData): SendMoneyResult =
TransfersCoroutineApi .transfersCoroutineService .sendMoney(sendMoneyData = sendMoneyData)```
___
## 4. DOCUMENT CHANGELOG
### 4.1. Version 1.0.0
- Created.
### 4.2. Version 1.0.7
- Disables obfuscation and pinning for debug.
### 4.3. Version 1.0.8
- Adds isInternalTransaction flag to CalculateCommissionResult model.
### 4.4 Version 1.0.9
- Updated koin to version 3.5.3
- Updated java to 17
- Updated compile and target android version
### 4.5 Version 1.0.11
- Updates internal mechanism responsible for data encryption
### 4.6 Version 1.0.12
- Added `UNKNOWN` type to `CalculateCommissionReconciliationType` and `McSendTransactionStatus` enum
model.
- Marked all enum fields in SDK result models with @Deprecated.
- Added corresponding value classes fields for all deprecated fields.
### 4.7 Version 1.0.13
- Improved SDKs deploying.
### 4.8 Version 1.0.14
- Internal changes have been introduced to improve build process.
### 4.9 Version 1.0.15
- Update koin to version 4.0.4
- Update java to 21
-