iOS SDK

This page is a guide to installing and using MoneyHash's iOS SDK. You will find here the prerequisites to using our integration, the necessary requirements, how to configure the SDK in your app, and finally, how you can 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

Requires Xcode 14.3 or above

Installation

Add a package in Xcode’s menu bar by selecting File → Add Packages.

Search for the MoneyHash SDK using the repo's URL:

https://github.com/MoneyHash/moneyhash-ios

Next, set the Dependency Rule to be Up to Next Major Version and specify 1.0.4 as the lower bound.
Add Package.

Integrating

After configuring MoneyHash's iOS 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 iOS 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.

POST

/api/v1.1/payments/intent/

Create a MoneyHash instance using theMoneyHashSDKBuilder.build method.

import MoneyHash

let moneyHashSDK = MoneyHashSDKBuilder.build()

Get intent details: Calling the getIntentDetails method with the intent_id from the intent created at Step 1 and intentType (Payment/Payout) as parameters, you are able to access your intent details. The intentDetails.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 possible state value.

self.moneyHashSDK.getIntentDetails(
  intentId: "intentId",
  intentType: IntentType.payment) { result in
                                   do {
                                     let intentDetails = try result.get()
                                     print(try intentDetails.convertToDictionary())
                                   } catch {
                                     print("Error: \(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 also use it directly to render the embed form for payment/payout without handling the methods selection native UI.

self.moneyHashSDK.renderForm(
          on: self,
          intentId: "intentId",
          intentType: IntentType.payment
        ) { result in
           do {
             // Handle result here
           } catch MHError.cancelled {
             print("Cancelled")
           } catch {
             print(String(describing: result))
           }
          }

Get intent methods: Calling the getIntentMethods sending the intent_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 which paymentMethods to display to give the customer the option to choose their preferred method.

self.moneyHashSDK.getIntentMethods(
  intentId: "intentId",
  intentType: IntentType.payment) { result in
                                   do {
                                     let intentMethods = try result.get()
                                     print(try intentMethods
                                           .convertToDictionary())
                                   } catch {
                                     print("Error: \(error)")
                                   }
                                  }

Proceed with payment: Using the proceedWithMethod method, you are able to proceed with the payment process. You are required to inform the intentId, intentType, selectedMethodId, methodType and methodMetaData to execute this method.

self.moneyHashSDK.proceedWithMethod(
  intentId: "intentId",
  intentType: IntentType.payment,
  selectedMethodId: "methodId",
  methodType: IntentMethodType.expressMethod, // method type that returned from the intent methods
  metaData: nil // optional and can be null (cvv is required for customer saved cards that requires cvv)
) { result in
   // handle the intent methods native UI and updated intent details
  }

Other available iOS SDK methods

In addition to the essential steps and methods previously described, the iOS 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.

self.moneyHashSDK.resetSelectedMethod(
  intentId: "intentId",
  intentType: IntentType.payment
) { result in

  }

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.

self.moneyHashSDK.deleteSavedCard(
  cardTokenId: "cardTokenId", // card token id that returned in savedCards list in IntentMethods
  intentSecret: "intentSecret" // intent secret that returned in intent details
) { result in

  }

Models

To help you proceed and organize your code, we provide all possible model types for the methods you can use on the iOS SDK.


public enum MHError: Error {
    case cancelled
    case unknownError(underlyingError: String)
}

public struct MethodsResult: Encodable {
    let intentData: IntentDetails?
    let methods: IntentMethods?
}

public struct IntentMethods: Encodable {
    public let customerBalances: [CustomerBalance]?
    public let paymentMethods: [PaymentMethod]?
    public let expressMethods: [ExpressMethod]?
    public let savedCards: [SavedCard]?
    public let payoutMethods: [PayoutMethod]?
}

public struct IntentDetails: Encodable {
    public let selectedMethod: String?
    public let wallet: Double?
    public let intent: Intent?
    public let state: State?
    public let transaction: Transaction?
    public let redirect: RedirectData?
}

public struct Intent: Encodable {
    public let id: String?
    public let amount: AmountData?
    public let secret: String?
    public let isLive: Bool?
    public let status: IntentStatus?
    public let expirationDate: String?
}

public struct AmountData: Encodable {
    let value: String?
    let formatted: Double?
    let currency: String?
    let maxPayoutAmount: Double?
}

public enum IntentStatus: String, Encodable {
    case processed
    case unprocessed
    case timeExpired
    case closed
}

public enum IntentType: String, Encodable {
    case payment
    case payout
}

public struct RedirectData: Encodable {
    public let redirectUrl: String?
}

public enum State: String, Encodable {
    case methodSelection
    case intentForm
    case intentProcessed
    case transactionWaitingUserAction
    case transactionFailed
    case expired
    case closed
}

public struct Transaction: Encodable {
    public let id: String?
    public let createdDate: String?
    public let status: String?
    public let amount: Double?
    public let amountCurrency: String?
    public let method: String?
    public let methodName: String?
    public let billingData: String?
    public let customFields: String?
    public let customFormAnswers: String?
    public let externalActionMessage: [String]?
    public let providerTransactionFields: String?
}

public struct SavedCard: Encodable {
    public let id: String?
    public let brand: String?
    public let last4: String?
    public let expiryMonth: String?
    public let expiryYear: String?
    public let country: String?
    public let logo: String?
    public let requireCvv: Bool?
    public let cvvConfig: CvvConfig?
    public let type: IntentMethodType?
}

public struct PayoutMethod: Encodable {
    public let id: String?
    public let title: String?
    public let isSelected: Bool?
    public let checkoutIcons: [String]?
    public let type: IntentMethodType?
}

public struct PaymentMethod: Encodable {
    public let id: String?
    public let title: String?
    public let isSelected: Bool?
    public let checkoutIcons: [String]?
    public let type: IntentMethodType?
}

public enum IntentMethodType: String, Encodable {
    case paymentMethod
    case expressMethod
    case payoutMethod
    case savedCard
    case customerBalance
}

public struct IntentMethodMetaData {
    public let cvv: String?
}

public struct ExpressMethod: Encodable {
    public let id: String?
    public let title: String?
    public let isSelected: Bool?
    public let checkoutIcons: [String]?
    public let type: IntentMethodType?
}

public struct CustomerBalance: Encodable {
    public let id: String?
    public let balance: Double?
    public let isSelected: Bool?
    public let icon: String?
    public let type: IntentMethodType?
}

Notifications

After integrating with MoneyHash through the iOS 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.