Payments SDK for iOS

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

Features

  • Cards Tokenization
  • Payment Checkout

Requirements

  • iOS 10.0+
  • Xcode 12+
  • Swift 5.3+

Integration

Manual

1. Get the latest versions of Payments.xcframework and AlCore.xcframework and embed it into your application by dragging and dropping the file onto the file structure of your project, as shown below.

image

2. When dropping the .xcframeworks, Xcode will provide a confirmation and configuration dialog. In that dialog make sure the Copy items if needed option and your main target are selected.

image

3. Navigate to the project file. On the General tab, under Frameworks, Libraries and Embedded Content, check if both are there and if the Embed option has the value Embed & Sign.

image

Implementation

To use the Payments SDK for iOS, import Payments into your code.

import Payments

Payments SDK Add Card for Tokenization

Adopt the AddCardDelegate protocol

This can be handled, for instance, by the view controller object that will present the UI.

extension ViewController : AddCardDelegate

Implement the Delegate Methods

The AddCardDelegate methods are the main communication back channel to your application for the Payments SDK for iOS.

didSucceed

This delegate method is called when the user successfully linked their card with Alviere. Use this to upload and store the cardToken with your service for use with the Alviere API.

func didSucceed(withCardToken cardToken: String) {
    // Handle success, e.g. by storing cardToken with your service
    print("Successfully tokenized card with token \(cardToken)")
}

didHandleEvent

This delegate method is called when the user exited from the Payments SDK, when an error occurred, or when certain events in the Payments SDK flow have occurred. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error you may want to display error related information to the user and have them try linking their card 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.

Presentation

Starting the Payments SDK for iOS is as simple as creating a new auth_token, using it to initialize PaymentsSDK, and get/register the AddCardViewController / AddCardView instances. You can also use the card tokenization with your own UI.

Presenting View Controller

From code

To instantiate AddCardViewController from code, use createAddCardViewController to create a new auth_token, set the Environment, and pass the AddCardDelegate delegate instance. Optionally, you can also pass a customization object with the style overrides you want to apply. You can either present the newly created view controller by pushing it, with show, or modally, with present.

let viewController = PaymentsSDK.shared
    .createAddCardViewController(environment: .sandbox,
                                 token: authToken,
                                 delegate: self,
                                 style: style)

self.navigationController?.show(viewController, sender: self)

When presenting modally, you still need to embed the view controller on a navigation controller and then present the navigation controller itself. If the AddCardViewController has no navigation controller it will throw an error and crash your application.

let viewController = PaymentsSDK.shared
    .createAddCardViewController(environment: .sandbox,
                                 token: authToken,
                                 delegate: self,
                                 style: style)

let navigationController = UINavigationController(rootViewController: viewController)

self.present(navigationController, animated: true)

From Storyboard

To create an AddCardViewController from a Storyboard or a xib you need to select your view controller. On the Custom Class section, set the Class as AddCardViewController and enable the Inherit Module From Target checkbox. At this point, you only need to register your view controller with PaymentsSDK, using the registerAddCardViewController, create a new auth_token, set the Environment, and pass the AddCardDelegate delegate instance. Optionally, you can also pass a customization object with the style overrides you want to apply. Be sure that when presenting modally the AddCardViewController needs to be embedded on a navigation controller or it will throw an error and crash your application.

image

If you present the view controller with a Segue you need to implement a prepare(for:, sender:) callback and then register the view controller.

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    PaymentsSDK.shared
        .registerAddCardViewController(environment: .sandbox,
                                    token: authToken,
                                    viewController: segue.destination,
                                    delegate: self,
                                    style: style)
}

If you choose to instantiate the view controller by Storyboard ID and navigate manually, you just need to register the view controller.

let viewController = UIStoryboard(name: "Main", bundle: nil)
    .instantiateViewController(identifier: "AddCardViewController") as! AddCardViewController

PaymentsSDK.shared
    .registerAddCardViewController(environment: .sandbox,
                                   token: authToken,
                                   viewController: viewController,
                                   delegate: self)

self.navigationController?.show(viewController, sender: self)

Presenting View Component

When using the Payments SDK for iOS as a component, be advised that you will also have the task of handling the errors and navigation.

From Code

To instantiate AddCardView from code, use createAddCardView where you will need to create a new auth_token, set the Environment, and pass the AddCardDelegate delegate instance. You also have the option to pass a customization object with the style overrides you want to apply.

let view = PaymentsSDK.shared
    .createAddCardView(environment: .development,
                       token: self.authToken,
                       delegate: self,
                       style: style)

From Storyboard

To create an AddCardView from a Storyboard or a xib you need to select your view, and on the Custom Class section, set the Class as AddCardView and enable the Inherit Module From Target checkbox.

image

Create an IBOutlet and register your view with PaymentsSDK on the viewDidLoad method, using the registerAddCardView and, create a new auth_token, set the Environment, and pass the AddCardDelegate delegate instance. If you wish, you may also pass a customization object with the style overrides you want to apply. Be advised that by this method you will miss the open event on the delegate.

@IBOutlet weak var addCardView: AddCardView!

...

override func viewDidLoad() {
    super.viewDidLoad()

    PaymentsSDK.shared
        .registerAddCardView(environment: .sandbox,
                             token: authToken,
                             view: addCardView,
                             delegate: self,
                             style: style)
}

Usage without UI

If you want to call the tokenization service directly, use createCardToken to create a new auth_token, set the Environment, pass the CardTokenRequest model with the card data, and pass the AddCardDelegate delegate instance. You also have the option to pass a customization object with a custom validation for the zip/postal code field.

let model = CardTokenRequest( ... )

