Android SDK APIs Documentation

Class: `MoneyHashSDKBuilder`

public class MoneyHashSDKBuilder {  
    public constructor()  
    public fun setPublicKey(key: String): MoneyHashSDKBuilder  
    public fun setNativeGooglePayConfig(config: NativeGooglePayConfig): MoneyHashSDKBuilder
    public fun build(): MoneyHashSDK  
}

1. `constructor`

public constructor()

Description: Initializes a new instance of MoneyHashSDKBuilder.
Use Case: Start the configuration process for setting up the MoneyHashSDK.
Example:
```
val sdkBuilder = MoneyHashSDKBuilder()
```

2. `setPublicKey`

public fun setPublicKey(key: String): MoneyHashSDKBuilder

Purpose: Sets the public API key for the MoneyHashSDK, which is essential for authenticating and authorizing API requests.
Use Case: Use this method to provide your public API key obtained from the MoneyHash dashboard before building the SDK instance.
Parameters:
- key: The public API key as a String.
Returns: The MoneyHashSDKBuilder instance to allow method chaining.

Example:

sdkBuilder.setPublicKey("your_public_api_key")

3. `setNativeGooglePayConfig`

public fun setNativeGooglePayConfig(config: NativeGooglePayConfig): MoneyHashSDKBuilder

Purpose: Configures Google Pay integration for displaying the native Google Pay popup within the embedded form. This setup is required to handle the native Google Pay payment flow within the embed flow.
Parameters:
- config: The configuration object containing the necessary details for Google Pay integration. See NativeGooglePayConfig for more details.
Default Values (if no configuration is provided):
- Environment: GooglePayEnvironment.PRODUCTION (Google Pay will operate in the production environment).
- Allowed Cards: A list of all supported card types (AllowedCards.entries).
- Supported Methods: A list of all supported payment methods (SupportedMethods.entries).
Returns: The MoneyHashSDKBuilder instance to allow method chaining.
Use Case: Customize the Google Pay flow to match your specific requirements, including environment, merchant details, and payment method preferences.

Example:

val googlePayConfig = NativeGooglePayConfig(
    environment = GooglePayEnvironment.TEST, // Use TEST for development
    allowedCards = listOf(AllowedCards.VISA, AllowedCards.MASTERCARD),
    supportedMethods = listOf(SupportedMethods.PAN_ONLY)
)

sdkBuilder.setNativeGooglePayConfig(googlePayConfig)

Note: For more details on configuring Google Pay, refer to:

4. `build`

public fun build(): MoneyHashSDK

Description: Builds and returns an instance of MoneyHashSDK configured with the provided settings.
Use Case: After setting all desired configurations using the builder methods, call this method to get the configured MoneyHashSDK instance.
Returns: An instance of MoneyHashSDK.
Example:
```
val moneyHashSDK = sdkBuilder.build()
```

Example

// Initialize the builder  
val sdkBuilder = MoneyHashSDKBuilder()

// Set the public key (obtained from MoneyHash dashboard)  
sdkBuilder.setPublicKey("your_public_api_key")

// Set Google Pay configuration  
val googlePayConfig = NativeGooglePayConfig(
    environment = GooglePayEnvironment.TEST, // Use TEST for development
    allowedCards = listOf(AllowedCards.VISA, AllowedCards.MASTERCARD),
    supportedMethods = listOf(SupportedMethods.PAN_ONLY)
)
sdkBuilder.setNativeGooglePayConfig(googlePayConfig)

// Build the MoneyHashSDK instance  
val moneyHashSDK = sdkBuilder.build()

// Now you can use the moneyHashSDK instance  
moneyHashSDK.setLogLevel(LogLevel.Debug)

Notes:
- For more information on the models used in the configuration, refer to:

Class: `MoneyHashSDK`

A. Methods That Do Not Require an Intent ID

1. `setLogLevel`

fun setLogLevel(logLevel: LogLevel)

