Android SDK

The Checkout SDK allows you to integrate key payment methods and 3D Secure into your Android app.

It comes with a pre-built UI that allows for some customization. For more control over the UI, you can also present the payment form using your own UI.

The SDK handles presenting a list of payment methods to the shopper, collecting their details, and submitting them to Adyen. It also takes care of encrypting and transmitting sensitive payment data, so it never touches your server. To use the SDK, you'll also need to set up a server that can create a payment session and verify the result of payments.

To accept online payments with the Checkout SDK, you'll need to:

1. Integrate the Android SDK.
2. Create a payment session from your server.
3. Verify the payment result on your server.

Before accepting live payments, we also recommend that you test your integration.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

After you have created your test account, get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.

Step 1: Integrate SDK

To add the Checkout SDK to your app:

1. Import the SDK

   Add the SDK modules into your project by adding the following to your build.gradle file.

   final checkoutVersion = "2.x.x"
   implementation "com.adyen.checkout:ui:${checkoutVersion}"
   implementation "com.adyen.checkout:nfc:${checkoutVersion}" // Optional; Integrates NFC card reader in card UI
   implementation "com.adyen.checkout:wechatpay:${checkoutVersion}" // Optional; Integrates support for WeChat Pay

2. Initialize SDK

   Next, call the startPayment method of the CheckoutController class. 

   CheckoutController.startPayment(/*Activity*/ this, new CheckoutSetupParametersHandler() {
       @Override
       public void onRequestPaymentSession(@NonNull CheckoutSetupParameters checkoutSetupParameters) {
           // TODO: Forward to your own server and request the payment session from Adyen with the given CheckoutSetupParameters.
       }
   
       @Override
       public void onError(@NonNull CheckoutException checkoutException) {
           // TODO: Handle error.
       }
   });

   A token and returnUrl will be returned in CheckoutSetupParameters. Pass these to your server to create a payment session. Then, handle the paymentSession value received by your server with CheckoutController. 

   String encodedPaymentSession = PAYMENTSESSION_VALUE_RECEIVED_BY_YOUR_SERVER;
   CheckoutController.handlePaymentSessionResponse(/*Activity*/ this, encodedPaymentSession, new StartPaymentParametersHandler() {
       @Override
       public void onStartPaymentParameters(@NonNull StartPaymentParameters startPaymentParameters) {
           // TODO: Start the desired checkout process.
       }
   
       @Override
       public void onError(@NonNull CheckoutException checkoutException) {
           // TODO: Handle error.
       }
   });

3. Present payment form

   Use StartPaymentParameters to present the payment form to the shopper.

   PaymentMethodHandler paymentMethodHandler = CheckoutController.getCheckoutHandler(startPaymentParameters);
   paymentMethodHandler.handlePaymentMethodDetails(/* Activity */ this, REQUEST_CODE_CHECKOUT);

   When the shopper completes the payment form and clicks  Pay, the Checkout SDK submits their payment details to the Adyen payments platform.

4. Handle payment result

   When the payment is completed you will receive the result in your calling Activity. Present this to the shopper in your app. For a list of possible payment results and what these mean, refer to Result codes.

   You'll also receive a payload. Send this to your server to verify the result of the payment.

   @Override
   protected void onActivityResult(int requestCode, int resultCode, Intent data) {
       super.onActivityResult(requestCode, resultCode, data);
   
       if (requestCode == REQUEST_CODE_CHECKOUT) {
           if (resultCode == PaymentMethodHandler.RESULT_CODE_OK) {
               PaymentResult paymentResult = PaymentMethodHandler.Util.getPaymentResult(data);
               // Handle PaymentResult.
           } else {
               CheckoutException checkoutException = PaymentMethodHandler.Util.getCheckoutException(data);
   
               if (resultCode == PaymentMethodHandler.RESULT_CODE_CANCELED) {
                   // Handle cancellation and optional CheckoutException.
               } else {
                   // Handle CheckoutException.
               }
           }
       }
   }

Step 2: Create payment session

A payment session is used to securely transmit payment data between the shopper and the Adyen payments platform. Create one from your server by making a POST request to the /paymentSession endpoint.

Specify your merchantAccount name, and a channel of Android.

Also include the amount, your unique reference for this payment, and the countryCode of the shopper.

Finally, include the token and returnUrl generated by the SDK.

curl -H "Content-Type: application/json" -H "X-API-Key: YourAPIkey" -X POST -d '{
       "merchantAccount": "YourMerchantAccount",
       "channel": "Android",
       "amount": {
          "currency": "EUR",
          "value": 17408
       },
       "reference": "Your order number",
       "countryCode": "NL",
       "shopperLocale": "nl_NL",
       "token": "TOKEN_GENERATED_BY_SDK",
       "returnUrl": "URL_GENERATED_BY_SDK"
    }' https://checkout-test.adyen.com/v68/paymentSession

The response will contain a paymentSession. Use this to initialize the SDK.

Step 3: Verify payment result

Once the payment has been completed, verify its result from your server with a /payments/result request. Include the payload that was generated by the SDK.

curl \
-H "Content-Type: application/json" \
-H "X-API-Key: YourAPIkey" \
-X POST \
-d '{ "payload": "2he28Ddhwj242he28Ddhwj..." }' \
https://checkout-test.adyen.com/v66/payments/result

