Guides
Dashboard

MoneyHash SDK - CardForm Documentation

The CardForm class in the MoneyHash SDK for Android provides a secure and user-friendly way to collect and handle card data for payment processing. This document details the methods available in the CardForm class, organized based on their dependencies.

Suggest Edits

Dependencies Overview

  • No Dependencies: Some methods do not require any additional setup or dependencies.
  • Public Key: Some methods require the public API key to be set in the MoneyHashSDK before they can be used. The public key can be set directly using the MoneyHashSDK instance or during the building process using the MoneyHashSDKBuilder.
  • Payment Intent ID: Certain methods require a valid payment intent ID to process transactions.
  • Card Intent ID: The method createCardToken requires a valid card intent ID to create a token for the card data.

Class: CardFormBuilder

public class CardFormBuilder {
    public constructor()
    public fun setCardNumberField(listener: ((CardInputFieldState) -> Unit)? = null): CardFormBuilder
    public fun setCVVField(listener: ((CardInputFieldState) -> Unit)? = null): CardFormBuilder
    public fun setCardHolderNameField(listener: ((CardInputFieldState) -> Unit)? = null): CardFormBuilder
    public fun setExpireMonthField(listener: ((CardInputFieldState) -> Unit)? = null): CardFormBuilder
    public fun setExpireYearField(listener: ((CardInputFieldState) -> Unit)? = null): CardFormBuilder
    public fun setCardBrandChangeListener(listener: (CardBrand) -> Unit): CardFormBuilder
    public fun build(): CardForm
}

Description

The CardFormBuilder class in Android provides a fluent interface for configuring and building a CardForm instance. It allows you to subscribe to changes in the state of various card input fields (such as card number, CVV, expiration date, etc.) and listen for changes in the card brand (e.g., Visa, MasterCard). Each setter method accepts a listener that will be invoked with the updated state whenever the user modifies the corresponding field.

You can choose to subscribe to only the fields you need, enabling a tailored and efficient user experience within your application.

Example of Usage

val cardFormBuilder = CardFormBuilder()
    .setCardNumberField { state ->
        println("Card Number Field Updated: $state")
    }
    .setCVVField { state ->
        println("CVV Field Updated: $state")
    }
    .setCardHolderNameField { state ->
        println("Card Holder Name Field Updated: $state")
    }
    .setExpireMonthField { state ->
        println("Expire Month Field Updated: $state")
    }
    .setExpireYearField { state ->
        println("Expire Year Field Updated: $state")
    }
    .setCardBrandChangeListener { brand ->
        println("Card Brand Changed: $brand")
    }

try {
    val cardForm = cardFormBuilder.build()
    // Use the cardForm for further operations
} catch (error: MHThrowable) {
    println("Error building CardForm: ${error.message}")
}

Class: CardForm

public class CardForm {
    // Checks if the card data entered is valid
    public val isValid: Boolean

    // Collects the card data entered by the user
    public suspend fun collect(): VaultData?

    // Processes a payment using the provided card data and payment intent ID
    public suspend fun pay(
        intentId: String,
        cardData: VaultData,
        saveCard: Boolean,
        billingData: Map<String, String>?,
        shippingData: Map<String, String>?
    ): IntentDetails?

    // Creates a token for the provided card data
    public suspend fun createCardToken(
        cardIntentId: String,
        cardData: VaultData
    ): IntentStateDetails?
}

Description

The CardForm class is responsible for securely collecting and managing card information. It provides methods to:

  • Validate the card data entered by the user.
  • Collect card details and tokenize them for secure transactions.
  • Process Payments using the collected card data and a payment intent.
  • Create Card Tokens for future use with a card intent.

1. isValid

public val isValid: Boolean

  • Description: This property checks the validation state of all card input fields (e.g., card number, CVV, expiration date). It returns true if all required fields are valid, ensuring that the card data meets the necessary format and constraints.

  • Returns: A Boolean (true or false) indicating whether the card data is valid.

  • Example:

    val isCardValid: Boolean = cardForm.isValid
println("Is card data valid? $isCardValid")

2. collect

public suspend fun collect(): VaultData?

  • Description: This method is used to securely collect the card data provided by the user, such as card number, expiration date, and CVV. The collected data is submitted to MoneyHash Vault and returns a VaultData object, which can then be used for processing payments or creating card tokens. It ensures that the card information is handled securely and complies with all necessary validation rules.

  • Returns: VaultData? containing the collected card details or null if the operation fails.

  • Throws: An MHThrowable with type CARD_VALIDATION if the card data is invalid.

  • Requirements: These methods require the public API key to be set in the MoneyHashSDK using either the setPublicKey method or during the building process with MoneyHashSDKBuilder.

  • Example:

    suspend fun collectCardData() {
    try {
        // Collect card data
        val cardData = cardForm.collect()
        if (cardData != null) {
            println("Card data collected: $cardData")
        } else {
            println("Failed to collect card data.")
        }
    } catch (error: MHThrowable) {
        println("Error collecting card data: ${error.message}")
    }
}