Purpose: Configures the verbosity level of the SDK’s internal logging, allowing developers to control the amount of information logged during runtime.
Use Case: Use this method to set the desired level of logging output, which is especially useful for debugging during development or troubleshooting in production. Higher log levels like VERBOSE provide detailed insights into SDK operations, while lower levels like ERROR focus only on critical issues.
Parameters:
- logLevel: The level of detail for logs, chosen from the LogLevel enum.
Returns: This method does not return a value.

Example:

moneyHashSDK.setLogLevel(LogLevel.DEBUG)
println("Log level set to DEBUG")

2. `setLocale`

fun setLocale(locale: SDKLocale)

Purpose: Sets the language preference for the SDK, enabling the display of localized text in the user’s chosen language.
Use Case: Use this method to change the SDK’s locale to match the app’s localization settings. This helps in providing a localized user experience for customers in different regions. Supported languages include English, Arabic, and French.
Parameters:
- locale: The locale to be set, chosen from the SDKLocale enum.
Returns: This method does not return a value.

Example:

moneyHashSDK.setLocale(SDKLocale.ENGLISH)
println("Locale set to English")

3. `setPublicKey`

fun setPublicKey(key: String)

Purpose: Registers the public API key for the SDK, allowing it to authenticate requests to MoneyHash's platform.
Use Case: This method must be called before any other network-based SDK operations to authenticate the application with the MoneyHash platform. The public API key is obtained from the MoneyHash dashboard.
Parameters:
- key: The public API key, which identifies the application to MoneyHash's API.
Returns: This method does not return a value.

Example:

moneyHashSDK.setPublicKey("your_public_api_key")
println("Public key set successfully")

B. Methods That Require the Public Key to Be Set

4. `getMethods` (Using Currency and Amount)

@Throws(MHThrowable::class)
suspend fun getMethods(
    currency: String,
    amount: Double? = null,
    customerId: String? = null,
    flowId: String? = null
): IntentMethods

Purpose: Retrieves available payment methods for a specific transaction, using the currency and amount as key criteria.
Use Case: This method is used when setting up a payment session where no intent ID has been created yet. It allows merchants to dynamically fetch the payment methods that are supported for a given currency and amount. Optionally, customer and flow identifiers can be provided to tailor the payment methods to specific customer profiles or workflows.
Parameters:
- currency: The currency code (e.g., USD, EUR) for the transaction.
- amount: The total amount for the transaction.
- customerId: An optional identifier for the customer making the transaction.
- flowId: An optional identifier for a custom flow or transaction process.
Returns: An IntentMethods object containing the available payment methods.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val methods = moneyHashSDK.getMethods(currency = "USD", amount = 200.0, customerId = "customer-id", flowId = "flow-id")
    println("Available methods: $methods")
} catch (error: MHThrowable) {
    println("Error retrieving methods: ${error.message}")
}

C. Methods That Require Payment Intent ID

5. `getMethods` (Using Intent ID)

@Throws(MHThrowable::class)
suspend fun getMethods(
    intentId: String,
    intentType: IntentType = IntentType.Payment
): IntentMethods

Purpose: Retrieves available payment or payout methods for a specific transaction, based on an existing intent.
Use Case: This method is ideal when you already have a payment or payout intent created, and you want to fetch the available methods to complete the transaction. It is especially useful for ongoing payment sessions or when reloading payment options for a user.
Parameters:
- intentId: The unique identifier for the intent.
- intentType: The type of the intent, such as IntentType.Payment or IntentType.Payout.
Returns: An IntentMethods object containing available methods.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val methods = moneyHashSDK.getMethods(intentId = "intent_id_here", intentType = IntentType.Payment)
    println("Available methods: $methods")
} catch (error: MHThrowable) {
    println("Error retrieving methods: ${error.message}")
}

6. `getIntentDetails`

@Throws(MHThrowable::class)
suspend fun getIntentDetails(
    intentId: String,
    intentType: IntentType = IntentType.Payment
): IntentDetails?

