Migration Guide: Upgrading from MoneyHash SDK for Flutter Version 2.0 to 2.1

Note: All API and model names are linked to their respective sections in the API documentation and Models documentation, which are located in the same directory as this guide.

Introduction

In MoneyHash SDK version 2.1, several changes have been made to improve the developer experience and streamline payment processing. This migration guide will help you understand these changes and update your code accordingly.

Overview of Key Changes

1. Deprecation of getIntentMethods: Replaced with the new getMethods method.
2. Renaming of CardCollector to CardForm: Simplifies the card form creation process.
3. **Renaming of cardFormCollector to [cardForm] Parameter while initializing the SecureTextField.
4. Deprecation of CardCollector.setTokenizeCardInfo: No longer needed in the new version.
5. Introduction of pay and createCardToken methods in CardForm: Provides direct methods for payment processing and card token creation.
6. Deprecation of CardCollector.collect("intentId", shouldSaveCard): Replaced with cardForm.collect() without parameters.
7. Addition of setPublicKey method in MoneyHashSDK: Requires setting the public API key before performing certain operations.
8. New Intent States: Two new states, CardIntentSuccessful and CardIntentFailed, specifically for handling card token creation outcomes.

Deprecated Methods and Their Replacements

1. getIntentMethods Deprecated

• Deprecated Method:

  Dart

  Future<IntentMethods> getIntentMethods(String intentId, IntentType intentType)
  

• Replacement Method: getMethods

  Dart

  Future<IntentMethods> getMethods(GetMethodsParams methodsParams)
  

Changes:

• The new getMethods method requires a GetMethodsParams object instead of separate parameters.

• Public API Key Requirement: You must set the public API key using setPublicKey before calling getMethods.

• Constructor Usage: You must use one of the provided constructors for GetMethodsParams:

  • GetMethodsParams.withIntent(intentId, intentType)
  • GetMethodsParams.withCurrency(currency: ..., customer: ..., flowId: ..., amount: ...)

2. CardCollector.collect Deprecated

• Deprecated Method:

  Dart

  Future<VaultData?> collect(String intentId, bool shouldSaveCard)
  

• Replacement Method: collect

  Dart

  Future<VaultData?> collect()
  

Changes:

• The collect method no longer accepts parameters.
• The method now relies on the public API key set via setPublicKey.

3. CardCollector.setTokenizeCardInfo Deprecated

• Deprecated Method:

  Dart

  CardCollector.setTokenizeCardInfo(tokenizeCardInfo);
  

• Reason: The tokenizeCardInfo is now handled internally, and you no longer need to set it manually.

New Additions and Updates

1. New Methods in CardForm

• pay Method: Processes a payment using the collected card data.

  See pay.

  Dart

  Future<IntentDetails?> pay(
    String intentId,
    VaultData cardData,
    bool saveCard,
    Map<String, String>? billingData,
    Map<String, String>? shippingData,
  )
  

• createCardToken Method: Creates a token for the collected card data.

  See createCardToken.

  Dart

  Future<IntentStateDetails?> createCardToken(
    String cardIntentId,
    VaultData cardData,
  )
  

2. Renaming of CardCollector to CardForm

• Old Class Name: CardCollector
• New Class Name: CardForm

Changes:

• The class used to build and manage the card form is now simply CardForm.
• Methods previously called on CardCollector are now called on CardForm.

3. Adding Public API Key with setPublicKey

• Method: setPublicKey

  Dart

  void setPublicKey(String publicKey)
  

Purpose:

• You must set the public API key before performing operations like collecting card data or retrieving payment methods.

4. New Intent States for Card Token Creation

• CardIntentSuccessful: Indicates that the card token was created successfully.
• CardIntentFailed: Indicates that the card token creation failed.

Usage:

• Handle these new states when you attempt to create a card token using createCardToken.

Step-by-Step Migration Instructions

1. Updating getIntentMethods to getMethods

Before:

var intentMethods = await moneyHashSDK.getIntentMethods("intentId", IntentType.payment);

After:

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

// Using the withIntent constructor if you have an intent ID
var methodsParams = GetMethodsParams.withIntent(
  "intentId",
  IntentType.payment,
);