3. pay

public suspend fun pay(
    intentId: String,
    cardData: VaultData,
    saveCard: Boolean,
    billingData: Map<String, String>?,
    shippingData: Map<String, String>?
): IntentDetails?

  • Description: This method allows you to process a payment using the card details collected from the user. It requires a valid payment intent ID, which links the card details to a specific transaction. You can also optionally provide billing and shipping information and indicate whether the card should be saved for future transactions. The method returns the payment details if the transaction is successful.

  • Parameters:

    • intentId: The unique identifier of the payment intent.
    • cardData: The card data collected using the collect method. See VaultData.
    • saveCard: A Boolean indicating whether to save the card for future transactions.
    • billingData: (Optional) A map containing billing information.
    • shippingData: (Optional) A map containing shipping information.

  • Returns: IntentDetails if the payment is processed successfully.

  • Throws: An MHThrowable if the payment fails.

  • Requirements: These methods require a valid payment intent ID to process transactions.

  • Example:

    suspend fun processPayment() {
    try {
        // Assuming cardData is obtained from the collect method
        val intentDetails = cardForm.pay(
            intentId = "payment_intent_id",
            cardData = cardData,
            saveCard = true,
            billingData = mapOf("address" to "123 Main St", "city" to "New York"),
            shippingData = mapOf("address" to "456 Elm St", "city" to "Boston")
        )
        println("Payment processed successfully: $intentDetails")
    } catch (error: MHThrowable) {
        println("Error processing payment: ${error.message}")
    }
}

4. createCardToken

public suspend fun createCardToken(
    cardIntentId: String,
    cardData: VaultData
): IntentStateDetails?

  • Description: This method is used to create a secure token for the card data provided by the user. The card token can be used for subsequent transactions, ensuring that sensitive card information is securely handled. The method returns the updated intent state after the card token has been successfully created. It requires a valid card intent ID.

  • Parameters:

    • cardIntentId: The unique identifier of the card intent.
    • cardData: The card data collected using the collect method. See VaultData.

  • Returns: IntentStateDetails? containing the state of the intent after the card token is created.

  • Throws: An MHThrowable if token creation fails.

  • Requirements: The following method requires a valid card intent ID to create a token for the card data.

  • Example:

    suspend fun generateCardToken() {
    try {
        // Assuming cardData is obtained from the collect method
        val intentState = cardForm.createCardToken(
            cardIntentId = "card_intent_id",
            cardData = cardData
        )
        println("Card token created: $intentState")
    } catch (error: MHThrowable) {
        println("Error creating card token: ${error.message}")
    }
}

Example of Usage

By utilizing CardForm, developers can ensure that sensitive card information is handled securely and in compliance with relevant standards.

// Initialize MoneyHashSDK and set the public key
val sdkBuilder = MoneyHashSDKBuilder()
    .setPublicKey("your_public_api_key")
val moneyHashSDK = sdkBuilder.build()

// Initialize CardFormBuilder and subscribe to field changes
val cardFormBuilder = CardFormBuilder()
    .setCardNumberField { state ->
        println("Card Number Field Updated: $state")
    }
    .setCVVField { state ->
        println("CVV Field Updated: $state")
    }
    .setCardHolderNameField { state ->
        println("Card Holder Name Field Updated: $state")
    }
    .setExpireMonthField { state ->
        println("Expire Month Field Updated: $state")
    }
    .setExpireYearField { state ->
        println("Expire Year Field Updated: $state")
    }
    .setCardBrandChangeListener { brand ->
        println("Card Brand Changed: $brand")
    }

try {
    val cardForm = cardFormBuilder.build()

    // Collect card data
    CoroutineScope(Dispatchers.Main).launch {
        try {
            val cardData = cardForm.collect()
            if (cardData != null) {
                println("Card data collected: $cardData")

                // Process payment
                val intentDetails = cardForm.pay(
                    intentId = "payment_intent_id",
                    cardData = cardData,
                    saveCard = true,
                    billingData = mapOf("address" to "123 Main St", "city" to "New York"),
                    shippingData = mapOf("address" to "456 Elm St", "city" to "Boston")
                )
                println("Payment processed successfully: $intentDetails")
            } else {
                println("Failed to collect card data.")
            }
        } catch (error: MHThrowable) {
            println("Error during card operations: ${error.message}")
        }
    }
} catch (error: MHThrowable) {
    println("Error building CardForm: ${error.message}")
}

Updated 2 months ago