Adyen Mobile Checkout

The Adyen Mobile Checkout library allows you to retrieve card details entered by clients in your iOS/Android app and accept payments with Adyen. In this case, Adyen generates a token to handle data securely and to take care of PCI compliance on your behalf.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

Mobile Checkout last update

Version

Date Changes
1.1 2016-09-09 Restructured and updated links and code samples.

Version

Date Changes
1.1 2016-09-09 Restructured and updated links and code samples.
1.0.1 2016-03-07 Updated information for importing binaries in Android.
1.0 2016-01-08

Initial version.

Mobile Checkout overview

Adyen provides you with several ways to integrate with the Adyen payment platform and start accepting payments in your mobile app. To simplify the way you integrate, Adyen introduced SDKs for iOS and Android and made them available on GitHub. Each repository contains an SDK and an example demonstrating the best way of utilizing this SDK.

Depending on your current implementation and your business requirements, refer to one of the following repositories.

iOS

Android

Mobile Checkout for iOS

Adyen Mobile Checkout for iOS is a native client for accepting payments in iOS applications. It is available at the public GitHub repository and is distributed under the MIT license.

This repository contains the example project on how to use the Mobile Checkout for iOS. To run this example application, clone the repository and then run this line in your terminal.

pod try 'AdyenCheckout'

Installing Checkout for iOS

Adyen Checkout is available through CocoaPods. To install, add the following line to your Podfile:

pod 'AdyenCheckout'

Usage

To start using the library, provide your public key and token that you use to connect to Adyen services.

Checkout.shared.publicKey = "YOUR_ADYEN_PUBLIC_KEY"
// OR
Checkout.shared.token = "YOUR_ADYEN_TOKEN"

Create a CheckoutRequest object with the specified values and use it to show a Checkout page with the CheckoutCardViewController object:

// Create a payment request.
let request = CheckoutRequest()
request.amount = 1.99
request.currency = "EUR"
request.reference = "Merchant Reference 123"

// Create the Checkout view controller.
let vc = CheckoutCardViewController(checkoutRequest: request)
vc.delegate = self
vc.titleText = "My Company"

// Present the controller.
let nc = UINavigationController(rootViewController: vc)
self.presentViewController(nc, animated: true, completion: nil)

And implement the CheckoutViewControllerDelegate functions:

func checkoutViewController(controller: CheckoutViewController, authorizedPayment payment: CheckoutPayment) {
    // Dismiss the view controller.
    controller.dismissViewControllerAnimated(true, completion: nil)

    // Send the payment to your server, which should validate it with Adyen.
    sendPayment(payment) { (psp, error) -> Void in
        if (error != nil) {
            let alert = UIAlertView(title: "Error", message: error!.localizedDescription, delegate: nil, cancelButtonTitle: "OK")
            alert.show()
        } else {
            let alert = UIAlertView(title: "Success!", message: "PSP: \(psp)", delegate: nil, cancelButtonTitle: "OK")
            alert.show()
        }
    }
}

func checkoutViewController(controller: CheckoutViewController, failedWithError error: NSError) {
    // Dismiss the view controller.
    controller.dismissViewControllerAnimated(true, completion: nil)

    // Show an error.
    let alert = UIAlertView(title: "Error", message: error.localizedDescription, delegate: nil, cancelButtonTitle: "OK")
    alert.show()
}

The CheckoutPayment class contains the following properties:

Property Type Description
amount Double

The payment amount to be charged.

currency String

The three-character  ISO currency code.

reference String

The merchant account identifier.

paymentData

String

The Base64-encoded string containing encrypted payment data. Ready for transmission through a merchant's server to Adyen.

Advanced usage

Take power with the advanced library usage. Display the card fields in your view by adding a separate CardPaymentField class.

let paymentFieldView = CardPaymentField()
self.view.addSubview(paymentFieldView)

Ensure that you have a valid public key for encryption, or get it with a token:

if (Checkout.shared.publicKey == nil) {
    Checkout.shared.fetchPublickKey({ (publicKey, error) -> Void in
        if (error != nil) {
            // Handle an error.          
        }
    })
}

Encrypt the obtained data:

if (paymentFieldView.valid) {
    let card = paymentFieldView.paymentData()
    do {
        let paymentData = try card.serialize()
        let payment = CheckoutPayment(request: self.request, encryptedData: paymentData)
        // Send a payment to Adyen.
    }
    catch let error as NSError {
        // Handle errors.
    }
}

Mobile Checkout for Android

Adyen Mobile Checkout for Android is a native client for accepting payments in Android applications. It is available at the public GitHub repository and is distributed under the MIT license.

You can integrate with the Adyen library by either:

Installing Checkout for Android

To start using Adyen Mobile Checkout for Android, you need to either import its sources from the GitHub, or use a plugin to automatically download the Mobile Checkout binaries and include them into your project.

Importing the binaries

  1. You can use the de.undercouch.download plugin for downloading the binaries of the Adyen Mobile Checkout. To enable this plugin, add the following line into the root directory's build.gradle file:

    buildscript {
        repositories {
            ...
        }
        dependencies {
            ...
            classpath 'de.undercouch:gradle-download-task:2.1.0'
        }
    }
  2. In the app module's build.gradle file, add the following task:

    import de.undercouch.gradle.tasks.download.Download
    
    ...
    
    task downloadAdyenLibrary(type: Download) {
        src 'https://raw.githubusercontent.com/Adyen/adyen-checkout-android/master/adyenpaysdk/adyenpaysdk-1.0.0.aar'
        src 'https://raw.githubusercontent.com/Adyen/adyen-checkout-android/master/adyenuisdk/adyenuisdk-1.0.0.aar'
        dest('libs');
    }
  3. Run this task using ./gradlew downloadAdyenLibrary command to download the adyenuisdk.aar and adyenpaysdk.aar files to you libs folder.

  4. Finally, add the following snippet in your build.gradle of the app module:

    repositories {
        flatDir {
            dirs 'libs'
        }
    }

