Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
docs: add android integration guide (#12975)
Szymon Chorobski354855ff7bbb
diff --git a/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdx b/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdxnew file mode 100644index 0000000000..7eaf3c2738--- /dev/null+++ b/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdx@@ -0,0 +1,154 @@+---+title: Adyen Integration Guide for Android+description: This guide provides step-by-step instructions for integrating Adyen Android Drop-in with spree_adyen using session flow and Drop-In component.+---++<Warning>+This guide is aimed at advanced users who want to create adyen integration for their custom android application.+You also need to install Spree Adyen extension before.+</Warning>+++## Resources++- [Official Adyen Documentation for Android integration](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Android&integration=Drop-in&version=5.13.1)+- Spree Adyen API docs - [create payment_session](https://spreecommerce.org/docs/api-reference/storefront/adyen/create-an-adyen-payment-session) and [GET payment_session](https://spreecommerce.org/docs/api-reference/storefront/adyen/get-an-adyen-payment-session)+- [Offcial Adyen example for Android integration](https://github.com/adyen-examples/adyen-android-online-payments)++## Overview++The integration consists of two main components:+- **Spree Adyen**: Provides API for your client and receive payment result from Adyen+- **Your Android client app**: Shows the Drop-in UI and handles payment flow++## Step 1: Import the library++Import the compatibility module:++import the module with Jet Compose+```+implementation "com.adyen.checkout:drop-in-compose:YOUR_VERSION"+```++import without Jet Compose+```+implementation "com.adyen.checkout:drop-in:YOUR_VERSION"+```++## Step 2: Create a checkout session++Create session using [this endpoint](https://spreecommerce.org/docs/api-reference/storefront/adyen/create-an-adyen-payment-session).++```+val sessionModel = SessionModel.SERIALIZER.deserialize(sessionsResponseJSON)+```++sessionsResponseJSON should contain:+- `sessionData` - available as `adyen_data` in payment_session API response+- `id` - available as `adyen_id` in payment_session API response+++## Step 3++call `CheckoutSessionProvider.createSession` passing serialized session data (`sessionModel`) and `dropInConfiguration`++dropInConfiguration example:++```+val checkoutConfiguration = CheckoutConfiguration(+ environment = environment,+ clientKey = clientKey,+ shopperLocale = shopperLocale, // Optional+ ) {+ // Optional: add Drop-in configuration.+ dropIn {+ setEnableRemovingStoredPaymentMethods(true)+ }++ // Optional: add or change default configuration for the card payment method.+ card {+ setHolderNameRequired(true)+ setShopperReference("...")+ }++ // Optional: change configuration for 3D Secure 2.+ adyen3DS2 {+ setThreeDSRequestorAppURL("...")+ }+ }+```+see also: https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Web&integration=Drop-in&version=6.18.1#create-instance+++`environment` - enum: `live` or `test`+`clientKey` - `client_key` from payment_sessions endpoint+`shopperLocale` - shopper locale in ISO format+++```+ // Create an object for the checkout session.+ val result = CheckoutSessionProvider.createSession(sessionModel, dropInConfiguration)++ // If the payment session is successful, handle the result.+ // If the payment session encounters an error, handle the error.+ when (result) {+ is CheckoutSessionResult.Success -> handleCheckoutSession(result.checkoutSession)+ is CheckoutSessionResult.Error -> handleError(result.exception)+ }+```++## Step 4: Launch and show Drop-in++```+ override fun onDropInResult(sessionDropInResult: SessionDropInResult?) {+ when (sessionDropInResult) {+ // The payment finishes with a result.+ is SessionDropInResult.Finished -> handleResult(sessionDropInResult.result)+ // The shopper dismisses Drop-in.+ is SessionDropInResult.CancelledByUser ->+ // Drop-in encounters an error.+ is SessionDropInResult.Error -> handleError(sessionDropInResult.reason)+ // Drop-in encounters an unexpected state.+ null ->+ }+ }+```++## Step 5: Create the Drop-in launcher++DropIn.startPayment, passing:+- dropInLauncher - The Drop-in launcher object+- checkoutSession - result of `CheckoutSessionProvider.createSession`+- dropInConfiguration - Your Drop-in configuration++Example:+```+ import com.adyen.checkout.dropin.compose.startPayment+ import com.adyen.checkout.dropin.compose.rememberLauncherForDropInResult++ @Composable+ private fun ComposableDropIn() {+ val dropInLauncher = rememberLauncherForDropInResult(sessionDropInCallback)++ DropIn.startPayment(dropInLauncher, checkoutSession, dropInConfiguration)+ }+```++# Get payment outcome++1. Wait for backend to process the payment+2. Continue shopping experience++## 1. Wait for backend to process the payment++backend will change the state of `payment_session` to one of the following state++- `pending` - chosen payment method can take a while to complete+- `completed` - payment resulted in success, order completed+- `canceled` - payment canceled, payment is `void`+- `refused` - payment failed++2. Continue shopping experience++if succeed - order is processed and completed+if failed - payment can be retried using new payment session\ No newline at end of file