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 specify1.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.
- Create a MoneyHash instance using the
MoneyHashSDKBuilder.build
method.
import MoneyHash
let moneyHashSDK = MoneyHashSDKBuilder.build()
- Get intent details: Calling the
getIntentDetails
method with theintent_id
from theintent
created at Step 1 andintentType
(Payment/Payout) as parameters, you are able to access your intent details. TheintentDetails.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 possiblestate
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 theintent_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 whichpaymentMethods
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 theintentId
,intentType
,selectedMethodId
,methodType
andmethodMetaData
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.
Updated 10 months ago