If the payment was successful you'll receive an Authorised resultCode and a pspReference, which is our unique identifier for the transaction. If you've set up webhooks, you'll also receive a successful AUTHORISATION events.

If you received a different resultCode, check our result codes documentation for what action you should take.

Next, let's look at how you can test your integration.

Testing your integration

Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the status of a test payment in your Customer Area, under Transactions > Payments.

When you've completed testing, there are some additional steps you'll need to complete before you can accept live payments from shoppers. Refer to Getting started with Adyen for more information.

Customizing your Checkout

You can customize the payment form presented in your app by:

• Adding your own styling.
• Setting the screen orientation.

In addition, you can sort and filter the list of payment methods presented to the shopper.

Styling

When your app has an AppCompat theme, the payment form rendered by the SDK will inherit your app's styling and font (from either AppTheme or AppTheme.Checkout).

To customize either of these, add new theme to your styles.xml file:

<style name="AppTheme.Checkout" parent="Theme.AppCompat[...]">
    <item name="colorPrimary">@color/checkoutColorPrimary</item>
    <item name="colorPrimaryDark">@color/checkoutColorPrimaryDark</item>
    <item name="colorAccent">@color/checkoutColorAccent</item>
    <item name="android:fontFamily">@font/montserrat</item>
    <item name="fontFamily">@font/montserrat</item>
</style>

Setting the screen orientation

By default, the payment form is displayed in portrait orientation. To use a different orientation, override the <integer> specified in your configuration.xml file:

<resources>
    <integer name="checkout_screenOrientation">1</integer>
</resources>

Set the orientation by specifying one of the following integers:

• 0: Landscape orientation.
• 1: Portrait orientation.
• 6: Sensor landscape orientation.
• 7: Sensor portrait orientation.

You can also use any screenOrientation referred to in the Android developer documentation. To do this, specify the Constant Value of your preferred screenOrientation as the <integer>.

Recurring and subscription payments

We recommend using our tokenization service to handle recurring payments and subscriptions.

To tokenize the shopper's payment details collected by the SDK, send additional parameters when creating a payment session. Pass enableOneClick and enableRecurring as true. Also provide a shopperReference  (minimum length three characters) to uniquely identify this shopper. This will act as the container for the shopper's tokenized payment details. The shopperReference will be stored when the token is created. 

curl https://checkout-test.adyen.com/v68/paymentsession \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
       "merchantAccount": "YourMerchantAccount",
       "returnUrl": "URL_GENERATED_BY_SDK",
       "channel": "Android",
       "amount": {
          "currency": "EUR",
          "value": 17408
       },
       "reference": "Your order number",
       "countryCode": "NL",
       "shopperLocale": "nl_NL",
       "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
       "enableRecurring": true,
       "enableOneClick": true,
       "token": "TOKEN_GENERATED_BY_SDK"
    }'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.checkout.paymentSession({
  :merchantAccount => "YourMerchantAccount",
  :returnUrl => "URL_GENERATED_BY_SDK",
  :channel => "Android",
  :amount => {
    :currency => "EUR",
    :value => 17408
  },
  :reference => "Your order number",
  :countryCode => "NL",
  :shopperLocale => "nl_NL",
  :shopperReference => "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j"
  :enableRecurring => true,
  :enableOneClick => true,
  :token => "TOKEN_GENERATED_BY_SDK"
}) 

// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
PaymentSessionRequest paymentSessionRequest = new PaymentSessionRequest();
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(17408);
paymentSessionRequest.setReference("Your order number");
paymentSessionRequest.setCountryCode("NL");
paymentSessionRequest.setShopperLocale("nl_NL");
paymentSessionRequest.setAmount(amount);
paymentSessionRequest.setChannel("Android");
paymentSessionRequest.setEnableRecurring(true);
paymentSessionRequest.setEnableOneClick(true);
paymentSessionRequest.setShopperReference("YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j");
paymentSessionRequest.setReturnUrl("URL_GENERATED_BY_SDK");
paymentSessionRequest.setMerchantAccount("YourMerchantAccount");
paymentSessionRequest.setToken("TOKEN_GENERATED_BY_SDK");
PaymentSessionResponse response = checkout.payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 17408
  ),
  "reference" => "Your order number",
  "channel" => "Android",
  "shopperReference" => "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
  "countryCode" => "NL",
  "shopperLocale" => "nl_NL",
  "returnUrl" => "URL_GENERATED_BY_SDK",
  "merchantAccount" => "YourMerchantAccount",
  "enableRecurring" => true,
  "enableOneClick" => true,
  "token" => "TOKEN_GENERATED_BY_SDK"
);
$result = $service->payments($params); 

Next, find out if the shopper's payment details was successfully tokenized by verifying the payment result. If the resultCode is Authorised, a recurringDetailReference value is also returned in the response. This is the identifier for the shopper's tokenized payment details.

If the resultCode is Pending, the payment details will be tokenized when the payment reaches an Authorised status. You will be informed of the status change through a webhook via our notification service. The recurringDetailReference is included in the notification if the payment has been authorised. For other result codes, see Pending and Refusal result codes under the Subscription tab.

Lastly, save the recurringDetailReference. You will use this and your corresponding shopperReference to make future payments. For more information, see Making payments with tokens.