Purpose: Fetches the details of an existing payment or payout intent, including transaction status and associated metadata.
Use Case: This method is typically used when you need to retrieve comprehensive details about a specific intent, such as after a transaction has been initiated or processed. This allows developers to access the full details and intent state.
Parameters:
- intentId: The unique identifier of the intent.
- intentType: The type of the intent, either IntentType.Payment or IntentType.Payout.
Returns: An IntentDetails object containing the detailed information about the intent, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val details = moneyHashSDK.getIntentDetails(intentId = "intent_id", intentType = IntentType.Payment)
    println("Intent details: $details")
} catch (error: MHThrowable) {
    println("Error retrieving intent details: ${error.message}")
}

7. `resetSelectedMethod`

@Throws(MHThrowable::class)
suspend fun resetSelectedMethod(
    intentId: String,
    intentType: IntentType = IntentType.Payment
): MethodsResult

Purpose: Resets the currently selected payment or payout method for a specified intent, allowing the user to reselect or change the method.
Use Case: This method is useful when the user wants to change their payment method after a previous selection or if there’s a need to refresh the method selection. It clears the selected method and returns the updated list of available methods.
Parameters:
- intentId: The unique identifier of the intent.
- intentType: The type of the intent (e.g., IntentType.Payment, IntentType.Payout).
Returns: A MethodsResult object, containing the available methods after the reset.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val result = moneyHashSDK.resetSelectedMethod(intentId = "intent_id", intentType = IntentType.Payment)
    println("Method reset successfully: $result")
} catch (error: MHThrowable) {
    println("Error resetting method: ${error.message}")
}

8. `renderForm`

fun renderForm(
    intentId: String,
    intentType: IntentType,
    embedStyle: EmbedStyle? = null,
    launcher: ActivityResultLauncher<IntentCreationParams>
)

Purpose: Renders the MoneyHash form within the app's user interface, taking over the payment or payout process and handling it using MoneyHash embed.
Parameters:
- intentId: The unique identifier of the intent.
- intentType: The type of the intent (e.g., IntentType.Payment, IntentType.Payout).
- embedStyle: Optional styling for the embedded form (EmbedStyle).
- launcher: Launcher for creating and running the intent (ActivityResultLauncher<IntentCreationParams>).
Returns: This method does not return a value.

Example:

moneyHashSDK.renderForm(
    intentId = "intent_id",
    intentType = IntentType.Payment,
    embedStyle = null,
    launcher = activityResultLauncher
)

// Example of setting up the ActivityResultLauncher
private val activityResultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        val data = result.data
        // Handle the result from the MoneyHash form
    }
}

9. `proceedWithMethod`

@Throws(MHThrowable::class)
suspend fun proceedWithMethod(
    intentId: String,
    intentType: IntentType = IntentType.Payment,
    selectedMethodId: String,
    methodType: MethodType,
    methodMetaData: MethodMetaData? = null
): MethodsResult

Purpose: Proceeds with the selected payment or payout method for a given intent, continuing the transaction based on the selected method and any additional metadata provided.
Use Case: This method is critical in scenarios where the user has chosen a payment method and is ready to proceed with the transaction. Optional metadata such as CVV can be passed to this method to complete the transaction flow.
Parameters:
- intentId: The unique identifier of the intent.
- intentType: The type of the intent, such as IntentType.Payment or IntentType.Payout.
- selectedMethodId: The identifier of the selected payment or payout method.
- methodType: The type of method being used (e.g., MethodType.PaymentMethod, MethodType.PayoutMethod).
- methodMetaData: Optional metadata to be passed along with the selected method (e.g., CVV for cards).
Returns: A MethodsResult object containing the result of the method selection.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val result = moneyHashSDK.proceedWithMethod(
        intentId = "intent_id",
        intentType = IntentType.Payment,
        selectedMethodId = "method_id",
        methodType = MethodType.PaymentMethod,
        methodMetaData = null
    )
    println("Proceeded with method successfully: $result")
} catch (error: MHThrowable) {
    println("Error proceeding with method: ${error.message}")
}

10. `submitForm`

