SDK IOS v2

• Description
• Changelogs
• Installation
• Usage
  • Initialization
  • Configuration
  • Logging configuration
  • UI configuration
  • Card list
  • Hosted Fields
  • Native Card Form
    • Form Display Customization
• The DALENYSSDKDelegate object
• Making a payment
  • 3-D Secure
• Example usage
  • Initialization
  • Delegate handling
  • Payment via Bank Card account type
  • Payment via Paypal account type
  • Payment with Hosted fields
  • Show Card List

Description

The Dalenys iOS SDK is a Swift framework that provides native wrappers for interacting with the Dalenys payment REST API. For a complete overview of the Dalenys payment system and an explanation of all of the various account types and payment options see the Dalenys developer documentation.

info

Use of the SDK requires a Dalenys account.

• The current version of the SDK is: 2.3.2
• The current Swift version supported is: 5.3

• The current Xcode version supported is: 12.x

• Swift 5.1, branch master version >= 0.7.1

Changelogs

Installation

info

The SDK is distributed via Cocoapods on a Dalenys Payment’s private repository. You must ask an access to your payment manager and provide a dedicated deploy key to install the SDK from this repository.

tips

You can find here a link to help you generate and use a ssh key authentication through our github private repository.

Once the key is generated, you have to provide the public part of the generated key to your payment manager.

In your Podfile, add the private pod spec repository:

# when adding custom spec repos, you must explictly define the Cocoapods Master Spec

source 'https://github.com/CocoaPods/Specs.git'
source 'git@github.com:be2bill/sdk-ios.git'
# other sources here... #

Add the Dalenys SDK pod:

pod 'Dalenys', '~> 2.3.2'

Then, run the following command:

$> pod install

info

The pod depends on the following libraries:

• CryptoSwift
• CardIO (redistributed as a framework in our private pod spec)

The SDK provides credit card scanning functionality via Paypal’s CardIO iOS SDK; it is therefore necessary to add the following usage description keys to your project’s Info.plist:

• NSCameraUsageDescription
• NSPhotoLibraryUsageDescription

Usage

Initialization

To initialize the SDK, in the application delegate’s application(_:didFinishLaunchingWithOptions:) method, call the SDK’s initialize method:

let config = DALENYSSDK.Configuration(
  ...params...
)

DALENYSSDK.initialize(
  with: application,
  configuration: config
)

The initialize method requires two parameters: the application object and an instance of a DALENYSSDK.Configuration object. This object is explained in detail below.

Configuration

The DALENYSSDK.Configuration class is used to configure the SDK and is required for initialization. The class initializer takes 4 parameters :

public init(apiKeyId: String, apiKey: String, directLinkUrl: String, redirectUrl: String)

• apiKeyId is your Dalenys SDK API KEY ID
• apiKey is your Dalenys SDK API KEY
• directLinkUrl is the URL used to communicate with the Dalenys backend
• redirectUrl is the URL used when redirecting from certain webform payment options such as 3DSECURE, it must match the REDIRECT_URL specified in your account setup in the Dalenys Dashboard.

All of these parameters will be communicated to you via your Dalenys account. See here for more information.

In addition to these 4 required parameters, there are two additional configuration options: Logging and UI Configuration.

Logging configuration

You can set the logging level via the logLevel(_:) method on the DALENYSSDK.Configuration object:

let config = DALENYSSDK.Configuration(...)
                       .logLevel(.full)

The available levels are:

• .none
• .error
• .full

The default is .none, and won’t log anything. This level should be used in production builds. .error will log only errors and .full will log all information available to the console.

UI configuration

You can configure the UI of the SDK to match your app’s theme. The elements available for customization can be found in the DALENYSSDK.UIConfiguration class and can be set with the .uiConfiguration() method of DALENYSSDK.Configuration:

let uiConfig = DALENYSSDK.UIConfiguration()
                            .primaryColor(UIColor.green)
                            // other UI configuration options here

let config = DALENYSSDK.Configuration(...)
                       .uiConfiguration(uiConfig)

Available options include:

• primaryColor(_:)
• separatorColor(_:)
• buttonTextColor(_:)
• placeholderColor(_:)
• textColor(_:)
• errorColor(_:)
• toolbarColor(_:)
• textFieldBackgroundColor(_:)
• screenBackgroundColor(_:)
• logoImage(_:)
• showCvvValidation(_:):

All UIConfiguration parameters are optional. For an up-to-date list, see the API Reference.

Card list

