Android SDK

The MoneyHash Android SDK allows developers to integrate MoneyHash payment processing into their Android applications. The SDK provides a simple and convenient way to accept customer payments, manage subscriptions, and send payouts. This page presents the prerequisites you need to finish before starting the integration, the software requirements, and how to configure the SDK in your app and use it.

Prerequisites

Below, you will find all you need to do before integrating to MoneyHash with Android SDK:

Get Started with MoneyHash to access your own Organization.
Create an Account within your Organization.
Connect providers to your new Account.
Set up your Payment Defaults.
Get your API keys in the dashboard to be able to make API calls.

Requirements

Before integrating the MoneyHash's Android SDK into your system, be sure to meet the following requirements:

Android 5.0 (API level 21) and above.
Android Gradle Plugin 3.5.1.
Gradle 5.4.1+.
AndroidX (as of v11.0.0).

Configuration

To start the integration, you need to install and configure your project's SDK.

Add moneyhash:android to your build.gradle dependencies.

repositories {
    maven{ url "https://jitpack.io" }
}

dependencies {
    implementation 'io.moneyHash:android:1.0.3'
}

Enable viewBinding in your project.

buildFeatures {
  viewBinding true
}

Integrating

After configuring MoneyHash's Android SDK into your application, you can start the integration. Below, you will find the essential steps to use this integration:

First, create an intent with the Payment intent endpoint. This step does not use MoneyHash's Android SDK and is standard for all MoneyHash's integrations, except for HPP. This endpoint requires authentication to be executed properly. You need to provide the Account API Key as a header and send the required data in the request body. Check the Create an Intent page for further explanation.

POST

/api/v1.1/payments/intent/

Create a MoneyHash instance using the MoneyHashSDKBuilder.build method.

import com.moneyhash.sdk.android.core.MoneyHashSDKBuilder
val moneyHash = MoneyHashSDKBuilder.build()

Get intent details: Calling the getIntentDetails method with the intent_id from the intent created at Step 1 as the parameter, you can access your intent details. The intentDetails.state returned can guide you through the actions and methods required to proceed and complete the payment or payout. The table below describes each action related to each possible state value.

moneyHash.getIntentDetails(intentId, IntentType.Payment, onSuccess = { intentDetails ->
   // handle the intent details
}, onFail = { throwable ->
  // handle the error
})

state	Action
`METHOD_SELECTION`	Use `moneyHash.getIntentMethods` to get the different payment methods available for the intent. You can render them natively with your own styles and use `moneyHash.proceedWithMethod` to proceed with one of them after the user selection.
`INTENT_FORM`	Use `moneyHash.renderForm` to start the SDK flow to let MoneyHash handle the flow for you and listen for the result by using `IntentContract()` to track the end of the process.
`INTENT_PROCESSED`	Render your successful confirmation UI with the intent details.
`TRANSACTION_FAILED`	Render your failure UI with the intent details.
`TRANSACTION_WAITING_USER_ACTION`	Render your pending actions confirmation UI with the intent details and `externalActionMessage` if exists on `Transaction`.
`EXPIRED`	Render your intent expired UI.
`CLOSED`	Render your intent closed UI.

Render SDK embed forms and payment integrations

If the state returned is INTENT_FORM you must call the renderForm method to let MoneyHash handle the payment/payout. You can listen for the completion or failure of an intent by providing using the IntentContract(). Or you can use it directly to render the embed form for payment/payout without handling the methods selection native UI.

 private val resultContract =
          registerForActivityResult(IntentContract()) { result ->
        
          }
        
        moneyHash
          .renderForm(
            intentId = "intentId",
            intentType = IntentType.Payment,
            launcher = resultContract,
            resultType = ResultType.RESULT_SCREEN_WITH_CALLBACK 
          )
          // Result type can be RESULT_SCREEN_WITH_CALLBACK or CALLBACK
          //(to not render moneyhash success screen)

Get intent methods: Calling the getIntentMethods sending the intent_id as the parameter, you have access to the available pay-in/pay-out methods, saved cards, and customer balances. For example, you could use this information to predefine a payment method. Or choose which paymentMethods to display to give the customer the option to choose their preferred method.

moneyHash.getIntentMethods(intentId, IntentType.Payment, onSuccess = { intentMethods ->
   // handle the intent methods native UI
}, onFail = { throwable ->
  // handle the error
})

Proceed with payment: Using the proceedWithMethod method, you can proceed with the payment process. You are required to inform the intentId, intentType, selectedMethodId, methodType and methodMetaData to execute this method.

moneyHash
  .proceedWithMethod(
    intentId = "intentId",
    intentType = IntentType.Payment,
    selectedMethodId = "methodId",
    methodType = MethodType.EXPRESS_METHOD, // method type that returned from the intent methods
    methodMetaData = MethodMetaData(
      // optional and can be null
      cvv = "cvv", // required for customer saved cards that requires cvv
    ),
    onSuccess = { intentMethods, intentDetails ->
      // handle the intent methods native UI and updated intent details
    }, onFail = { throwable ->
      // handle the error
    })

