Integrate our Checkout SDK for Android with your own UI.
Our Checkout SDK for Android gives you the ability to take advantage of the SDK's payment flow, including the encrypted communication between the SDK and Adyen, but collect and present information using your own UI. There are additional functions that you need to implement to do this, which we explain below. 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:
- Install the Android SDK.
- Initialize the SDK.
- Create a payment session from your server.
- Build your payment flow.
- Verify the payment result on your server.
Before accepting live payments, we also recommend that you test your integration.
Step 1: Install SDK
Import the SDK modules into your project:
Add the following to your build.gradle file.
Step 2: Initialize SDK
startPaymentmethod of the
tokenwill be returned in
tokento your server to create a payment session.
paymentSessionvalue received by your server with
Step 3: 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
You can also use our demo server until you have implemented your own:
- In the request, specify:
merchantAccount: Your merchant account name.
returnUrl: The URI of your app.
reference: Your unique reference for this payment.
countryCode: The country code of the shopper.
token: The token generated by the SDK.
Execute this code from your server, not your app. This helps to prevent tampering with transaction data.
- Use the
paymentSessionyou receive in the response to initialize the SDK.
Step 4: Build payment flow
You'll need to create your app's payment flow by building a UI that responds to the SDK's observers and handlers.
PaymentHandleryou retrieved earlier from the
PaymentReferenceis Parcelable, so you can pass it along to another
Attach the observers and handlers below in the scope of the current
Activity. These will be removed automatically when the
Show progress indicator
- Attach an observer to the
NetworkingStateObservable. When the networking state changes, this will receive a callback with the latest
isExecutingRequestsis true, present a progress indicator to the shopper in your UI.
Present available payment methods
To present a list of available payment methods to the shopper:
Attach an observer to the
PaymentSessionObservable. This will be lifecycle aware, and receive callbacks with the latest
- From the
paymentSession, retrieve a list of available payment methods . These are represented in two indexed arrays:
oneClickPaymentMethods: One-click enabled payment methods, that the shopper has used previously.
paymentMethods: All other payment methods.
Present a list of available payment methods in your UI.
You should also refresh the list of payment methods in your UI whenever the
When the shopper has chosen a payment method, present a form in your UI, and collect the required payment details from the shopper. Use the
typeto determine which payment method input screen to present, and show input fields based on the required
For example, if the shopper selected the payment method at index 5:
Use the shopper's chosen payment method and the payment details that you collected from the shopper to submit the payment:
- In a
paymentMethodDetailsobject, provide the required payment details.
Pass these, together with the
paymentMethodthe shopper selected, to the SDK by calling
initiatePayment. In the example below we show how you'd do this for an issuer-based payment method such as iDEAL, where:
InputDetailat index 0 has
Itemat index 5 is the shopper's selected issuer.
Optional: Collect SMS verification
For some payment methods, such as China UnionPay, you'll need to collect SMS verification codes. When required, the
onAdditionalDetailsRequired is called.
Use the parameters in
additionalDetailsto present an input field in your UI to collect the SMS verification code from the shopper.
For many local payment methods, such as iDEAL and Sofort, and card payments with 3D Secure verification, you'll need to redirect the shopper to a webpage or app to verify the payment. Once verified, they will be returned to your app. The
onRedirectRequired method is called when a redirect is required.
Redirect the shopper to the URI specified in
Once the shopper has completed verification, they'll be redirected to the URI you passed when you created the payment session. Then call
handleRedirectResultto dispatch the data from the
You should declare an
Activitythat handles the redirect to this URI in your AndroidManifest.
Handle payment result
Attach an observer to the
PaymentResultObservable. This will receive a callback with the
PaymentResultwhen the payment has been processed.
Present the received payment result to the shopper in your calling Activity. For a list of possible payment results and what they mean, refer to Result codes.
- You'll also receive a
payload. Send this to your server to verify the result of the payment.
Set a handler with
setErrorHandler. This will receive a callback with a
CheckoutExceptionwhen an error unrelated to the payment result occurred.
- Use the parameters contained in
CheckoutExceptionto determine the cause of the error:
Present an error message to the shopper in your UI.
Step 5: Verify payment result
/payments/resultrequest. Include the
payloadthat was generated by the SDK.
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 notifications, you'll also receive a successful AUTHORISATION notification.
If you received a different
resultCode, check our result codes documentation for what action you should take.
Testing your integration
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.
Set up notifications
Receive confirmation when a payment is authorised or fails.
Add payment methods
Learn about payment methods and how to integrate them.
Find out how to cancel, refund, or capture a payment using our API.