As of version 2.1.0, you are responsible for saving the card alias and associated information in your database. You will have to supply these information to the SDK to propose a list of recorded cards to the end user.

To show the card list, you first need to construct an array of DPCardInfo objects and call the SDK’s showCardList method:

let cards: [DPCardInfo] = [...]
DALENYSSDK.showCardList(cards)

Here is the structure of DPCardInfo:

class DPCardInfo: NSObject {

    public var alias: String
    public var label: String
    public var cardNetwork: DPCardType
    public var cardFullName: String?
    public var cardValidityDate: Date

}

To receive events from the card list you need to register a DPCardListDelegate object. This is done directly on the DALENYSSDK class:

override func viewDidLoad() {
  super.viewDidLoad()
  DALENYSSDK.registerCardListDelegate(self)
}

The delegate must be unregistered when you have finished using it:

deinit {
  DALENYSSDK.unregisterCardListDelegate()
}

A DPCardListDelegate must implement two methods:

• cardDidSelect(_:DPCardInfo): notifies the delegate that the user has selected a card
• addButtonClicked(): notifies the delegate that the user wants to pay with a new card

info

You can also use a custom Card List. In this case you need to set the alias on the operation params.

Example:

func cardDidSelect (alias: String) {
    let bankCardParams = DPPaymentParamsBankCard(hfToken: nil)

    //Set the alias of card selected by the user
    bankCardParams.alias = alias

    //Add required other datas
    let amout: DPAmount = //Initialize a DPAmout
    let identifer: String = //Your identifier
    let clientIdent: String = //Your clientIdent
    let cartDescription: String = //The cart description
    let orderId: String = //The orderId

    //Call the payment method to start the transaction
    DALENYSSDK.payment(options: bankCardParams, identifier: identifer, amount: amout, clientIdent: clientIdent, cartDescription: cartDescription, orderId: orderId)
}

Hosted Fields

The hosted-fields mode is the best compromise between security, ease of customization and payment form integration.

This integration mode aims to diminish your PCI-DSS constraints down to SAQ-A level requirements.

For more information about the technical implementation of hosted-fields mode, see the REST API documentation

info

Since the 2.1.1 version of the SDK, hosted fields is the preferred payment mode. The native payment-form mode is deprecated and will be removed shortly.

To display your Hosted Fields form, call the SDK’s showHostedFields(_:URL) method:

let url = URL(string: ...)
DALENYSSDK.showHostedFields(url)

Your are responsible of the HostedFields Webpage (the HTML page displayed to the end user).

When the HFToken will be returned by the Dalenys Javascript SDK, call the dalenyssdk://hostedfields url with result parameters described below. The SDK will intercept this url and transform Url Encoded Data into a DPHostedFieldsResult.

The accepted url encoded keys are :

• hfToken as String
• cardFullName as String
• createAlias as Boolean
• cardType as String. The accepted values are listed below. Note that this list can be extended in future releases.
  • unknown
  • cb
  • visa
  • mastercard
  • bancontact
  • sepa
  • americanExpress
• cardCode as String. It will contain a non-sensible (truncated) version of the card code. Ex: 111122XXXXXX4444.
• cardValidityDate as String (MM-YY)

You can add other parameters in the redirect url. They will be stored into vendorDatas.

To receive events from the hosted fields form, you need to register a DALENYSHostedFieldsDelegate object. This is done directly on the DALENYSSDK class:

override func viewDidLoad() {
  super.viewDidLoad()
  DALENYSSDK.registerHostedFieldsDelegate(self)
}

The delegate must be unregistered when you have finished using it:

deinit {
  DALENYSSDK.unregisterHostedFieldsDelegate()
}

A DALENYSHostedFieldsDelegate has a single method:

• deliverHostedFieldsResult(_:DPHostedFieldsResult): the delegate receives the result of the hosted fields in the form of a DALENYSSDK.DPHostedFieldsResult object.

Native Card Form

This integration mode is deprecated. For bank card operations, the SDK presents a form so the user can complete their personal details.

info

if the payment method is called with an implementation of DPAliasable and no alias or hftoken is provided, the SDK will automatically show the native card form.

Form Display Customization

For credit card payments, the SDK presents a form so the user can complete their personal details. The SDK exposes four customization options that allow you to control the fields that will be displayed.

Three of these options are found on the DPAliasable class, which you use via one of it’s concrete subclasses (DPPaymentParamsAliasable, DPAuthorizationParamsAliasable) :

And the fourth option is found on DALENYSSDK.UIConfiguration:

The DALENYSSDKDelegate object