PaymentsSDK.shared
    .createCardToken(environment: .sandbox,
                     token: authToken,
                     data: model,
                     delegate: self)

Payments SDK Payment Checkout

Adopt the CheckoutDelegate protocol

This can be handled by the view controller object that will present the UI component.

extension ViewController : CheckoutDelegate

Implement the Delegate Methods

The CheckoutDelegate methods are the main communication back channels to your application for the Payments SDK for iOS.

cardDebitAccepted

This delegate method is called when the payment checkout is successful.

func cardDebitAccepted() {
    // Handle success
    print("Payment checkout successful")
}

didHandleEvent

This delegate method is called when certain events in the Payments SDK flow have occurred. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display error related information to the user.

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.

Payment Checkout Presentation

Starting the Payments SDK for iOS is as simple as creating a new auth_token, using it to initialize PaymentsSDK, get/register a CheckoutButton instance, and provide a CardDebitRequest model. You can also use the payment checkout with your own UI.

Presenting Button

From Code

To instantiate CheckoutButton from code, use createCardDebitButton where you will need to create a new auth_token, set the Environment, and pass the CheckoutDelegate delegate instance. You also have the option to pass a customization object with the style overrides you want to apply.

let view = PaymentsSDK.shared
    .createCardDebitButton(environment: .development,
                           token: self.authToken,
                           delegate: self,
                           style: style)

After this, set the CardDebitRequest model with the data to proceed with the checkout. You can do this on your viewDidLoad method, for instance.

@IBOutlet weak var checkoutButton: CheckoutButton!

...

override func viewDidLoad() {
    super.viewDidLoad()

    let model = CardDebitRequest( ... )

    self.checkoutButton.setRequestData(model)
}

From Storyboard

To create a CheckoutButton from a Storyboard or a xib, you need to select your view, and on the Custom Class section, set the Class as CheckoutButton and enable the Inherit Module From Target checkbox.

image

Create an IBOutlet and register your view with PaymentsSDK on the viewDidLoad method using the registerCardDebitButton, create a new auth_token, set the Environment, and pass the CheckoutDelegate delegate instance. If you wish, you may also pass a customization object with the style overrides you want to apply. You also need to set the CardDebitRequest model with the data to proceed with the checkout.

@IBOutlet weak var checkoutButton: CheckoutButton!

...

override func viewDidLoad() {
    super.viewDidLoad()

    PaymentsSDK.shared
        .registerCardDebitButton(environment: .sandbox,
                                 token: authToken,
                                 view: addCardView,
                                 delegate: self)

    let model = CardDebitRequest( ... )

    self.checkoutButton.setRequestData(model)
}

Payment Checkout without UI

If you want to call the payment checkout service directly, use cardDebit to create a new auth_token, set the Environment, pass the CardDebitRequest model with the card data, and pass the CheckoutDelegate delegate instance.

let model = CardDebitRequest( ... )

PaymentsSDK.shared
    .cardDebit(environment: .sandbox,
               token: authToken,
               data: model,
               delegate: self)

Customization

The Payments SDK for iOS provides a set of UI styling and field validation customizations to allow you to adjust the provided UI to fit your needs by setting a style model. To customize the UI, start from the default style and make the changes; you can also select the card brands that you wish to support on validations. The default includes all brands. You can check the supported brands on CardBrand enum.

var style = AddCardStyle.getDefaultStyle()
style.acceptedCardBrands = [.visa, .mastercard]
style.backgroundColor = UIColor.white
...

Styling

Below are the styling options provided that are used to compose style models like AddCardStyle.

Class Attribute Description
ViewStyle backgroundColor UIColor that affects the background color of UIView
TextStyle color UIColor that affects the text color of UILabel
  font UIFont that affects the text font of UILabel
ButtonStyle backgroundColor UIColor that affects the background color of UIButton
  titleStyle TextStyle that affects the text font and color of UIButton
  cornerRadius CGFloat that controls the corner radius of UIButton
  margins UIEdgeInsets that controls the margins of UIButton
TextFieldStyle backgroundColor UIColor that affects the background color of UITextField
  textStyle TextStyle that affects the text font and color of UITextField text
  placeholderStyle TextStyle that affects the text font and color of UITextField placeholder

Fields

Below are the field customizations provided that can be used standalone or in style models like AddCardStyle.

Class Attribute Description
Validation regex validation regex
  minimumCharacters minimum allowed characters
  maximumCharacters maximum allowed characters
  keyboardType UIKeyboardType for field

Text and Localization

The Payments SDK for iOS allows you to customize the UI text. To do so, you will need to redefine the localization key that you want to change on your Localization.strings file. The next section details a list of the current localization keys. Currently, the SDK only provides english localization.

Localization Keys

Key English Value
alviere_sdk_payments_add_card_title Add Card
alviere_sdk_payments_add_card_number_placeholder Number
alviere_sdk_payments_add_card_expiration_date_placeholder Expiration Date
alviere_sdk_payments_add_card_cvc_placeholder CVC
alviere_sdk_payments_add_card_cvv_placeholder CVV
alviere_sdk_payments_add_card_cardholder_name_placeholder Cardholder Name
alviere_sdk_payments_add_card_zip_code_placeholder Zip Code
alviere_sdk_payments_add_card_add_title Add
alviere_sdk_payments_add_card_add_error_required_field Required
alviere_sdk_payments_add_card_add_error_invalid_field Invalid
alviere_sdk_payments_add_card_add_error_invalid_card Invalid or unsupported card
alviere_sdk_payments_payment_card_debit_checkout_title Checkout
alviere_sdk_error_title Error
alviere_sdk_error_try_again Try Again
alviere_sdk_error_generic An error has occurred