@Throws(MHThrowable::class)
suspend fun submitForm(
    intentId: String,
    selectedMethod: String,
    billingData: Map<String, String>? = null,
    shippingData: Map<String, String>? = null,
    vaultData: VaultData? = null,
    saveCard: Boolean? = null
): IntentDetails?

Purpose: Submits the form data related to a payment or payout intent, completing the transaction with the provided billing, shipping, and vault data.
Use Case: This method is used once the user has entered all necessary payment details, such as billing or shipping information. It finalizes the transaction and can save the user's card if desired. Vault data can also be used for tokenized cards.
Parameters:
- intentId: The unique identifier of the intent.
- selectedMethod: The identifier of the selected payment or payout method.
- billingData: Optional map containing billing information (Map<String, String>).
- shippingData: Optional map containing shipping information (Map<String, String>).
- vaultData: Optional tokenized card information from the vault (VaultData).
- saveCard: A boolean indicating whether the card should be saved for future use.
Returns: An IntentDetails object containing the submitted details and the result of the transaction, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val details = moneyHashSDK.submitForm(
        intentId = "intent_id",
        selectedMethod = "method_id",
        billingData = mapOf("name" to "John Doe"),
        shippingData = mapOf("address" to "1234 Street"),
        vaultData = null,
        saveCard = true
    )
    println("Form submitted successfully: $details")
} catch (error: MHThrowable) {
    println("Error submitting form: ${error.message}")
}

11. `submitCardCVV`

@Throws(MHThrowable::class)
suspend fun submitCardCVV(
    intentId: String,
    cvv: String
): IntentDetails?

Purpose: Submits the CVV for a saved card that is associated with a specified payment intent, enabling the completion of a card-based transaction.
Use Case: When a user selects a saved card for a payment and only the CVV is needed to complete the transaction, this method can be used to submit the CVV securely.
Parameters:
- intentId: The unique identifier of the intent.
- cvv: The CVV code of the saved card.
Returns: An IntentDetails object containing the result of the transaction, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val details = moneyHashSDK.submitCardCVV(intentId = "intent_id", cvv = "123")
    println("CVV submitted successfully: $details")
} catch (error: MHThrowable) {
    println("Error submitting CVV: ${error.message}")
}

12. `submitPaymentReceipt`

@Throws(MHThrowable::class)
suspend fun submitPaymentReceipt(
    intentId: String,
    data: String
): IntentDetails?

Purpose: Submits a payment receipt for a specified payment intent, providing confirmation or additional details related to the transaction.
Use Case: This method is useful when a third-party or manual payment confirmation needs to be submitted, such as when a payment receipt is generated outside the SDK. It allows you to associate the receipt with the transaction for record-keeping and confirmation.
Parameters:
- intentId: The unique identifier of the payment intent.
- data: The receipt data in a string format (could be in JSON or any other format as required).
Returns: An IntentDetails object containing the updated details of the intent, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    val details = moneyHashSDK.submitPaymentReceipt(intentId = "intent_id", data = "receipt_data")
    println("Receipt submitted successfully: $details")
} catch (error: MHThrowable) {
    println("Error submitting receipt: ${error.message}")
}

13. `updateFees`

@Throws(MHThrowable::class)
suspend fun updateFees(
    intentId: String,
    fees: List<FeeItem>
): FeesData?

Purpose: Updates the fees associated with a specified intent, allowing you to adjust or add fees dynamically during a transaction.
Use Case: This method is useful in scenarios where additional fees (such as service or delivery fees) need to be applied or adjusted after an intent is created. It ensures that the final transaction reflects all applicable fees before completion.
Parameters:
- intentId: The unique identifier of the intent.
- fees: A list of FeeItem objects representing the updated fees.
Returns: A FeesData object containing the updated fees, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

val feeItem1 = FeeItem(title = mapOf(SDKLocale.ENGLISH to "Service Fee"), value = "5.0", discount = null)
val feeItem2 = FeeItem(title = mapOf(SDKLocale.ENGLISH to "Delivery Fee"), value = "3.0", discount = null)

