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 yourbuild.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.
- 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 theintent_id
from theintent
created at Step 1 as the parameter, you can access your intent details. TheintentDetails.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 possiblestate
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 theintent_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 whichpaymentMethods
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 theintentId
,intentType
,selectedMethodId
,methodType
andmethodMetaData
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.
Updated 8 days ago