When you are ready to make a payment via the SDK, you first need to register a delegate object. This is done directly on the DALENYSSDK class :

override func viewDidLoad() {
        super.viewDidLoad()
        DALENYSSDK.registerDelegate(self)
}

The delegate must be unregistered when you have finished using it:

deinit {
        DALENYSSDK.unregisterDelegate()
}

A DALENYSSDKDelegate must implement two methods:

• hostViewController(): the delegate is responsible for providing a ViewController that will be used to present the SDK’s internal user interface
• deliverResult(_:DPResult): the delegate receives the result of an operation in the form of a DALENYSSDK.DPResult object.

With this DPResult you can access transaction result like the created alias if you set createAlias to true in the operation params. Example:

func deliverResult(_ result: DPResult) {
    let createdAlias = result.alias
    //Store this alias for a future transaction
}

With an optional third that can be implemented for testing purposes:

• logged(_:String): provides a hook to recover the text that is logged to the console.
• userDidCancelTransaction(): Call when user cancel the current transaction

Making a payment

Currently the Dalenys SDK supports two operation types: Payment and Authorization.

To make a payment, you have to use the class function payment:

public class func payment<T>(options: T, identifier: String, amount: DALENYSSDK.DPAmount, clientIdent: String, cartDescription: String, orderId: String) where T : DALENYSSDK.DPBasePayAuthParams

where:

• options: is an instance of one of the available account types (ex. DPPaymentParamsBankCard)
• identifier: The identifier of the Dalenys account that you want to receive payment on
• amount: A DPAmount instance representing either a single or n-times payment amount
• clientIdent: The client’s identifier
• cartDescription: a description of the cart
• orderId: The client’s order ID

info

The DPBaseParams and its subclasses provide three types of information to the SDK:

• The class type (ex. DPPaymentParamsPaypal) provides the account type to be used for this transaction (in this case, Paypal)
• The operation type (ex. .payment or .authorization) to be used for this transaction
• The transaction parameters (ex. clientEmail, shipToFirstName, etc.)

For more information on DPBaseParams see the API Reference and the Integration Documentation

info

The DPAmount encapsulates a transaction amount and has 2 usable subclasses:

• DPSingleAmount: specifies a one-time payment
• DPMultipleAmount: specifies an n-times payment

These classes are instantiated with the class methods singleAmount(cents:, locale:) and multipleAmount(locale:) on the DPAmount class, where the locale is the locale of the client’s selected currency. The locale is only used to display the currency symbol and is not transmitted to the Dalenys backend. The currency is tied to the vendor account used for the transaction, it is not controlled by the SDK.

For more information on DPAmount see the API Reference.

3-D Secure

warning

From IOS 2.2.0, the 3DSECURE field has been deprecated. Use the 3DSECUREPREFERENCE field to control the triggering of the 3DS.

Here are the possible values:

• sca ask for a strong authentication;
• frictionless ask for a frictionless authentication;
• nopref or absent, the decision will be made by Dalenys;
• scamandate strong authentication required by regulation

Example:

I want to activate 3DS => 3DSECUREPREFERENCE = SCA ou SCAMANDATE

Example usage

Initialization

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Configure UI
    let uiConfig = DALENYSSDK.UIConfiguration()
        .primaryColor(UIColor.green)
        .separatorColor(UIColor.gray)
        .buttonTextColor(UIColor.orange)
        .placeholderColor(UIColor.blue)
        .textColor(UIColor.black)
        .errorColor(UIColor.red)
        .toolbarColor(UIColor.cyan)
        .textFieldBackgroundColor(UIColor.white)
        .screenBackgroundColor(UIColor.lightGray)
        .logoImage(UIImage(named: "myLogoImage"))
        .showCvvValidation(true)

    // Configure SDK
    #if DEBUG
        let logLevel = DALENYSSDK.LogLevel.full
    #else
        let logLevel = DALENYSSDK.LogLevel.none
    #endif

        let config = DALENYSSDK.Configuration(
            apiKeyId: "MyDalenysIdentifier",
            apiKey: "MySecretKey",
            directLinkUrl: "https://example.com",
            redirectUrl: "https://myredirecturl.com"
        )
        .logLevel(logLevel)
        .uiConfiguration(uiConfig)

        // Initialize
        DALENYSSDK.initialize(with: application, configuration: config)

        return true
}

Delegate handling

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        DALENYSSDK.registerDelegate(self)
    }

    deinit {
        DALENYSSDK.unregisterDelegate()
    }
}

extension ViewController : DALENYSSDKDelegate {
    func hostViewController() -> UIViewController {
        return self
    }