try {
    val updatedFees = moneyHashSDK.updateFees(intentId = "intent_id", fees = listOf(feeItem1, feeItem2))
    println("Fees updated successfully: $updatedFees")
} catch (error: MHThrowable) {
    println("Error updating fees: ${error.message}")
}

14. `updateDiscount`

@Throws(MHThrowable::class)
suspend fun updateDiscount(
    intentId: String,
    discount: DiscountItem
): DiscountData?

Purpose: Updates the discount associated with a specified payment intent, allowing the application of a discount to the total transaction amount.
Use Case: This method is used when a discount needs to be applied or modified for a transaction after the intent has been created. Discounts can be based on promotional codes, loyalty programs, or other incentives, and this method ensures the transaction reflects the correct discount before processing.
Parameters:
- intentId: The unique identifier of the payment intent for which the discount is being updated.
- discount: A DiscountItem object representing the discount details (e.g., type, value, and localized title).
Returns: A DiscountData object containing the updated discount information, or null if not available.
Throws: MHThrowable if an error occurs during the operation.

Example:

val discountTitle = mapOf(SDKLocale.ENGLISH to "Promo Code", SDKLocale.ARABIC to "رمز العرض")
val discountItem = DiscountItem(title = discountTitle, type = DiscountType.AMOUNT, value = "10.0")

try {
    val discountData = moneyHashSDK.updateDiscount(intentId = "intent_id", discount = discountItem)
    println("Discount updated successfully: $discountData")
} catch (error: MHThrowable) {
    println("Error updating discount: ${error.message}")
}

15. `deleteSavedCard`

@Throws(MHThrowable::class)
suspend fun deleteSavedCard(
    cardTokenId: String,
    intentSecret: String
)

Purpose: Deletes a saved card from the system using its token ID, ensuring that the card will no longer be available for future transactions.
Use Case: This method is ideal when a user wants to remove a saved card for security or personal reasons. The card is identified using its token ID, and the intent secret is required to ensure that the deletion is authorized and secure. Once deleted, the card can no longer be used for payments or stored in the vault.
Parameters:
- cardTokenId: The token ID of the card to be deleted.
- intentSecret: The secret associated with the card intent, used to authorize the deletion.
Returns: This method does not return a value.
Throws: MHThrowable if an error occurs during the operation.

Example:

try {
    moneyHashSDK.deleteSavedCard(cardTokenId = "card_token_123", intentSecret = "intent_secret_456")
    println("Card deleted successfully")
} catch (error: MHThrowable) {
    println("Error deleting card: ${error.message}")
}

Class: MoneyHashSDKBuilder

1. constructor

2. setPublicKey

3. setNativeGooglePayConfig

4. build

Example

Class: MoneyHashSDK

A. Methods That Do Not Require an Intent ID

1. setLogLevel

2. setLocale

3. setPublicKey

B. Methods That Require the Public Key to Be Set

4. getMethods (Using Currency and Amount)

C. Methods That Require Payment Intent ID

5. getMethods (Using Intent ID)

6. getIntentDetails

7. resetSelectedMethod

8. renderForm

9. proceedWithMethod

10. submitForm

11. submitCardCVV

12. submitPaymentReceipt

13. updateFees

14. updateDiscount

15. deleteSavedCard

Class: `MoneyHashSDKBuilder`

1. `constructor`

2. `setPublicKey`

3. `setNativeGooglePayConfig`

4. `build`

Class: `MoneyHashSDK`

1. `setLogLevel`

2. `setLocale`

3. `setPublicKey`

4. `getMethods` (Using Currency and Amount)

5. `getMethods` (Using Intent ID)

6. `getIntentDetails`

7. `resetSelectedMethod`

8. `renderForm`

9. `proceedWithMethod`

10. `submitForm`

11. `submitCardCVV`

12. `submitPaymentReceipt`

13. `updateFees`

14. `updateDiscount`

15. `deleteSavedCard`