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 adyen: add ios tutorial (#12978)
Szymon Chorobski663c546fbae7
diff --git a/docs/api-reference/storefront.yaml b/docs/api-reference/storefront.yamlindex 0a7a476788..7a298de0ca 100644--- a/docs/api-reference/storefront.yaml+++ b/docs/api-reference/storefront.yaml@@ -5754,6 +5754,10 @@ components:type: stringdescription: The payment currencyexample: USD+ client_key:+ type: string+ description: The Adyen client key+ example: 'your_client_key'adyen_data:type: stringdescription: The Adyen session data required for payment processing@@ -5809,6 +5813,7 @@ components:amount: '80.99'currency: USDadyen_data: 'Ab02b4c0!BQABAgCNxadId3f9NXF6OMYGXsZAoAwcnOdgINKAypoyo8GUq8UqjnT/7J8K4kNhl6tjWOpGY6t+r+4QQVVfo4IHFWtjzNkj2k9dnTS4932UyCznLC+gHbzPHcfN6rNiHBIpQo523a94EvV2Sq1Gh/3j6N2aNCjfV2TDWynQJU11uOhalgwhAnVrD3HmFtbVqM60kGiPRBfE4LwLuQ7f+7S/cdVx8HzWizvafndeRnx5lM3RQNibNRbimJ3G6YZh/HI9FwZYbxkUoq8dQl8dgdquNKAxsSO0BcC6UpTU2Z8d/z3lAsm0UlX1+YiryRut4Ipg9YqJbVt3gnj7Kh4kZFRO1hZM8NDeD9PshE8riBXDpUwJ84m+9I+cfbnwYWgfZaGuxfGG+IiiliQBWIjHefd6ukUATLWsPX6ufUL7BT3rSMx/5QMmdNrE/zMA9B1tFg5Tm8t88S6WQcSZ/vIgOv+peDml5j44OcEth6iEqxRwsmT3T0nZUhYwYUSTEykrpY9+Ly2+NWpTE+sgvXhld6SZubbbG9gIBad6TIwaKkUO0kJOx6Zvk37uU2D0z8mnWIktimBZIqhegsdBXutVyUe93xSighf/C41n69COSjALE3KCcXGCmR4NsdwJ7LesJMYLu1S4gDOObvkuW5IY2k8r6pptUWgsOxcyUvbpPMlQrjRTHAwRPxcnk0SJrSL29HwASnsia2V5IjoiQUYwQUFBMTAzQ0E1MzdFQUVEODdDMjRERDUzOTA5QjgwQTc4QTkyM0UzODIzRDY4REFDQzk0QjlGRjgzMDVEQyJ9JcDZ7NsVaMwwHpvV0vX/5b7P9FS/1TfuFbQRmlFX4vCQOLxSiyAf5P4uN7Hb2Zw4dplBl4oSEBBUvrKk5TCqjGoS1azHS8Fv5LCcl2yCDH6WBtQKzJnT6NmXl29+ILYCxETtyF9K8LwgJyu8sHs2jQnnLujLBqqjIZqDFa8TORtGiwvhtS3UMtagkkg0SkCaaaOjqtZdWrTy7C9Gy9nFZNYEfmurFZmgLRROTB3jRNwmveWvayFJl4TTtub14l+RZJDx2VgjAwqRU8btN/0xnrT9m2kg6LOyW4F9TkauPgAzY3Gu//HQOGW7VDBPq6y83mzP7iNp8Whe14NQSu29i9rBricl0f6RoWin87jRD7AtZx0MxlhNxUF579COCwNHAMhs310nntoSY5U8s13of9Wn2lDcBcg2QmSNOixMMIcBkjHpEQEZAeGzfi8OvJtjoi9TVY0VzrpSbR1dcx8MNjOUeY37H+XlWkdEkd3457zbeOuSlEbjvuDYW7tYHYWipsd4fNllXiMzKW+w6YxL2Kqj0M5B+3ihuEKg7VS3b/XKs+OS7eHGZSImAt9e4tGltEqYzdRHzm4S6pnJytaoPp7+OswEm+JQTi739w4CJeNWxr1t9dot2k9OQw3vZabeI7OTrwBc2IwtUYZ9oPlBVOibMoUwCIVmSPrSgF8nCj9S2RdZgamLNnyg1srQmWnNxtOLMnvTnWedICtoE48rMG2Q+cDrEjy11TCGK3R+LHE+LaqPv96yk3ztsHomOF7XstAvLvUAIH3Z/X5+ePNcDzV7OZkS9xcLkqGqeqR04iHGZZfLw3q4rauZMWLyxb+NkGKfgTtGhe7nq+Z7bGXWxzQh694dJf+59oGCslmfJ44cd8SX3o2JjSZ7Ew7LgQt7fj6z+yif1Bs8SH3QNZN9POsfxJggCwRIhvaPmZR7hsV75+b4jC+wU2LAHik8Nr1pt48NpCxULtKNw6ZPUbJwMVWK7gmZtqa39l7OmIs2PE54vgeZk38XBi6K1UFqoZlV667GrnwOgscob3DFPMcjZhCBYOWJNLjxjqP6pw3zf7OB/ZA1m4F6yv4LVka19rlQk0esAqfTy36KbJggRYNJdGYgDr6u2zz3NblMfZpys5mtpW8ncoBdsOeWlL+cspDGig9HINHT2CnrL9+N7oU='+ client_key: 'test_ECRHWDLSER123456HMT57VW7XGOUDA23'status: initialexpires_at: '2025-07-24T14:40:45.000Z'relationships:diff --git a/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdx b/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdxindex b3c4db067a..bd9db9edc1 100644--- a/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdx+++ b/docs/api-reference/tutorials/adyen-integration-guide-for-android.mdx@@ -8,6 +8,12 @@ This guide is aimed at advanced users who want to create adyen integration for tYou also need to install Spree Adyen extension before.</Warning>+## Note++The list of available library versions can be found on [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)+Current newest version available at the moment of writing the tutorial is 5.13.1.+This doc will be referring to the library version as YOUR_VERSION.+## 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)diff --git a/docs/api-reference/tutorials/adyen-integration-guide-for-ios.mdx b/docs/api-reference/tutorials/adyen-integration-guide-for-ios.mdxnew file mode 100644index 0000000000..e99b67e15b--- /dev/null+++ b/docs/api-reference/tutorials/adyen-integration-guide-for-ios.mdx@@ -0,0 +1,196 @@+---+title: Adyen Integration Guide for iOS+description: This guide provides step-by-step instructions for integrating Adyen iOS 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 iOS application.+You also need to install Spree Adyen extension before.+</Warning>++## Requirements++- Adyen test account+- Set up `spree_adyen` spree extension++### return_url++spree_adyen needs to be configured with `return_url`.++Return url tells where shopper should be redirect after the payment from outside your application (for example klarna or most of others buy now pay later systems).++Use the custom URL for your app, like `my-app://adyen`. Url can contain custom query params however do not include any personally identifiable information (PII) of your customer. Maximum length of the url is 1024 characters.++## Note++The list of available library versions can be found on [Official Adyen Documentation for iOS integration](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS&integration=Drop-in&version=5.13.1)+Current newest version available at the moment of writing the tutorial is 5.19.2.++## Resources++- [Official Adyen Documentation for iOS integration](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS&integration=Drop-in&version=5.19.2)+- Spree Adyen API docs - [create payment_session](/api-reference/storefront/adyen/create-an-adyen-payment-session) and [get payment_session](/api-reference/storefront/adyen/get-adyen-payment-session)+- [Official Adyen example for iOS integration](https://github.com/Adyen/adyen-ios/tree/develop/Demo)+- Apple Developer documentation on [defining custom url scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)++## Overview++The integration consists of two main components:++- **Spree Adyen**: Provides API for your client and receive payment result from Adyen+- **Your iOS client app**: Shows the Drop-in UI and handles payment flow++## Step 1: Install adyen with Swift Package Manager++repository URL:+```+https://github.com/Adyen/adyen-ios+```+use at least version 5.0.0++CocoaPods and Carthage instructions are available [here](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS&integration=Drop-in&version=5.19.2&tab=cocoapods_1_2#1-get-adyen-ios).++## Step 2: Create the context++Create the instance of APIContext that includes client key and environment setting.++```swift+// Set the client key and environment in an instance of APIContext.+let apiContext = APIContext(clientKey: clientKey, environment: Environment.test) // Set the environment to a live one when going live.+// Create the amount with the value in minor units and the currency code.+let amount = Amount(value: 1000, currencyCode: "EUR")+// Create the payment object with the amount and country code.+let payment = Payment(amount: amount, countryCode: "NL")+// Create an instance of AdyenContext, passing the instance of APIContext, and payment object.+let adyenContext = AdyenContext(apiContext: apiContext, payment:payment)+```++`environment` - Environment.test or Environment.live+`clientKey` - `client_key` from payment_sessions endpoint++## Step 3: Create and set up session++Create a session using [payment_session endpoint](/api-reference/storefront/adyen/create-an-adyen-payment-session).+Then set a configuration using data from the response:++```swift+let configuration = AdyenSession.Configuration(sessionIdentifier: sessionId,+ initialSessionData: data)+```++- `data` - available as `adyen_data` in payment_session API response+- `sessionId` - available as `adyen_id` in payment_session API response++With the configuration you initialize AdyenSession:++```swift+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.+ }+ }+```++## Step 4. Configure Drop-in++```swift+let dropInConfiguration = DropInComponent.Configuration()+// Some payment methods have additional required or optional configuration.+// For example, an optional configuration to show the cardholder name field for cards.+dropInConfiguration.card.showsHolderNameField = true+```++## Step 5: Initialize the DropInComponent class++```swift+let dropInComponent = DropInComponent(paymentMethods: session.sessionContext.paymentMethods,+ context: adyenContext,+ configuration: dropInConfiguration)++// Keep the instance of Drop-in to so that it doesn't get destroyed after the function is executed.+self.dropInComponent = dropInComponent++// Set the session as the delegate.+dropInComponent.delegate = session+// If you support gift cards, set the session as the partial payment delegate.+dropInComponent.partialPaymentDelegate = session+```++## Step 6: Show Drop-in in your app++```swift+myCheckoutViewController.present(dropInComponent.viewController, animated: true)+```++If the `action` field is `redirect` you need to handle the redirect result.++## Step 7. Handling the redirect result++If the `action` field returns `redirect` the shopper is completing the payment outside of your application. You need to inform the Drop-in when the shopper returns to your app.++Here an example for a Custom Url scheme:+- implement the following in your `UIApplicationDelegate`:++```swift+func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {+ return RedirectComponent.applicationDidOpen(from: url)+}+```++for Universal URL use this instead:+```swift+func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {+ guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,+ let incomingURL = userActivity.webpageURL else { return false }+ return RedirectComponent.applicationDidOpen(from: incomingURL)+}+```++## Step 8: Show the shopper result of the payment++When the payment flow is finished, your instance of AdyenSession calls the didComplete method.+Implement the following in your Drop-in configuration object.++```swift+func didComplete(with result: AdyenSessionResult, // The session result.+ component: Component, // The Drop-in component.+ session: AdyenSession) // Your instance of AdyenSession.+```++Use the resultCode to inform your shopper about the current payment status.+Possible resultCode values:+- `authorised` - payment authorised+- `refused` - payment refused+- `pending` - payment pending (for payments with asynchronous flow like iDEAL). When the shopper completes the payment webhook will process process the payment.+- `cancelled` - payment canceled+- `received` - some payments needs more time to be processed. When the status is available webhook will process the payment+- `error` - an error occurred when processing the payment. The response contains more details with the error code+ Your instance of AdyenSession calls the didFail method containing the error.+ ```swift+ func didFail(with error: Error, // The error object.+ from component: Component, // The Drop-in component.+ session: AdyenSession) // Your instance of AdyenSession.+ ```++## Step 8: Continue shopping experience++1. Wait for backend to process the payment+2. Continue shopping experience++### 1. Wait for backend to process the payment++backend after receiving webhook 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 filediff --git a/docs/docs.json b/docs/docs.jsonindex e06c894c65..429b4c7a0a 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -196,7 +196,8 @@"group": "Tutorials","pages": ["api-reference/tutorials/quick-checkout-with-stripe",- "api-reference/tutorials/adyen-integration-guide-for-android"+ "api-reference/tutorials/adyen-integration-guide-for-android",+ "api-reference/tutorials/adyen-integration-guide-for-ios"]},{