    func deliverResult(_ result: DPResult) {
        debugPrint(result)
        // handle the result
    }

    func userDidCancelTransaction () {
        // Handle the cancel action
    }
}

Payment via Bank Card account type

@IBAction func paymentButtonClicked(_ sender: Any?) {
    let opts = DPPaymentParamsBankCard(hfToken: nil)
    opts.threeDsecure = true
    // configure more options here, see API Reference for more

    let identifier = "myDalenysVisaAccountIdentifierInUSD"

    let amount = DPAmount.singleAmount(cents: 10000, locale: Locale(identifier: "en_US"))

    let clientId = "MyClientId"

    let cartDescription = "My Cart Description"

    let orderId = "TEST-ORDER-001"

    DALENYSSDK.payment(
        options: opts,
        identifier: identifier,
        amount: amount,
        clientIdent: clientId,
        cartDescription: cartDescription,
        orderId: orderId
    )
}

Payment via Paypal account type

@IBAction func paymentButtonClicked(_ sender: Any?) {

    let opts = DPPaymentParamsPaypal()
    opts.clientEmail = "myclientemail@test.com" // Paypal requires a clientEmail
    // configure more options here, see API Reference for more

    let identifier = "myDalenysPayPalAccountIdentifierInEUR"  // Dalenys PayPal accounts only accept euros

    let amount = DPAmount.singleAmount(cents: 10000, locale: Locale(identifier: "fr_FR"))

    let clientId = "MyClientId"

    let cartDescription = "My Cart Description"

    let orderId = "TEST-ORDER-001"

    DALENYSSDK.payment(
        options: opts,
        identifier: identifier,
        amount: amount,
        clientIdent: clientId,
        cartDescription: cartDescription,
        orderId: orderId
    )
}

Payment with Hosted fields

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        //Register the delegates on viewDidLoad()
        DALENYSSDK.registerDelegate(self)
        DALENYSSDK.registerHostedFieldsDelegate(self)
    }

    deinit {
        //Unregister the delegates on deinit
        DALENYSSDK.unregisterDelegate()
        DALENYSSDK.unregisterHostedFieldsDelegate()
    }

    @IBAction func paymentButtonClicked(_ sender: Any?) {
        let hostedFieldsUrl = URL(string: ...)
        //Call the showHostedFields(...) method to show the web page associated with the hostedFieldsUrl
        DALENYSSDK.showHostedFields(hostedFieldsUrl)
    }
}

extension ViewController : DALENYSHostedFieldsDelegate {

    func deliverHostedFieldsResult(_ result: DPHostedFieldsResult) {
        //Store result data into DPHostedFieldsParams subclass
        let opts = DPPaymentParamsBankCard(hfToken: result.hfToken)
        opts.threeDsecure = true
        // configure more options here, see API Reference for more

        let identifier = "myDalenysVisaAccountIdentifierInUSD"

        let amount = DPAmount.singleAmount(cents: 10000, locale: Locale(identifier: "en_US"))

        let clientId = "MyClientId"

        let cartDescription = "My Cart Description"

        let orderId = "TEST-ORDER-001"

        DALENYSSDK.payment(
            options: opts,
            identifier: identifier,
            amount: amount,
            clientIdent: clientId,
            cartDescription: cartDescription,
            orderId: orderId
        )
    }
}

Show Card List

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        DALENYSSDK.registerDelegate(self)
        DALENYSSDK.registerCardListDelegate(self)
    }

    deinit {
        DALENYSSDK.unregisterDelegate()
        DALENYSSDK.unregisterCardListDelegate()
    }

    @IBAction func paymentButtonClicked(_ sender: Any?) {
        let expirationDateString = "12-20"
        let expirationDate = DPCardInfo.dateFormatter.date(from: expirationDateString)!
        let cards: [DPCardInfo] = [
            DPCardInfo(alias: "aerchbezdznnlezel", label: "MyVisaCard", cardNetwork: .visa, cardFullName: nil, cardValidityDate: expirationDate),
            DPCardInfo(alias: "dscuhdjscbbkzdsx", label: "MyVisaCard", cardNetwork: .mastercard, cardFullName: nil, cardValidityDate: expirationDate)
        ]
        DALENYSSDK.showCardList(cards)
    }
}

extension ViewController : DPCardListDelegate {

    func cardDidSelect(card: DPCardInfo) {
        //Put the DPCardInfo data in the DPAliasable instance
    }


    func addButtonClicked() {
        //Show the hosted fields form or the native form
    }
}