Importing the sources

Follow the steps below:

  1. Run git pull https://github.com/Adyen/adyen-checkout-android.
  2. Copy adyenpaysdk and adyenuisdk in your application folder.
  3. Add ':adyenuisdk',':adyenpaysdk' in your settings.gradle file.
  4. From one of the modules' lib folder, copy volley-release.aar into your app's lib folder.
  5. Add the following code snippet to your android module in the build.gradle:

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
  6. Add the following code snippet to your dependencies module in the build.gradle:

    compile project(':adyenpaysdk')
    compile project(':adyenuisdk')

Default payment form

Follow these steps to display the predefined payment form in your Android applications.

  1. Install the Mobile Checkout for Android. Note that you should install both adyenuisdk and adyenpaysdk to use the predefined payment form.
  2. Add the PaymentActivity to your AndroidManifest.xml:

    <activity
        android:name="adyen.com.adyenuisdk.PaymentActivity"
        android:screenOrientation="locked"/>
  3. In order to launch PaymentActivity, add the code snippet below to the click event handler of your Checkout button.

    CheckoutRequest checkoutRequest = new CheckoutRequest();
    try {
        checkoutRequest.setBrandColor(your_brand_color);
        checkoutRequest.setBrandLogo(your_brand_logo);
        checkoutRequest.setCheckoutAmount(checkout_amount);
        checkoutRequest.setCurrency(Currency.EUR);
        checkoutRequest.setToken(your_token);
        checkoutRequest.setTestBackend(true); // false by default; set it to true to use Adyen's test backend.
    
        Intent intent = new PaymentActivity.PaymentActivityBuilder(checkoutRequest).build(this, context);
        startActivity(intent);
    } catch (CheckoutRequestException e) {
        Log.e("tag", e.getMessage(), e);
    }
  4. Make sure your Activity or Fragment implements the AdyenCheckoutListener interface. To do this, implement checkoutAuthorizedPayment(String paymentData, float amount) and checkoutFailedWithError(String errorMessage) methods. The paymentData parameter of checkoutAuthorizedPayment represents the encrypted payment data that needs to be sent to the merchant server.

For a complete code example of using the default payment form, check the adyen.com.pay.MainActivity.java file sources.

Default payment UI with custom elements

This is a combination of the Adyen checkout UI library and the Adyen checkout SDK. Using this approach you can display the default payment UI provided by Adyen and design your own screen around the payment form.

Follow the steps below:

  1. Install the Mobile Checkout for Android. Note that you should install both adyenuisdk and adyenpaysdk to use the predefined payment form.
  2. Add the credit card form inside your activity or fragment xml:

    <com.adyen.adyencheckout.ui.CreditCardForm
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />
  3. As you are implementing your own payment button, you need to call the following API calls in order to retrieve the encrypted card data and send it to your server.

    public void initPaymentButton() {
        mPayButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                if (CreditCardForm.isValid()) {
                    final CardPaymentData cardPaymentData = buildCardData();
                    Adyen.getInstance().setToken(extras.getString("token"));
                    Adyen.getInstance().setUseTestBackend(extras.getBoolean("useTestBackend"));
                    Adyen.getInstance().fetchPublicKey(new Adyen.CompletionCallback() {
                        @Override
                        public void onSuccess(String result) {
                            try {
                                CheckoutResponse checkoutResponse = new CheckoutResponse();
                                checkoutResponse.setPaymentData(cardPaymentData.serialize());
                                checkoutResponse.setAmount(extras.getFloat("amount"));
                                checkoutResponse.setCurrency(Currency.valueOf(extras.getString("currency")));
                                adyenCheckoutListener.checkoutAuthorizedPayment(checkoutResponse);
                            } catch (EncrypterException e) {
                                e.printStackTrace();
                            } catch (NoPublicKeyExeption noPublicKeyExeption) {
                                noPublicKeyExeption.printStackTrace();
                            }
                        }
    
                        @Override
                        public void onError(String error) {
                            adyenCheckoutListener.checkoutFailedWithError(error);
                        }
                    });
                }
            }
        });
    }

For a complete code example of using the default payment UI with custom elements, check the adyen.com.adyencheckout.ui.PaymentActivity.java file sources.

Custom payment UI

Follow these steps to create a completely custom UI for accepting payment in your Android application:

  1. Install the Mobile Checkout for Android. Note that you should install only adyenpaysdk in this case. 
  2. After including the library SDK in your Android application, implement the following API calls in order to retrieve the encrypted card data and send it to the your server.

    public void initCreditCardPayment(final CardPaymentData cardPaymentData) {
        Adyen.getInstance().fetchPublicKey(new CompletionCallback() {
            @Override
            public void onSuccess(String result) {
                String encryptedData = cardPaymentData.serialize();
    
                // Send encryptedData to your merchant server
            }
    
            @Override
            public void onError(String message) {
    
            }
        });
    }

For a complete code example of creating a custom payment form, check the adyen.com.adyenpaysdk.Adyen.java file sources.

Checkout flow

The following diagram shows the payment flow you should implement to start accepting payments in mobile applications. For more information on client-side encryption, refer to Easy encryption.

Merchant server

Although Adyen Mobile Checkout already wraps most of the integration complexity, you also need to set up a merchant server to validate the integrity of each payment request/response.

For an example of how you can build your own merchant server, see the Adyen repository.