// Or using the withCurrency constructor if you want to get methods based on currency
var methodsParams = GetMethodsParams.withCurrency(
  currency: "USD",
  customer: "customer_id", // Optional
  flowId: "flow_id",       // Optional
  amount: 100.0,           // Optional
);

var intentMethods = await moneyHashSDK.getMethods(methodsParams);

Action Required:

• Replace getIntentMethods with getMethods.
• Create a GetMethodsParams object using one of the provided constructors:
  • Use GetMethodsParams.withIntent(intentId, intentType) if you have an intent ID.
  • Use GetMethodsParams.withCurrency(...) if you want to retrieve methods based on currency.
• Do not set parameters directly; use the constructors to ensure required fields are provided.
• Set the public API key before calling getMethods.

2. Refactoring CardCollector to CardForm

Before:

CardCollector cardCollector = cardFormBuilder.build();
VaultData? cardData = await cardCollector.collect("intentId", true);

After:

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

CardForm cardForm = cardFormBuilder.build();
// Configure cardForm as needed
VaultData? cardData = await cardForm.collect();

Action Required:

• Replace CardCollector with CardForm.
• Use the collect method without parameters.
• Ensure the public API key is set before collecting card data.

3. Adjusting CardCollector Usage

Deprecated Method:

cardCollector.setTokenizeCardInfo(tokenizeCardInfo);

Action Required:

• Remove any calls to setTokenizeCardInfo.
• The CardForm now handles tokenization information internally.

4. Implementing the setPublicKey Method

Before:

• Public API key was not required for certain operations.

After:

• Set the public API key before performing operations that require it:

  Dart

  moneyHashSDK.setPublicKey("your_public_api_key");
  

• Operations that require the public API key:

  • Collecting card data using cardForm.collect().
  • Retrieving payment methods using getMethods.

Action Required:

• Call setPublicKey with your public API key before performing relevant operations.

5. Handling New Intent States

When Creating a Card Token:

• Possible States:
  • CardIntentSuccessful
  • CardIntentFailed

Example:

IntentStateDetails? intentState = await cardForm.createCardToken("cardIntentId", cardData!);

if (intentState is CardIntentSuccessful) {
  // Handle success
  print("Card token created successfully.");
} else if (intentState is CardIntentFailed) {
  // Handle failure
  print("Card token creation failed: ${intentState.errorMessage}");
}

Action Required:

• Implement handling for these new states in your code when creating card tokens.

Code Examples Before and After Migration

1. getIntentMethods vs. getMethods

Before (Version 2.0):

var intentMethods = await moneyHashSDK.getIntentMethods("intentId", IntentType.payment);

After (Version 2.1):

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

// Using the withIntent constructor
var methodsParams = GetMethodsParams.withIntent(
  "intentId",
  IntentType.payment,
);

var intentMethods = await moneyHashSDK.getMethods(methodsParams);

Or, if you don't have an intent ID and want to retrieve methods based on currency:

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

// Using the withCurrency constructor
var methodsParams = GetMethodsParams.withCurrency(
  currency: "USD",
  customer: "customer_id", // Optional
  flowId: "flow_id",       // Optional
  amount: 100.0,           // Optional
);

var intentMethods = await moneyHashSDK.getMethods(methodsParams);

Important: You must use one of the provided constructors (withIntent or withCurrency) and cannot set the parameters directly.

2. CardCollector.collect vs. CardForm.collect

Before:

CardCollector cardCollector = cardFormBuilder.build();
VaultData? cardData = await cardCollector.collect("intentId", true);

After:

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

CardForm cardForm = cardFormBuilder.build();
VaultData? cardData = await cardForm.collect();

3. CardCollector Adjustments

Before:

CardCollector cardCollector = CardCollector();
cardCollector.setTokenizeCardInfo(tokenizeCardInfo);
// ... other configurations

After:

CardForm cardForm = CardForm();
// ... configure cardForm as needed

Action Required:

• Replace CardCollector with CardForm.
• Remove any calls to setTokenizeCardInfo.

Additional Resources

• MoneyHash SDK API Documentation
• MoneyHash SDK - CardForm Documentation
• MoneyHash SDK Models Documentation
• GitHub Issue.