Remittances SDK for iOS

The Remittances SDK is a solution to ease the integration with the Alviere services.

Features
Requirements
Installation
- SPM
- CocoaPods
- Carthage
- Manual
Usage
Alternative Usage

Features

Beneficiary Management
Global Payments

Requirements

iOS 13.0+
Xcode 15+
Swift 5.5+

Installation

Swift Package Manager

1. Add the dependency to your project. Open your project and navigate to your project’s settings. Select the tab named Swift Packages and click on the add button + at the bottom left.

2. Enter the url of Remittances SDK for the iOS repository (https://github.com/Alviere/alviere-remittances-ios) in the text field and click Next.

3. On the next screen, select the SDK version and click Next.

4. Select the RemittancesSDK package and click Finish.

5. Repeat the same process for AlCore SDK (https://github.com/Alviere/alviere-core-ios). The current version is compatible with AlCore SDK version 0.9.0 and up.

CocoaPods

1. Get the latest version of CocoaPods, if you haven’t already.

2. Create the Podfile by running the following command, if you don’t have one already.

pod init

3. Add this line to your Podfile.

pod 'RemittancesSDK'

4. Run the following command to install the library. Also, run this to update to newer releases in the future.

pod install

Carthage

1. Get the latest version of Carthage, if you haven’t already.

2. Add the following entries in your Cartfile:

binary https://raw.githubusercontent.com/Alviere/alviere-core-ios/master/AlCore.json
binary https://raw.githubusercontent.com/Alviere/alviere-remittances-ios/master/RemittancesSDK.json

3. Run the following command to download the latest version of the SDK.

carthage update --use-xcframeworks

4. Follow the Manual instructions below to embed the SDK into your project.

Manual

1. Get the latest versions of RemittancesSDK.xcframework and AlCore.xcframework and embed them into your application by dragging and dropping the files onto the Frameworks, Libraries and Embedded Content project section, as shown below.

2. Depending on the location of RemittancesSDK.xcframework and AlCore.xcframework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: ‘RemittancesSDK/RemittancesSDK.h’ file not found. For example, the Xcode project below have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the xcframeworks files are shared between them and are kept in the directory that also contains the project directories.

Usage

To initialize the Remittances SDK for iOS, you need to set the Environment at the entry point of your application. For example, you can do this on your AppDelegate file on the application(_:,didFinishLaunchingWithOptions:) method, as shown below.

import AlCore

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Setup Alviere SDK.
    if !AlCoreSDK.shared.setEnvironment(.sandbox) {
        print("Error initializing SDK.")
    }
    return true
}

After this setup, you just need to import the Remittances SDK for iOS on the files where you want to use the features.

import RemittancesSDK

Beneficiary Management

Adopt the BeneficiaryDelegate Protocol

This can be handled, for instance, by the view controller object that will call the beneficiary actions.

extension ViewController : BeneficiaryDelegate

The BeneficiaryDelegate methods are the main communication backchannel to your application for the beneficiary management on Remittances SDK for iOS. For each action there is one method associated as follows:

Create a Beneficiary: didCreateBeneficiary(_:)
List Beneficiaries: didListBeneficiaries(_:)
Get a Beneficiary: didGetBeneficiary(_:)
Update a Beneficiary: didUpdateBeneficiary(_:)
Delete a Beneficiary: didDeleteBeneficiary()

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Remittances SDK flow. In case of an error, you may want to display error-related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Create a Beneficiary

To create a beneficiary for a user, use createBeneficiary where you will need to create a new auth_token, pass the accountUuid and the CreateBeneficiaryRequest model with the data, and pass the BeneficiaryDelegate delegate instance.

let model = CreateBeneficiaryRequest( ... )

AlRemittances.shared
    .createBeneficiary(token: authToken,
                       accountUuid: accountUuid,
                       beneficiaryData: model,
                       delegate: self)

The result of this action will return the newly created Beneficiary model on the didCreateBeneficiary(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateBeneficiary(_ beneficiary: Beneficiary) {
    print("New beneficiary is:\n\(beneficiary)")
}

List Beneficiaries

To list beneficiaries you will need to create a new auth_token, pass the accountUuid of the user and the BeneficiaryDelegate delegate instance.

AlRemittances.shared
    .listBeneficiaries(token: authToken,
                       accountUuid: accountUuid,
                       delegate: self)

The result of this action will return all beneficiaries Beneficiary list on the didListBeneficiaries(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListBeneficiaries(_ beneficiaries: [Beneficiary]) {
    print("Beneficiaries are:\n\(beneficiaries)")
}

Get Beneficiary

To get a beneficiary you will need to create a new auth_token, pass the accountUuid of the user, and pass the beneficiaryUuid and the BeneficiaryDelegate delegate instance.

AlRemittances.shared
    .getBeneficiary(token: authToken,
                    accountUuid: accountUuid,
                    beneficiaryUuid: beneficiaryUuid,
                    delegate: self)

The result of this action will return a beneficiary Beneficiary on the didGetBeneficiary(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetBeneficiary(_ beneficiary: Beneficiary) {
    print("Beneficiary is:\n\(beneficiary)")
}

Update a Beneficiary

To update a beneficiary for a user, use updateBeneficiary where you will need to create a new auth_token, pass the accountUuid of the user and the beneficiaryUuid, pass the UpdateBeneficiaryRequest model with the updated data, and pass the BeneficiaryDelegate delegate instance.

let beneficiaryData = UpdateBeneficiaryRequest( ... )

AlRemittances.shared
    .updateBeneficiary(token: authToken,
                       accountUuid: accountUuid,
                       beneficiaryUuid: beneficiaryUuid,
                       beneficiaryData: beneficiaryData,
                       delegate: self)

The result of this action will return the updated Beneficiary model on the didUpdateBeneficiary(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didUpdateBeneficiary(_ beneficiary: Beneficiary) {
    print("Updated beneficiary is:\n\(beneficiary)")
}

Delete a Beneficiary

To delete a beneficiary for a user, use deleteBeneficiary where you will need to create a new auth_token, pass the accountUuid of the user and the beneficiaryUuid, and pass the BeneficiaryDelegate delegate instance.

AlRemittances.shared
    .deleteBeneficiary(token: authToken,
                       accountUuid: accountUuid,
                       beneficiaryUuid: beneficiaryUuid,
                       delegate: self)

The result of this action will return a confirmation on the didDeleteBeneficiary() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didDeleteBeneficiary() {
    print("Beneficiary was deleted!")
}

Global Payments

Adopt the GlobalPaymentsDelegate Protocol

This can be handled, for instance, by the view controller object that will call the global payments actions.

extension ViewController : GlobalPaymentsDelegate

The GlobalPaymentsDelegate methods are the main communication backchannel to your application for global payments on Remittances SDK for iOS. For each action there is one method associated as follows:

Create a Quote: didCreateQuote(_:)
Create a Remittance: didCreateRemittance(_:)

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Create a Quote

To create a quote for a remittance, use createQuote where you will need to create a new auth_token, pass the walletUuid and the CreateQuoteRequest model with the data, and pass the GlobalPaymentsDelegate delegate instance.

let model = CreateQuoteRequest( ... )

AlRemittances.shared
    .createQuote(token: authToken,
                 walletUuid: walletUuid,
                 data: model,
                 delegate: self)

The result of this action will return the newly created Quote model on the didCreateQuote(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateQuote(_ quote: Quote) {
    print("New quote is:\n\(quote)")
}

Create a Remittance

To create a remittance for a international beneficiary, use createRemittance where you will need to create a new auth_token, pass the walletUuid and the CreateRemittanceRequest model with the data, and pass the GlobalPaymentsDelegate delegate instance.

let model = CreateRemittanceRequest( ... )

AlRemittances.shared
    .createRemittance(token: authToken,
                      walletUuid: walletUuid,
                      data: model,
                      delegate: self)

The result of this action will return the newly created Remittance transaction model on the didCreateRemittance(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateRemittance(_ remittance: Remittance) {
    print("Remittance has been issued!\n\(remittance)")
}

Cash Pickup

Adopt the CashPickupDelegate Protocol

This can be handled, for instance, by the view controller object that will call the global payments actions.

extension ViewController : CashPickupDelegate

The CashPickupDelegate methods are the main communication backchannel to your application for cash pickup methods on Remittances SDK for iOS. For each action there is one method associated as follows:

List cash pickup cities: didListCashPickupCities(_:)

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

List Cash Pickup Cities

To list cash pickup cities you will need to create a new auth_token, provide a query throught CashPickupCitiesQuery with at least the country of the cities to retrieve and the CashPickupDelegate delegate instance.

let query = CashPickupCitiesQuery(country: "MEX")

AlRemittances.shared
    .listCashPickupCities(token: authToken,
                          query: query,
                          delegate: self)

The result of this action will return all cities CashPickupCity list on the didListCashPickupCities(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListCashPickupCities(_ cities: [CashPickupCity]) {
    print("Cash pickup cities are:\n\(cities)")
}

List Cash Pickup Locations

To list cash pickup locations you will need to create a new auth_token, provide a query throught CashPickupLocationsQuery with at least the city_uuid defined, and the CashPickupDelegate delegate instance.

let query = CashPickupLocationsQuery(cityUuid: cityUuid)

AlRemittances.shared
    .listCashPickupLocations(token: authToken,
                             query: query,
                             delegate: self)

The result of this action will return all locations CashPickupLocation list on the didListCashPickupLocations(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListCashPickupLocations(_ locations: [CashPickupLocation]) {
    print("Cash pickup locations are:\n\(locations)")
}

Get Cash Pickup Location

To get a cash pickup location details you will need to create a new auth_token, provide a location_uuid and the CashPickupDelegate delegate instance.

AlRemittances.shared
    .getCashPickupLocation(token: authToken,
                           locationUuid: locationUuid,
                           delegate: self)

The result of this action will return a CashPickupLocation model on the didGetCashPickupLocation(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCashPickupLocation(_ location: CashPickupLocation) {
    print("Cash pickup location is:\n\(location)")
}

Payout Methods

Adopt the PayoutMethodsDelegate Protocol

This can be handled, for instance, by the view controller object that will call the payout methods actions.

extension ViewController : PayoutMethodsDelegate

The PayoutMethodsDelegate methods are the main communication backchannel to your application for the beneficiary management on Remittances SDK for iOS. For each action there is one method associated as follows:

Create a Payout Method: didCreatePayoutMethod(_:)
List Payout Methods: didListPayoutMethods(_:)
Get a Payout Method: didGetPayoutMethod(_:)
Update a Payout Method: didUpdatePayoutMethod(_:)
Delete a Payout Method: didDeletePayoutMethod()

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Create a Payout Method

To create a payout method for a beneficiary, use createPayoutMethod where you will need to create a new auth_token, pass the beneficiaryUuid and the CreatePayoutMethodRequest model with the data, and pass the PayoutMethodsDelegate delegate instance.

let model = CreatePayoutMethodRequest( ... )

AlRemittances.shared
    .createPayoutMethod(token: authToken,
                        beneficiaryUuid: beneficiaryUuid,
                        data: model,
                        delegate: self)

The result of this action will return the newly created PayoutMethod model on the didCreatePayoutMethod(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreatePayoutMethod(_ payoutMethod: PayoutMethod) {
    print("New payout method is:\n\(payoutMethod)")
}

List Payout Methods

To list payout methods you will need to create a new auth_token, pass the beneficiaryUuid of the user and the PayoutMethodsDelegate delegate instance.

AlRemittances.shared
    .listPayoutMethods(token: authToken,
                       beneficiaryUuid: beneficiaryUuid,
                       delegate: self)

The result of this action will return all beneficiaries PayoutMethod list on the didListPayoutMethods(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListPayoutMethods(_ payoutMethods: [PayoutMethod]) {
    print("Payout methods are:\n\(payoutMethods)")
}

Get Payout Method

To get a beneficiary you will need to create a new auth_token, pass the payoutMethodUuid and the PayoutMethodsDelegate delegate instance.

AlRemittances.shared
    .getPayoutMethod(token: authToken,
                     payoutMethodUuid: accountUuid,
                     delegate: self)

The result of this action will return a beneficiary PayoutMethod on the didGetPayoutMethod(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetPayoutMethod(_ payoutMethod: PayoutMethod) {
    print("Payout method is:\n\(payoutMethod)")
}

Update a Payout Method

To update a payout method for a user, use updatePayoutMethod where you will need to create a new auth_token, pass the payoutMethodUuid, pass the UpdatePayoutMethodRequest model with the updated data, and pass the PayoutMethodsDelegate delegate instance.

let data = UpdatePayoutMethodRequest( ... )

AlRemittances.shared
    .updatePayoutMethod(token: authToken,
                        payoutMethodUuid: payoutMethodUuid,
                        data: data,
                        delegate: self)

The result of this action will return the updated PayoutMethod model on the didUpdatePayoutMethod(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didUpdateBeneficiary(_ payoutMethod: PayoutMethod) {
    print("Updated payout method is:\n\(payoutMethod)")
}

Delete a Payout Method

To delete a payout method for a user, use deletePayoutMethod where you will need to create a new auth_token, pass the payoutMethodUuid and pass the PayoutMethodsDelegate delegate instance.

AlRemittances.shared
    .deletePayoutMethod(token: authToken,
                        payoutMethodUuid: payoutMethodUuid,
                        delegate: self)

The result of this action will return a confirmation on the didDeletePayoutMethod() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didDeletePayoutMethod() {
    print("Payout method was deleted!")
}

Alternative Usage

The SDK can also be integrated using Closures, Combine or Async/Await methods. They can be accessed respectively by:

Closures - A closure can be passed instead of the delegate.
Combine - AlRemittances.shared.combine can be used to access methods that return Combine Future objects.
Async/Await - AlRemittances.shared.async can be used to access async methods.