jszumski/adyen-ios

Adyen iOS Drop-in and Components

Adyen iOS

Adyen iOS provides you with the building blocks to create a checkout experience for your shoppers, allowing them to pay using the payment method of their choice.

You can integrate with Adyen iOS in two ways:

• iOS Drop-in: an all-in-one solution, the quickest way to accept payments on your iOS app.
• iOS Components: one Component per payment method and combine with your own payments flow.

Installation

Adyen iOS are available through either CocoaPods, Carthage or Swift Package Manager.

Minimum Requirements

• iOS 12.0
• Xcode 14.0
• Swift 5.7

CocoaPods

1. Add pod 'Adyen' to your Podfile.
2. Run pod install.

You can install all modules or add individual modules, depending on your needs and integration type. The Adyen/WeChatPay module needs to be explicitly added to support WeChat Pay. The Adyen/SwiftUI module needs to be explicitly added to use the SwiftUI specific helpers.

pod 'Adyen'               // Add DropIn with all modules except WeChat Pay and SwiftUI.
// Add individual modules
pod 'Adyen/Card'          // Card components.
pod 'Adyen/Session'       // Handler for the simplified checkout flow.
pod 'Adyen/Encryption'    // Encryption module.
pod 'Adyen/Components'    // All other payment components except WeChat Pay.
pod 'Adyen/Actions'       // Action Components.
pod 'Adyen/WeChatPay'     // WeChat Pay Component.
pod 'Adyen/SwiftUI'       // SwiftUI apps specific module.

⚠️ Adyen/AdyenWeChatPay and AdyenWeChatPayInternal modules doesn't support any simulators and can only be tested on a real device.

Carthage

1. Add github "adyen/adyen-ios" to your Cartfile.
2. Run carthage update.
3. Link the framework with your target as described in Carthage Readme.

You can add all modules or select individual modules to add to your integration. But make sure to include each module dependency modules.

• AdyenDropIn: DropInComponent.
• AdyenSession: handler for the simplified checkout flow.
• AdyenCard: the card components.
• AdyenComponents: all other payment components except WeChat Pay.
• AdyenActions: action components.
• AdyenEncryption: encryption.
• AdyenWeChatPay: WeChat Pay component.
• AdyenWeChatPayInternal: WeChat Pay component.
• AdyenTwint: Twint component.
• AdyenSwiftUI: SwiftUI apps specific module.

⚠️ AdyenWeChatPay and AdyenWeChatPayInternal modules doesn't support any simulators and can only be tested on a real device.

Swift Package Manager

1. Follow Apple's Adding Package Dependencies to Your App guide on how to add a Swift Package dependency.
2. Use https://github.com/Adyen/adyen-ios as the repository URL.
3. Specify the version to be at least 4.9.0.

You can add all modules or select individual modules to add to your integration. The AdyenWeChatPay module needs to be explicitly added to support WeChat Pay. The AdyenTwint module needs to be explicitly added to support Twint native flow. The AdyenSwiftUI module needs to be explicitly added to use the SwiftUI specific helpers.

• AdyenDropIn: all modules except AdyenWeChatPay.
• AdyenSession: handler for the simplified checkout flow.
• AdyenCard: the card components.
• AdyenComponents: all other payment components except WeChat Pay.
• AdyenActions: action components.
• AdyenEncryption: encryption.
• AdyenWeChatPay: WeChat Pay component.
• AdyenTwint: Twint component.
• AdyenSwiftUI: SwiftUI apps specific module.

⚠️ Swift Package Manager for Xcode 12.0 and 12.1 has a know issue when it comes to importing a dependency that in turn depend on a binary dependencies. A workaround is described here.

⚠️ AdyenWeChatPay and AdyenWeChatPayInternal modules doesn't support any simulators and can only be tested on a real device.

Drop-in

The Drop-in handles the presentation of available payment methods and the subsequent entry of a customer's payment details. It is initialized with the response of /sessions, and handles the entire checkout flow under the hood.

Usage

Setting up the Drop-in

All Components need an AdyenContext. An instance of AdyenContext wraps your client key, environment, analytics configuration and so on. Please read more here about the client key and how to get one. Use Environment.test for environment. When you're ready to accept live payments, change the value to one of our live environments

let apiContext = try! APIContext(environment: componentsEnvironment, clientKey: clientKey)
let context = AdyenContext(apiContext: apiContext,
                           payment: payment)
let configuration = DropInComponent.Configuration()

Create an instance of AdyenSession.Configuration with the response you received from the /sessions call and the AdyenContext instance.

let configuration = AdyenSession.Configuration(sessionIdentifier: response.sessionId,
                                               initialSessionData: response.sessionData,
                                               context: context)

Call the static initialize function of the AdyenSession by providing the configuration and the delegates, which will asynchronously create and return the session instance.

AdyenSession.initialize(with: configuration, delegate: self, presentationDelegate: self) { [weak self] result in
    switch result {
    case let .success(session):
        // store the session object
        self?.session = session
    case let .failure(error):
        // handle the error
    }
}

Create a configuration object for DropInComponent. Check specific payment method pages to confirm if you need to include additional required parameters.