Other available Android SDK methods

In addition to the essential steps and methods previously described, the Android SDK provides other methods to customize the user experience. These additional methods are presented and described next.

Reset selected method: You can use the resetSelectedMethod method for different situations:
- Give the customer a button as an option to go back after they already selected a payment method.
- Offer a retry button so your customer can select a different payment method after a transaction has failed.

moneyHash
  .resetSelectedMethod(
    intentId = "intentId",
    intentType = IntentType.Payment,
    onSuccess = { intentMethods, intentDetails ->
      // handle the intent methods native UI and updated intent details
    }, onFail = { throwable ->
      // handle the error
    })

Delete card: Call the deleteSavedCard method to delete a customer's saved card from the system. You can use this option when listing the existing customer's saved cards.

moneyHash
  .deleteSavedCard(
    cardTokenId = "cardTokenId", // card token id that returned in savedCards list in IntentMethods
    intentSecret = "intentSecret", // intent secret that returned in intent details
    onSuccess = {
      // card deleted successfully
    }, onFail = { throwable ->
      // handle the error
    })

Event Listeners

To stay up to date with the events related to payments/payouts, you need to add PaymentActivity / PayoutActivity to AndroidManifest.xml.

<activity android:name="com.moneyhash.sdk.android.payment.PaymentActivity" />

<activity android:name="com.moneyhash.sdk.android.payout.PayoutActivity" />

Responses

To help you proceed and organize your code, we provide all possible response types for the methods you can use on the Android SDK.

enum class IntentType {
    Payment,
    Payout;
}

// Intent methods 

data class IntentMethods(
  val customerBalances: List<CustomerBalance>? = null,
  val paymentMethods: List<PaymentMethod>? = null,
  val expressMethods: List<ExpressMethod>? = null,
  val savedCards: List<SavedCard>? = null,
  val payoutMethods: List<PayoutMethod>? = null
)

data class CustomerBalance(
  val balance: Double? = null,
  val id: String? = null,
  val icon: String? = null,
  val isSelected: Boolean? = null,
  val type: MethodType = MethodType.CUSTOMER_BALANCE
)

data class PaymentMethod(
  val id: String? = null,
  val title: String? = null,
  val isSelected: Boolean? = null,
  val confirmationRequired: Boolean? = null,
  val icons: List<String>? = null,
  val type: MethodType? = MethodType.PAYMENT_METHOD
)

data class PayoutMethod(
  val id: String? = null,
  val title: String? = null,
  val isSelected: Boolean? = null,
  val confirmationRequired: Boolean? = null,
  val icons: List<String>? = null,
  val type: MethodType? = MethodType.PAYOUT_METHOD
)

data class ExpressMethod(
  val id: String? = null,
  val title: String? = null,
  val isSelected: Boolean? = null,
  val confirmationRequired: Boolean? = null,
  val icons: List<String>? = null,
  val type: MethodType? = MethodType.EXPRESS_METHOD
)

data class SavedCard(
  val id: String? = null,
  val brand: String? = null,
  val last4: String? = null,
  val expiryMonth: String? = null,
  val expiryYear: String? = null,
  val country: String? = null,
  val logo: String? = null,
  val requireCvv: Boolean? = null,
  val cvvConfig: CvvConfig? = null,
  val type: MethodType? = MethodType.SAVE_CARD
)

data class CvvConfig(
  val digitsCount: Int? = 0
)

// Intent Details

data class IntentDetails(
  val selectedMethod: String? = null,
  val intent: IntentData? = null,
  val walletBalance: Double? = null,
  val transaction: TransactionData? = null,
  val redirect: RedirectData? = null,
  val state: State? = null
)

data class TransactionData(
  val billingData: String? = null,
  val amount: Double? = null,
  val externalActionMessage: List<String>? = null,
  val amountCurrency: String? = null,
  val id: String? = null,
  val methodName: String? = null,
  val method: String? = null,
  val createdDate: String? = null,
  val status: String? = null,
  val customFields: String? = null,
  val providerTransactionFields: String? = null,
  val customFormAnswers: String? = null
)

data class IntentData(
  val amount: AmountData? = null,
  val secret: String? = null,
  val expirationDate: String? = null,
  val isLive: Boolean? = null,
  val id: String? = null,
  val status: IntentStatus? = null
)

data class AmountData(
  val value: String? = null,
  val formatted: Double? = null,
  val currency: String? = null,
  val maxPayout: Double? = null,
)

data class RedirectData(
  val redirectUrl: String? = null
)

// Method Meta Data
data class MethodMetaData(
  val cvv: String? = null
)

Proguarding

MoneyHash Android SDK is proguard friendly, and the rules are added by default, so you don't need to
care about adding extra proguard rules.

Questions and Issues

Please provide any feedback via a GitHub Issue.

Notifications

After integrating with MoneyHash through the Android SDK, it's recommended you learn how to configure and use Webhooks and Redirects to be able to receive notifications and automatically redirect your customer to where you want with ease.