MoneyHash SDK - CardForm Documentation

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 object 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 init()
    public func setCardNumberField(handler: ((CardInputFieldState) -> Void)?) -> CardFormBuilder
    public func setCVVField(handler: ((CardInputFieldState) -> Void)?) -> CardFormBuilder
    public func setCardHolderNameField(handler: ((CardInputFieldState) -> Void)?) -> CardFormBuilder
    public func setExpireMonthField(handler: ((CardInputFieldState) -> Void)?) -> CardFormBuilder
    public func setExpireYearField(handler: ((CardInputFieldState) -> Void)?) -> CardFormBuilder
    public func setCardBrandChangeHandler(_ handler: @escaping (CardBrand) -> Void) -> CardFormBuilder
    public func build() throws -> CardForm
}

Description

The CardFormBuilder class provides methods that allow you to subscribe to changes in the state of different card input fields (such as card number, CVV, expiration date, etc.). Each method takes a handler, which is a function that accepts the current CardInputFieldState of the field as a parameter. When the user updates any of the subscribed fields, the handler is called with the updated state, allowing you to respond accordingly.

You are free to subscribe to whichever fields you need. Additionally, you can subscribe to listen for changes in the CardBrand (e.g., Visa, MasterCard) using the setCardBrandChangeHandler.

This class provides flexibility in subscribing to only the fields you need, allowing you to build a customized experience for your form.

Example of Usage

let cardFormBuilder = CardFormBuilder()
    .setCardNumberField { state in
        print("Card Number Field Updated: \(state)")
    }
    .setCVVField { state in
        print("CVV Field Updated: \(state)")
    }
    .setCardBrandChangeHandler { brand in
        print("Card Brand Changed: \(brand)")
    }

do {
    let cardForm = try cardFormBuilder.build()
    // Use the cardForm for further operations
} catch {
    print("Error building CardForm: \(error)")
}

Class: CardForm

public class CardForm {
    // Checks if the card data entered is valid
    public var isValid: Bool

    // Collects the card data entered by the user
    public func collect() async throws -> VaultData?

    // Processes a payment using the provided card data and payment intent ID
    public func pay(
        intentId: String,
        cardData: VaultData,
        saveCard: Bool,
        billingData: [String: String]?,
        shippingData: [String: String]?
    ) async throws -> IntentDetails

    // Creates a token for the provided card data
    public func createCardToken(
        cardIntentId: String,
        cardData: VaultData
    ) async throws -> IntentStateDetails?
}

Description

The CardForm class is responsible for collecting and managing card information securely. 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.

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

1. isValid

public var isValid: Bool

• 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:

let isCardValid = cardForm.isValid
print("Is card data valid? \(isCardValid)")

2. collect

public func collect() async throws -> 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 nil if the operation fails.

• Throws: An MHError with type cardValidation 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:

do {
    // Ensure the public key is set
    moneyHashSDK.setPublicKey("your_public_api_key")

    // Initialize CardForm using CardFormBuilder
    let cardFormBuilder = CardFormBuilder()
    // Configure cardFormBuilder as needed
    let cardForm = try cardFormBuilder.build()

    let cardData = try await cardForm.collect()
    if let cardData = cardData {
        print("Card data collected: \(cardData)")
    } else {
        print("Failed to collect card data.")
    }
} catch {
    print("Error collecting card data: \(error)")
}

3. pay

public func pay(
    intentId: String,
    cardData: VaultData,
    saveCard: Bool,
    billingData: [String: String]?,
    shippingData: [String: String]?
) async throws -> 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 dictionary containing billing information.
  • shippingData: (Optional) A dictionary containing shipping information.

• Returns: IntentDetails if the payment is processed successfully.

• Throws: An MHError if the payment fails.

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

• Example:

do {
    // Assuming cardData is obtained from the collect method
    let intentDetails = try await cardForm.pay(
        intentId: "payment_intent_id",
        cardData: cardData,
        saveCard: true,
        billingData: ["address": "123 Main St", "city": "New York"],
        shippingData: ["address": "456 Elm St", "city": "Boston"]
    )
    print("Payment processed successfully: \(intentDetails)")
} catch {
    print("Error processing payment: \(error)")
}

4. createCardToken

public func createCardToken(
    cardIntentId: String,
    cardData: VaultData
) async throws -> 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 MHError if token creation fails.

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

• Example:

do {
    // Assuming cardData is obtained from the collect method
    let intentState = try await cardForm.createCardToken(
        cardIntentId: "card_intent_id",
        cardData: cardData
    )
    print("Card token created: \(String(describing: intentState))")
} catch {
    print("Error creating card token: \(error)")
}