// Check specific payment method pages to confirm if you need to configure additional required parameters.
let dropInConfiguration = DropInComponent.Configuration()

Some payment methods need additional configuration. For example ApplePayComponent. These payment method specific configuration parameters can be set in an instance of DropInComponent.Configuration:

let summaryItems = [
                      PKPaymentSummaryItem(label: "Item A", amount: 75, type: .final),
                      PKPaymentSummaryItem(label: "Item B", amount: 25, type: .final),
                      PKPaymentSummaryItem(label: "My Company", amount: 100, type: .final)
                   ]
let applePayment = try ApplePayPayment(countryCode: "US",
                                       currencyCode: "USD",
                                       summaryItems: summaryItems)

dropInConfiguration.applePay = .init(payment: applePayment,
                                     merchantIdentifier: "merchant.com.adyen.MY_MERCHANT_ID")

Also for voucher payment methods like Doku variants, in order for the DokuComponent to enable the shopper to save the voucher, access to the shopper photos is requested, so a suitable text needs to be added to the NSPhotoLibraryAddUsageDescription key in the application Info.plist.

Presenting the Drop-in

Initialize the DropInComponent class and set the AdyenSession instance as the delegate and partialPaymentDelegate (if needed) of the DropInComponent instance.

let dropInComponent = DropInComponent(paymentMethods: session.sessionContext.paymentMethods,
                                      context: context,
                                      configuration: dropInConfiguration)
 
// Keep the Drop-in instance to avoid it being destroyed after the function is executed.
self.dropInComponent = dropInComponent
 
// Set session as the delegate for Drop-in
dropInComponent.delegate = session
dropInComponent.partialPaymentDelegate = session
 
present(dropInComponent.viewController, animated: true)

Implementing AdyenSessionDelegate

AdyenSession makes the necessary calls to handle the whole flow and notifies your application through its delegate, AdyenSessionDelegate. To handle the results of the Drop-in, the following methods of AdyenSessionDelegate should be implemented:

---

func didComplete(with result: AdyenSessionResult, component: Component, session: AdyenSession)

This method will be invoked when the component finishes without any further steps needed by the application. The application just needs to dismiss the current component, ideally after calling finalizeIfNeeded on the component.

---

func didFail(with error: Error, from component: Component, session: AdyenSession)

This method is invoked when an error occurred during the use of the Drop-in or the components. You can then call the finalizeIfNeeded on the component, dismiss the component's view controller in the completion callback and display an error message.

---

func didOpenExternalApplication(component: DropInComponent)

This optional method is invoked after a redirect to an external application has occurred.

---

Handling an action

Actions are handled by the Drop-in via its delegate AdyenSession.

Receiving redirect

In case the customer is redirected to an external URL or App, make sure to let the RedirectComponent know when the user returns to your app. Do this by implementing the following in your UIApplicationDelegate:

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
    RedirectComponent.applicationDidOpen(from: url)

    return true
}

Components

In order to have more flexibility over the checkout flow, you can use our Components to present each payment method individually. Implementation details of our Components can be found in our Components API Reference.

Available Components

• Card Component
• 3D Secure 2 Component
• Apple Pay Component
• BCMC Component
• SEPA Direct Debit Component
• MOLPay Component
• Dotpay Component
• EPS Component
• Entercash Component
• Open Banking Component
• WeChat Pay Component
• Qiwi Wallet Component
• Redirect Component
• MB Way Component
• BLIK Component
• Doku Component
• Boleto Component
• ACH Direct Debit Component
• Affirm Component
• Atome Component
• BACS Direct Debit Component
• Online Banking Czech republic Component
• Online Banking Slovakia Component
• Online Banking Poland Component
• UPI Component
• QRCode Component
• Cash App Pay Component
• Twint Component

Customization

Both the Drop-in and the Components offer a number of customization options to allow you to match the appearance of your app. For example, to change the section header titles and form field titles in the Drop-in to red, and turn the submit button's background to black with white foreground:

var style = DropInComponent.Style()
style.listComponent.sectionHeader.title.color = .red
style.formComponent.textField.title.color = .red
style.formComponent.mainButtonItem.button.backgroundColor = .black
style.formComponent.mainButtonItem.button.title.color = .white

let dropInComponent = DropInComponent(paymentMethods: paymentMethods,
                                      configuration: configuration,
                                      style: style)
dropInComponent.delegate = self.session

Or, to create a black Card Component with white text:

var style = FormComponentStyle()
style.backgroundColor = .black
style.header.title.color = .white
style.textField.title.color = .white
style.textField.text.color = .white
style.switch.title.color = .white

let component = CardComponent(paymentMethod: paymentMethod,
                              apiContext: context.apiContext,
                              style: style)
component.delegate = self.session

A full list of customization options can be found in the API Reference.

See also

• Complete Documentation

• Components API Reference

• Drop-in Integration

• Advanced flow

Support

If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our support team.

Contributing

We strongly encourage you to join us in contributing to this repository so everyone can benefit from:

• New features and functionality
• Resolved bug fixes and issues
• Any general improvements

Read our contribution guidelines to find out how.

License

This repository is open source and available under the MIT license. For more information, see the LICENSE file.