{"title":"Advanced flow integration guide","category":"default","creationDate":1776961627,"content":"
\n \n <\/in-page-filtering>\n<\/div>\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n <\/div>\n","url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow","articleFields":{"feedback_component":true,"description":"Accept payments using the Advanced flow.","filters_component":true,"filters_config_folder":"advanced-flow-integration","dynamic_minitoc":true,"dynamic_minitoc_context":".in-page-filtering--content","search_tags":["adyen android","adyen ios","adyen web","adyen react native","adyen flutter","adyen sdk"]},"algolia":[{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow","title":"Advanced flow integration guide","content":"Web Drop-in\nRender a list of available payment methods anywhere on your website.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\n\nDemo\nView live demoDrop-in is our pre-built UI solution for accepting payments on your website. Drop-in shows all payment methods as a list, in the same block. This integration requires you to make API requests to \/paymentMethods, \/payments, and \/payments\/details endpoints.\nAdding new payment methods usually doesn't require more development work. Drop-in supports cards, wallets, and most local payment methods.\nIntroducing Web v6\nImprovements\nThe Web v6 library introduces the following improvements:\n\nReduced bundle size through tree shaking\nEnhanced design\nEnhanced Typescript developer experience\nBetter alignment of express payment methods\nAdded support for 6 localizations\nSupport for Apple Pay Order tracking\nImprove AVS checks for Google Pay and Apple Pay\n\nTo upgrade your existing integration, see Upgrade to Adyen Web v6Requirements\n\nCheck out our Node.js + Express tutorialFollow our tutorial to integrate Drop-in with Node.js and Express.\n\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\n\nTo make sure that your 3D Secure integration works on Chrome, your cookies need to have the SameSite attribute. For more information, refer to Chrome SameSite Cookie policy.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\n\nYour client website: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client website.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website\n Go to the integration steps for your client website.\n Webhook server\n Go to the integration steps for your webhook server.\n\nThe parts of your integration work together to complete the payment flow:\n\n \n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nCreate an instance of Drop-in on your payments form.\nFrom your server, submit a payment request with data you receive from Drop-in.\nDetermine from the response if you need to perform additional actions on your client website.\nFrom your server, submit additional payment details with data you receive from Drop-in.\nShow the payment result to the shopper.\n\nWhen you have completed the integration, proceed to test your integration.Install an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a \/paymentMethods request, specifying:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.\n\n\nchannel\n\nThe platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Drop-in configuration.\n\n\n\nThe following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client website. You'll use this in the next step to show which payment methods are available for the shopper.\nCustom list of payment methods\nWhen you make a \/paymentMethods request, the response includes all payment methods that you enabled in your Customer Area that are available for the transaction.\nTo exclude payment methods from the available list of available payment methods for a specific transaction, include one of the following parameters when making your request:\n\n allowedPaymentMethods: Drop-in renders only the payment methods that you specify.\n blockedPaymentMethods: Drop-in doesn't render payment methods that you specify.\nAdd Drop-in to your payments form\n\n \n Client website\n \n\n\nNext, use Drop-in to show the available payment methods, and to collect payment details from your shopper.\nImport using the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:\n\n\n \n \n \n \n\n\n   You can add your own styling by overriding the rules in this CSS file.\nAfter you have imported the Adyen Web library, do the following:\n\n\nCreate a Document Object Model (DOM) element on your checkout page and put it where you want Drop-in to render on the page.\n\n\n\n\nIf you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element.\n\n\n\n\n\n\nCreate a global configuration object with the following parameters and events:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\npaymentMethodsResponse\n\nThe full \/paymentMethods response returned when you get available payment methods.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication. Web Drop-in versions before 3.10.1 use originKey instead. Find out how to migrate from using originKey to clientKey.\n\n\nlocale\n\nThe shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see\u00a0Language and localization.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nenvironment\n\nUse test. When you are ready to accept live payments, change the value to one of our live environments.\u00a0\n\n\nsecondaryAmount\n\nShows the payment amount in an additional currency on the Pay button. You must do the currency conversion and set the amount. This object has properties: currency: The three-character ISO currency code. value: The amount of the transaction, in minor units. currencyDisplay: Sets the currency formatting. Default: symbol. \n\n\nshowPayButton\n\nShows or hides a Pay Button for each payment method. Defaults to true. When set to false, you must override it in \n paymentMethodsConfiguration\n. The Pay button triggers the onSubmit event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to false and call the .submit() method from your own button implementation. PayPal Smart Payment Buttons doesn't support the .submit() method.\n\n\namount\n\nAmount to be displayed on the Pay Button. It expects an object with the value and currency properties. For example, { value: 1000, currency: 'USD' }.\n\n\n\n\n\n\nEvent name\nRequired\nDescription\n\n\n\n\nonSubmit(state, dropin, actions)\n\nCreate an event handler for this event, which is called when the shopper selects the Pay button, and the details are valid. This applies if the showPayButton configuration parameter is set to true. Makes a POST \/payments request. You must call actions.resolve(), passing resultCode, action, and order objects (if available) from the \/payments response, even if the payment is unsuccessful. If the \/payments request from your server fails, or if an unexpected error occurs, call actions.reject().\n\n\nonAdditionalDetails(state, dropin, actions)\n\nCreate an event handler, called when a payment method requires more details, for example for native 3D Secure 2, or native QR code payment methods. Makes a POST \/payments\/details request. If the \/payments\/details request from your server is successful, you must call actions.resolve(), passing resultCode, action, and order objects (if available) from the API response. You must call it even if the payment is unsuccessful. If the \/payments\/details request from your server fails, or if an unexpected error occurs, call actions.reject.\n\n\nonPaymentCompleted(result, component)\n\nCreate an event handler, called when the payment is completed.\n\n\nonPaymentFailed(result, component)\n\nCreate an event handler, called when the payment failed. A failed payment has result code Cancelled, Error or Refused.\n\n\nonError(error)\n\nCreate an event handler, called when an error occurs in Drop-in.\n\n\nonChange(state, dropin)\n\nCreate an event handler, called when the shopper provides the required payment details.\n\n\nonActionHandled\n\nCreate an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following action.type values trigger this callback: threeDS qr await Returns data that contains: componentType: The type of component that shows the action to the shopper. actionDescription: A description of the action shown to the shopper. \n\n\n\n\n\n\n\n\nCreate an instance of AdyenCheckout, passing the global configuration object you created:\n\n\n\n\n\nCreate and mount an instance of Dropin, passing the instance of AdyenCheckout you created. You can add optional Drop-in configuration your instance of Dropin. How you create it depends on if you import resources for all payment methods or individual payment methods.\n\n\n \n \n \n \n\n\nWhen the shopper selects the Pay button, Drop-in calls the onSubmit event, which contains a state.data. These are the shopper details that you need to make the payment.\n\n\nPass the state.data to your server.\n\n\n\n\nOptional Drop-in configuration\nYou can add the following configuration parameters to the Dropin configuration:\n\n\n\nParameter name\nDescription\n\n\n\n\nopenFirstPaymentMethod\nWhen enabled, Drop-in opens the first payment method automatically on page load. Defaults to true.\n\n\nopenFirstStoredPaymentMethod\nWhen enabled, Drop-in opens the payment method with stored card details on page load. This option takes precedence over openFirstPaymentMethod. Defaults to true.\n\n\nopenPaymentMethod.type\nAutomatically selects the specified payment method when Drop-in renders. Set the payment method type that you want to be automatically selected as the value.\n\n\nshowStoredPaymentMethods\nShows or hides payment methods with stored card details. Defaults to true.\n\n\nshowRemovePaymentMethodButton\nAllows the shopper to remove a stored payment method. Defaults to false. If using this prop, you must also implement the onDisableStoredPaymentMethod callback.\n\n\nshowPaymentMethods\nShows or hides regular (not stored) payment methods. Set to false if you only want to show payment methods with stored card details. Defaults to true.\n\n\npaymentMethodsConfiguration\nConfiguration for individual payment methods. The payment method guides have configuration options specific to each payment method. If you include this in the configuration on your instance of DropIn, it overrides global payment method configuration on your instance of AdyenCheckout.\n\n\nredirectFromTopWhenInIframe\nIf your Drop-in is inside of an iframe element, set to true if you want redirects to be performed on the top-level window. We recommend that you do not put Component in an iframe.\n\n\ninstantPaymentTypes\nMoves payment methods to the top of the list of available payment methods. This is available for Apple Pay and Google Pay.\n\n\ndisableFinalAnimation\nWhen enabled, disables the final animation after a shopper completes the payment (whether successful or failed). This lets you implement your own Defaults to false.\n\n\nshowRadioButton\nWhen enabled, payment methods in the Drop-in have a radio button. Defaults to false.\n\n\nEvents\nUse the following events to include additional logic on your checkout page:\n\n\n\nEvent name\nDescription\n\n\n\n\nonReady()\nCalled when Drop-in is initialized and ready for use.\n\n\nonSelect(component)\nCalled when the shopper selects a payment method.\n\n\nonDisableStoredPaymentMethod(storedPaymentMethodId, resolve, reject)\nCalled when a shopper removes a stored payment method. To remove the selected payment method, make a DELETE \/storedPaymentMethod request including the storedPaymentMethodId. Then call either resolve() or reject(), depending on the \/storedPaymentMethods\/{storedPaymentMethodId} response.\n\n\nMethods\nDrop-in supports the following methods:\n\n\n\nMethod name\nDescription\n\n\n\n\nmount(selector)\nMounts the Drop-in into the DOM returned by the selector. The selector must be either a valid CSS selector string or an HTMLElement reference.\n\n\nunmount()\nUnmounts the Drop-in from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.\n\n\ncloseActivePaymentMethod()\nCloses a selected payment method, for example if you want to reset the Drop-in.\n\n\nOptional: Update the payment amount\nIf the amount changes after you mount Drop-in (for example: the shopper adds or removes items from their cart), you can update the payment amount without re-initializing AdyenCheckout.\nFrom your instance of AdyenCheckout, call the update method, passing the new amount.\n\n \nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from onSubmit to your server\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete state.data.paymentMethod object from the onSubmit event from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by Drop-in to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nURL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:\/\/ or https:\/\/. You can also include your own additional query parameters, for example, shopper ID or order reference number. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\nriskData\n\nDevice characteristics and other data that we use to detect fraudulent payment activity, and mitigate fraud.\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\nshopperEmail\n\nThe shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.\n\n\nshopperIP\n\nThe shopper's IP address. Strongly recommended because this field is used in a number of risk checks.\n\n\nshopperReference\n\nYour reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\nUsing the Adyen Uplift Personalize module and accessing the Checkout dashboard.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nTo handle the additional action:\n\n\nPass the action object from your server to the onSubmit actions.resolve() function.\n\n\nDrop-in performs additional actions depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, Drop-in redirects your shopper to another website to complete the payment.\n\n\nWhen the shopper finishes their payment on the other website, they are returned to your returnUrl with an HTTP GET request. The returnUrl is appended with a Base64-encoded redirectResult.\n\n\n\n\nIf the shopper fails to return to your website, you do not get the redirectResult. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nTo process the result:\n\nGet the redirectResult appended to your return URL. You do not need to decode it.\nPass the redirectResult to your server.\n\nSend additional payment details to complete the payment flow.\n\n\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nDrop-in handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\nDrop-in shows the QR code to the shopper.\nThe shopper scans the QR code to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nDrop-in shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nDrop-in shows the voucher to the shopper.\nThe shopper uses the voucher to pay outside of your website.\nYou get the payment outcome.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nDrop-in shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nDrop-in calls onAddtionalDetails or onError, depending on the result of the additional action.\nPass the state.data from onAdditionalDetails or onError to your server.\nSend additional payment details to complete the payment flow.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your website, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass additional payment details to your server, depending on the action you handled:\n\nIf you handled a redirect: pass the redirectResult.\nIf you handled a non-redirect additional action: pass the complete state.data object from the onAdditionalDetails event.\n\n\n\nFrom your server, make a POST \/payments\/details request including the redirectResult or the full state.data object, depending on the action you handled.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website\n \n\n\nUse the \n resultCode\n from the onPaymentCompleted or onPaymentFailed event to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \n\nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\n\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Drop-in from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\nlive\n\n\nUnited States (US) live\nlive-us\n\n\nAustralia (AU) live\nlive-au\n\n\nAsia Pacific & Southeast (APSE) live\nlive-apse\n\n\nIndia (IN) live\nlive-in\n\n\n\n\nSee also\n\n\n Tokenization\n \n 3D Secure\n \n PCI DSS compliance guide\n \n Adyen Uplift requirements and recommendations\n \nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["adyen android","adyen ios","adyen web","adyen react native","adyen flutter","adyen sdk"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Web&integration=Drop-in","title":"Web Drop-in","content":"Web Drop-in\nRender a list of available payment methods anywhere on your website.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\n\nDemo\nView live demoDrop-in is our pre-built UI solution for accepting payments on your website. Drop-in shows all payment methods as a list, in the same block. This integration requires you to make API requests to \/paymentMethods, \/payments, and \/payments\/details endpoints.\nAdding new payment methods usually doesn't require more development work. Drop-in supports cards, wallets, and most local payment methods.\nIntroducing Web v6\nImprovements\nThe Web v6 library introduces the following improvements:\n\nReduced bundle size through tree shaking\nEnhanced design\nEnhanced Typescript developer experience\nBetter alignment of express payment methods\nAdded support for 6 localizations\nSupport for Apple Pay Order tracking\nImprove AVS checks for Google Pay and Apple Pay\n\nTo upgrade your existing integration, see Upgrade to Adyen Web v6Requirements\n\nCheck out our Node.js + Express tutorialFollow our tutorial to integrate Drop-in with Node.js and Express.\n\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\n\nTo make sure that your 3D Secure integration works on Chrome, your cookies need to have the SameSite attribute. For more information, refer to Chrome SameSite Cookie policy.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\n\nYour client website: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client website.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website\n Go to the integration steps for your client website.\n Webhook server\n Go to the integration steps for your webhook server.\n\nThe parts of your integration work together to complete the payment flow:\n\n \n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nCreate an instance of Drop-in on your payments form.\nFrom your server, submit a payment request with data you receive from Drop-in.\nDetermine from the response if you need to perform additional actions on your client website.\nFrom your server, submit additional payment details with data you receive from Drop-in.\nShow the payment result to the shopper.\n\nWhen you have completed the integration, proceed to test your integration.Install an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a \/paymentMethods request, specifying:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.\n\n\nchannel\n\nThe platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Drop-in configuration.\n\n\n\nThe following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client website. You'll use this in the next step to show which payment methods are available for the shopper.\nCustom list of payment methods\nWhen you make a \/paymentMethods request, the response includes all payment methods that you enabled in your Customer Area that are available for the transaction.\nTo exclude payment methods from the available list of available payment methods for a specific transaction, include one of the following parameters when making your request:\n\n allowedPaymentMethods: Drop-in renders only the payment methods that you specify.\n blockedPaymentMethods: Drop-in doesn't render payment methods that you specify.\nAdd Drop-in to your payments form\n\n \n Client website\n \n\n\nNext, use Drop-in to show the available payment methods, and to collect payment details from your shopper.\nImport using the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:\n\n\n \n \n \n \n\n\n   You can add your own styling by overriding the rules in this CSS file.\nAfter you have imported the Adyen Web library, do the following:\n\n\nCreate a Document Object Model (DOM) element on your checkout page and put it where you want Drop-in to render on the page.\n\n\n\n\nIf you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element.\n\n\n\n\n\n\nCreate a global configuration object with the following parameters and events:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\npaymentMethodsResponse\n\nThe full \/paymentMethods response returned when you get available payment methods.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication. Web Drop-in versions before 3.10.1 use originKey instead. Find out how to migrate from using originKey to clientKey.\n\n\nlocale\n\nThe shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see\u00a0Language and localization.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nenvironment\n\nUse test. When you are ready to accept live payments, change the value to one of our live environments.\u00a0\n\n\nsecondaryAmount\n\nShows the payment amount in an additional currency on the Pay button. You must do the currency conversion and set the amount. This object has properties: currency: The three-character ISO currency code. value: The amount of the transaction, in minor units. currencyDisplay: Sets the currency formatting. Default: symbol. \n\n\nshowPayButton\n\nShows or hides a Pay Button for each payment method. Defaults to true. When set to false, you must override it in \n paymentMethodsConfiguration\n. The Pay button triggers the onSubmit event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to false and call the .submit() method from your own button implementation. PayPal Smart Payment Buttons doesn't support the .submit() method.\n\n\namount\n\nAmount to be displayed on the Pay Button. It expects an object with the value and currency properties. For example, { value: 1000, currency: 'USD' }.\n\n\n\n\n\n\nEvent name\nRequired\nDescription\n\n\n\n\nonSubmit(state, dropin, actions)\n\nCreate an event handler for this event, which is called when the shopper selects the Pay button, and the details are valid. This applies if the showPayButton configuration parameter is set to true. Makes a POST \/payments request. You must call actions.resolve(), passing resultCode, action, and order objects (if available) from the \/payments response, even if the payment is unsuccessful. If the \/payments request from your server fails, or if an unexpected error occurs, call actions.reject().\n\n\nonAdditionalDetails(state, dropin, actions)\n\nCreate an event handler, called when a payment method requires more details, for example for native 3D Secure 2, or native QR code payment methods. Makes a POST \/payments\/details request. If the \/payments\/details request from your server is successful, you must call actions.resolve(), passing resultCode, action, and order objects (if available) from the API response. You must call it even if the payment is unsuccessful. If the \/payments\/details request from your server fails, or if an unexpected error occurs, call actions.reject.\n\n\nonPaymentCompleted(result, component)\n\nCreate an event handler, called when the payment is completed.\n\n\nonPaymentFailed(result, component)\n\nCreate an event handler, called when the payment failed. A failed payment has result code Cancelled, Error or Refused.\n\n\nonError(error)\n\nCreate an event handler, called when an error occurs in Drop-in.\n\n\nonChange(state, dropin)\n\nCreate an event handler, called when the shopper provides the required payment details.\n\n\nonActionHandled\n\nCreate an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following action.type values trigger this callback: threeDS qr await Returns data that contains: componentType: The type of component that shows the action to the shopper. actionDescription: A description of the action shown to the shopper. \n\n\n\n\n\n\n\n\nCreate an instance of AdyenCheckout, passing the global configuration object you created:\n\n\n\n\n\nCreate and mount an instance of Dropin, passing the instance of AdyenCheckout you created. You can add optional Drop-in configuration your instance of Dropin. How you create it depends on if you import resources for all payment methods or individual payment methods.\n\n\n \n \n \n \n\n\nWhen the shopper selects the Pay button, Drop-in calls the onSubmit event, which contains a state.data. These are the shopper details that you need to make the payment.\n\n\nPass the state.data to your server.\n\n\n\n\nOptional Drop-in configuration\nYou can add the following configuration parameters to the Dropin configuration:\n\n\n\nParameter name\nDescription\n\n\n\n\nopenFirstPaymentMethod\nWhen enabled, Drop-in opens the first payment method automatically on page load. Defaults to true.\n\n\nopenFirstStoredPaymentMethod\nWhen enabled, Drop-in opens the payment method with stored card details on page load. This option takes precedence over openFirstPaymentMethod. Defaults to true.\n\n\nopenPaymentMethod.type\nAutomatically selects the specified payment method when Drop-in renders. Set the payment method type that you want to be automatically selected as the value.\n\n\nshowStoredPaymentMethods\nShows or hides payment methods with stored card details. Defaults to true.\n\n\nshowRemovePaymentMethodButton\nAllows the shopper to remove a stored payment method. Defaults to false. If using this prop, you must also implement the onDisableStoredPaymentMethod callback.\n\n\nshowPaymentMethods\nShows or hides regular (not stored) payment methods. Set to false if you only want to show payment methods with stored card details. Defaults to true.\n\n\npaymentMethodsConfiguration\nConfiguration for individual payment methods. The payment method guides have configuration options specific to each payment method. If you include this in the configuration on your instance of DropIn, it overrides global payment method configuration on your instance of AdyenCheckout.\n\n\nredirectFromTopWhenInIframe\nIf your Drop-in is inside of an iframe element, set to true if you want redirects to be performed on the top-level window. We recommend that you do not put Component in an iframe.\n\n\ninstantPaymentTypes\nMoves payment methods to the top of the list of available payment methods. This is available for Apple Pay and Google Pay.\n\n\ndisableFinalAnimation\nWhen enabled, disables the final animation after a shopper completes the payment (whether successful or failed). This lets you implement your own Defaults to false.\n\n\nshowRadioButton\nWhen enabled, payment methods in the Drop-in have a radio button. Defaults to false.\n\n\nEvents\nUse the following events to include additional logic on your checkout page:\n\n\n\nEvent name\nDescription\n\n\n\n\nonReady()\nCalled when Drop-in is initialized and ready for use.\n\n\nonSelect(component)\nCalled when the shopper selects a payment method.\n\n\nonDisableStoredPaymentMethod(storedPaymentMethodId, resolve, reject)\nCalled when a shopper removes a stored payment method. To remove the selected payment method, make a DELETE \/storedPaymentMethod request including the storedPaymentMethodId. Then call either resolve() or reject(), depending on the \/storedPaymentMethods\/{storedPaymentMethodId} response.\n\n\nMethods\nDrop-in supports the following methods:\n\n\n\nMethod name\nDescription\n\n\n\n\nmount(selector)\nMounts the Drop-in into the DOM returned by the selector. The selector must be either a valid CSS selector string or an HTMLElement reference.\n\n\nunmount()\nUnmounts the Drop-in from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.\n\n\ncloseActivePaymentMethod()\nCloses a selected payment method, for example if you want to reset the Drop-in.\n\n\nOptional: Update the payment amount\nIf the amount changes after you mount Drop-in (for example: the shopper adds or removes items from their cart), you can update the payment amount without re-initializing AdyenCheckout.\nFrom your instance of AdyenCheckout, call the update method, passing the new amount.\n\n \nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from onSubmit to your server\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete state.data.paymentMethod object from the onSubmit event from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by Drop-in to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nURL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:\/\/ or https:\/\/. You can also include your own additional query parameters, for example, shopper ID or order reference number. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\nriskData\n\nDevice characteristics and other data that we use to detect fraudulent payment activity, and mitigate fraud.\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\nshopperEmail\n\nThe shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.\n\n\nshopperIP\n\nThe shopper's IP address. Strongly recommended because this field is used in a number of risk checks.\n\n\nshopperReference\n\nYour reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\nUsing the Adyen Uplift Personalize module and accessing the Checkout dashboard.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nTo handle the additional action:\n\n\nPass the action object from your server to the onSubmit actions.resolve() function.\n\n\nDrop-in performs additional actions depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, Drop-in redirects your shopper to another website to complete the payment.\n\n\nWhen the shopper finishes their payment on the other website, they are returned to your returnUrl with an HTTP GET request. The returnUrl is appended with a Base64-encoded redirectResult.\n\n\n\n\nIf the shopper fails to return to your website, you do not get the redirectResult. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nTo process the result:\n\nGet the redirectResult appended to your return URL. You do not need to decode it.\nPass the redirectResult to your server.\n\nSend additional payment details to complete the payment flow.\n\n\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nDrop-in handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\nDrop-in shows the QR code to the shopper.\nThe shopper scans the QR code to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nDrop-in shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nDrop-in calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nDrop-in shows the voucher to the shopper.\nThe shopper uses the voucher to pay outside of your website.\nYou get the payment outcome.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nDrop-in shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nDrop-in calls onAddtionalDetails or onError, depending on the result of the additional action.\nPass the state.data from onAdditionalDetails or onError to your server.\nSend additional payment details to complete the payment flow.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your website, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass additional payment details to your server, depending on the action you handled:\n\nIf you handled a redirect: pass the redirectResult.\nIf you handled a non-redirect additional action: pass the complete state.data object from the onAdditionalDetails event.\n\n\n\nFrom your server, make a POST \/payments\/details request including the redirectResult or the full state.data object, depending on the action you handled.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website\n \n\n\nUse the \n resultCode\n from the onPaymentCompleted or onPaymentFailed event to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \n\nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\n\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Drop-in from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\nlive\n\n\nUnited States (US) live\nlive-us\n\n\nAustralia (AU) live\nlive-au\n\n\nAsia Pacific & Southeast (APSE) live\nlive-apse\n\n\nIndia (IN) live\nlive-in\n\n\n\n\nSee also\n\n\n Tokenization\n \n 3D Secure\n \n PCI DSS compliance guide\n \n Adyen Uplift requirements and recommendations\n \nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Web","Drop-in"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Web&integration=Components","title":"Web Components","content":"Web Components\nRender individual payment methods anywhere on your website.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate each payment method component\nUI styling customization for each payment method\nFlexibility to add payment method components with configuration for each\n3D Secure 2 support using the 3D Secure 2 Component\n\nDemo\nView live demoComponents is our pre-built UI solution for accepting payments on your website. Each component renders a payment method which you can place anywhere on your website. This integration requires you to make API requests to \/paymentMethods, \/payments, and \/payments\/details endpoints.\nAdding new payment methods usually doesn't require more development work. Components supports cards, wallets, and most local payment methods.\nIntroducing Web v6\nImprovements\nThe Web v6 library introduces the following improvements:\n\nReduced bundle size through tree shaking\nEnhanced design\nEnhanced Typescript developer experience\nBetter alignment of express payment methods\nAdded support for 6 localizations\nSupport for Apple Pay Order tracking\nImprove AVS checks for Google Pay and Apple Pay\n\nTo upgrade your existing integration, see Upgrade to Adyen Web v6Requirements\n\nCheck out our Node.js + Express tutorialFollow our tutorial to integrate Drop-in with Node.js and Express.\n\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\n\nTo make sure that your 3D Secure integration works on Chrome, your cookies need to have the SameSite attribute. For more information, refer to Chrome SameSite Cookie policy.\nHow it works\nFor a Components integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client website: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client website. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website\n Go to the integration steps for your client website.\n Webhook server\n Go to the integration steps for your webhook server.\n\nThe parts of your integration work together to complete the payment flow:\n\n \n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nAdd the specific payment method Component to your payments form.\nFrom your server, submit a payment request with the data returned by the Component.\nDetermine from the response if you need to perform additional actions on your client website, such as to redirect the shopper.\nFrom your server, submit additional payment details.\nGet the payment outcome.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a \/paymentMethods request, specifying:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.\n\n\nchannel\n\nThe platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Drop-in configuration.\n\n\n\nThe following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client website. You'll use this in the next step to show which payment methods are available for the shopper.\nCustom list of payment methods\nWhen you make a \/paymentMethods request, the response includes all payment methods that you enabled in your Customer Area that are available for the transaction.\nTo exclude payment methods from the available list of available payment methods for a specific transaction, include one of the following parameters when making your request:\n\n allowedPaymentMethods: Drop-in renders only the payment methods that you specify.\n blockedPaymentMethods: Drop-in doesn't render payment methods that you specify.\nAdd Components to your payments form\n\n \n Client website\n \n\n\nNext, use the Component to render the payment method, and collect the required payment details from your shopper.\nImport using the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:\n\n\n \n \n \n \n\n\n   You can add your own styling by overriding the rules in this CSS file.\nAfter you have imported the Adyen Web library, do the following:\n\n\nCreate a DOM element on your checkout page,\u00a0placing it where you want the payment method form to be rendered.\n\n\n\n\nIf you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element.\n\n\n\n Create a configuration object with the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\npaymentMethodsResponse\n\nThe full \/paymentMethods response returned when you get available payment methods.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication.\n\n\nlocale\n\nThe shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see\u00a0Localization.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nenvironment\n\nUse test. When you are ready to accept live payments, change the value to one of our live environments.\u00a0\n\n\nonSubmit(state, component, actions)\n\nCreate an event handler for this event, which is called when the shopper selects the Pay button, and the details are valid. This applies if the showPayButton configuration parameter is set to true. Makes a POST \/payments request. You must call actions.resolve(), passing resultCode, action, and order objects (if available) from the \/payments response, even when the payment is unsuccessful. If the \/payments request from your server fails, or if an unexpected error occurs, call actions.reject().\n\n\nonAdditionalDetails(state, component, actions)\n\nCreate an event handler for this event, used for native 3D Secure 2, and for native QR code payment methods. In the example below, the handler is named handleOnAdditionalDetails. Makes a POST \/payments\/details request.\n\n\nonPaymentCompleted(result, component)\n\nCreate an event handler, called when the payment is completed.\n\n\nonPaymentFailed(result, component)\n\nCreate an event handler, called when the payment failed. A failed payment has result code Cancelled, Error or Refused.\n\n\nonError(error)\n\nCreate an event handler, called when an error occurs in the Component.\n\n\nonChange(state, component)\n\nCreate an event handler, called when the shopper provides the required payment details.\n\n\nsecondaryAmount\n\nShows the payment amount in an additional currency on the Pay button. You must do the currency conversion and set the amount. This object has properties: currency: The three-character ISO currency code. value: The amount of the transaction, in minor units. currencyDisplay: Sets the currency formatting. Default: symbol. \n\n\nshowPayButton\n\nShows or hides a Pay Button for each payment method. Defaults to true. When set to false, you must override it in \n paymentMethodsConfiguration\n. The Pay button triggers the onSubmit event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to false and call the .submit() method from your own button implementation. PayPal Smart Payment Buttons doesn't support the .submit() method.\n\n\namount\n\nThe currency and value of the transaction.\n\n\nonActionHandled\n\nCreate an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following action.type values trigger this callback: threeDS qr await Returns data that contains: componentType: The type of component that shows the action to the shopper. actionDescription: A description of the action shown to the shopper. \n\n\n\n\n\n\n\n\nUse the configuration object to create an instance of AdyenCheckout.\n\n\n\n\n\nCreate and mount an instance of the payment method Component. \n\nSome payment method Components require additional configuration. For more information, refer to our payment method integration guides.\n\nFor example, to mount the Card Component using its component name, card:\n\n\n\nYou can also include optional Card Component configuration.\nWhen the shopper enters the payment details and selects the Pay button, the Component calls the onSubmit event. If state.isValid is true, use the data in state.data to make the payment.\n\n\nPass the state.data to your server.\n\n\n\n\nMethods\nAll Components support the following methods:\n\n\n\nMethod name\nDescription\n\n\n\n\nmount(selector)\nMounts the Component into the DOM returned by the selector. The selector must be either a valid CSS selector string or an HTMLElement reference.\n\n\nunmount()\nUnmounts the Component from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.\n\n\nOptional: Update the payment amount\nIf the amount changes after you mount the Component (for example: the shopper adds or removes items from their cart), you can update the payment amount without re-initializing AdyenCheckout.\nFrom your instance of AdyenCheckout, call the update method, passing the new amount.\n\n \nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from onSubmit to your server\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete state.data.paymentMethod object from the onSubmit event from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nURL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:\/\/ or https:\/\/. You can also include your own additional query parameters, for example, shopper ID or order reference number. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\nriskData\n\nDevice characteristics and other data that we use to detect fraudulent payment activity, and mitigate fraud.\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\nshopperEmail\n\nThe shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.\n\n\nshopperIP\n\nThe shopper's IP address. Strongly recommended because this field is used in a number of risk checks.\n\n\nshopperReference\n\nYour reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\nUsing the Adyen Uplift Personalize module and accessing the Checkout dashboard.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nTo handle the additional action:\n\nPass the action object from your server to the onSubmit actions.resolve() function.\nThe Component performs the additional action on the client side.\n\nYou handle the payment data, depending on the action type (action.type).\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, the Component redirects your shopper to another website to complete the payment.\n\n\nWhen the shopper finishes their payment on the other website, they are returned to your returnUrl with an HTTP GET request. The returnUrl is appended with a Base64-encoded redirectResult.\n\n\n\n\nIf the shopper fails to return to your website, you do not get the redirectResult. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nTo process the result:\n\nGet the redirectResult appended to your return URL. You do not need to decode it.\nPass the redirectResult to your server.\n\nSend additional payment details to complete the payment flow.\n\n\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nThe Component handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nThe Component calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\nThe Component shows the QR code to the shopper.\nThe shopper scans the QR code to complete the payment.\nThe Component calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nThe Component shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nThe Component calls onAddtionalDetails.\nPass the state.data from onAdditionalDetails to your server.\nSend additional payment details to complete the payment flow.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nThe Component shows the voucher to the shopper.\nThe shopper uses the voucher to pay outside of your website.\nYou get the payment outcome.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nThe Component shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nThe Component calls onAddtionalDetails or onError, depending on the result of the additional action.\nPass the state.data from onAdditionalDetails or onError to your server.\nSend additional payment details to complete the payment flow.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your website, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass additional payment details to your server, depending on the action you handled:\n\nIf you handled a redirect: pass the redirectResult.\nIf you handled a non-redirect additional action: pass the complete state.data object from the onAdditionalDetails event.\n\n\n\nFrom your server, make a POST \/payments\/details request including the redirectResult or the full state.data object, depending on the action you handled.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website\n \n\n\nUse the resultCode from the onPaymentCompleted or onPaymentFailed event to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \n\nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\n\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Components from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\nlive\n\n\nUnited States (US) live\nlive-us\n\n\nAustralia (AU) live\nlive-au\n\n\nAsia Pacific & Southeast (APSE) live\nlive-apse\n\n\nIndia (IN) live\nlive-in\n\n\n\n\nSee also\n\n\n Tokenization\n \n 3D Secure\n \n PCI DSS compliance guide\n \n Adyen Uplift requirements and recommendations\n \nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Web","Components"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Web&integration=API only","title":"Web API only","content":"API only\nCreate your own client-side UI and use our API endpoints to get the list of available payment methods and submit a payment.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nFull control of styling on your checkout page\nYour own UI elements\nCreating your own client-side logic\n\nHandling secure card data and authentication\nYou must ensure that your integration complies with regulatory requirements such as PCI DSS and PSD2 SCA.\nWe recommend that you use our pre-built client-side solutions to securely do the following:\n\nCollect, validate, and encrypt card details: Implement our solution to handle encrypted card data with your custom UI and comply with PCI DSS regulations.\nAuthenticate transactions with 3D Secure 2: Handle the 3D Secure 2 authentication action using our solution and comply with PSD2 SCA regulations for online payments.\nWith an API-only integration, you create your own UI, implement your own client-side logic, and use our API to send and receive payment data. You have full control over the look and feel of your checkout page.\nTo reduce your development time and resources, you can use one of our pre-built UI options (Drop-in\/Components) instead.Requirements\nBefore you build your integration, take into account the following requirements and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that you have the following role: Checkout webservice role\n\n\nCustomer Area roles\nMake sure that you have one of the following roles: Merchant admin role Manage API credentials\n\n\nWebhooks\nSubscribe to the following webhook: Standard webhooks\n\n\nLimitations\nYour PCI compliance assesment determines your integration options for card payments.For 3D Secure 2 authentication for shoppers using Chrome, your cookies must use the SameSite attribute. \n\n\nSetup steps\nBefore you begin: Create your Adyen test accountGet your API key.Get your client key.Set up webhooks.If you want to process payments using raw card data, contact your Adyen Account Manager to confirm that you are eligible.\n\n\nHow it works\nFor an API-only integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\nYour client: shows your custom UI where the shopper makes the payment. Passes data to and receives data from your payment server to handle the payment flow and additional actions on your client.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIntegration steps\nThe parts of your integration work together to handle the payment flow:\n\nFrom your server, make an API request to get a list of payment methods available to the shopper.\nShow the payment form to collect the shopper's payment details in your UI.\nFrom your server, make a payment request with the data that you have collected from the shopper.\nFor some payment methods, you use your client to handle the additional action that your shopper must do. For example, you redirect your shopper to another website or show a QR code that the shopper uses to complete the payment.\nFrom your server, send additional payment details.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website or app\n Go to the integration steps for your client.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper goes to your checkout page, get a list of the available payment methods to show the shopper.\n\n\nFrom your server, make a\u00a0POST \/paymentMethods request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nchannel\n\nWeb\n\n\ncountryCode\n\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. This is used to translate the payment methods names in the response. Default value: en-US.\n\n\n\nThe information that you include is used to filter the list of available payment methods.\n\n\n\nThe response includes the list of available payment methods, in the paymentMethods object. The payment methods are ordered by popularity in the shopper's country. For each payment method, the response contains:\n\n\n\nParameter name\nDescription\n\n\n\n\nname\nThe name of the payment method that you can show in your payment form.\n\n\ntype\nThe unique payment method code. You must include this when you make a payment.\n\n\n\n\n\n\n\n\nPass the list of available payment methods and the required input fields for each payment method to your client.\n\nBuild your payment form\n\n \n Client website or app\n \n\n\nCreate your payment form where the shopper enters their information. We recommend that you collect commonly-used shopper information in your payment form to process a transactions, depending on your type of business.\n\nSome payment methods require you to collect, or optionally accept, additional information that you include in the payment request. For the additional information you must collect in your payment form for an individual payment method, go to our API-only guide for the individual payment method.\nWe provide payment method and issuer logos that you can download and use in your payment form.\nCredit and debit card details\nBecause governing bodies and organizations regulate the handling of credit and debit card information strictly, you must make sure that you are compliant when collecting card details. When a shopper selects to pay with a card, use the integration option that corresponds to your level of PCI compliance:\n\n(Recommended) Adyen's Custom Card Component with encryption: our pre-built UI with logic to securely encrypt and handle payment card data.\nYour own UI and logic to collect and handle raw card data: before you build an integration that collects raw credit and debit card data, you must assess your PCI compliance according to the most extensive self-assessment form and contact your Adyen Account Manager to confirm that you are eligible.\n\nInformation in the payment form\nAfter collecting information in your payment form, you must add it to corresponding API parameters that you include in the payment request.\nFor example, for commonly-used information:\n\n\n\nField in the payment form\nAPI request parameter\n\n\n\n\nFirst name\nshopperName.firstName\n\n\nLast name\nshopperName.lastName\n\n\nEmail address\nshopperEmail\n\n\nBilling address (multiple fields)\nbillingAddress (object)\n\n\nShipping address (multiple fields)\ndeliveryAddress (object)\n\n\nPhone number\ntelephoneNumber\n\n\n\n \n \n \n \n \n Downloading logos\n \n \n \n \nIf you are building your own UI, we provide payment method and issuing bank logos that you can use on your checkout page. The images are available in PNG format with different sizes and screen resolutions and in SVG format.\nIf you cannot find a payment method or issuer logo, contact our Support Team.\nPayment method logos\nDownload the images from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type returned in the \/paymentMethods response. For example, googlepay or primeiropay_boleto.\nFor cards, the values you should use are specified under brands with type: scheme. For example, mc, visa, and amex. To get a generic card logo, set pm-type to card.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/mc.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/large\/googlepay@2x.png\nIssuing bank logos\nSome payment methods such as iDEAL present a list of issuing banks to the shopper.\nDownload the issuing bank logos from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type in objects with details.key issuer returned in the \/paymentMethods response. For example, ideal.\n\n\nissuerid: The details.items.id referring to the issuing bank. For example, 1121 and 1151 for iDEAL.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/ideal\/1121.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/small\/ideal\/1151-xxhdpi.png\n\n \n \n\nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from your client to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod.type\n\nThe payment method type. From the \/paymentMethods response, this is the value in paymentMethod.type.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. Format: Include the protocol: http:\/\/ or https:\/\/.Maximum 1024 characters.If it includes non-ASCII characters, such as spaces or special letters, URL encode it.You can include your own additional query parameters, such as a shopper ID or order reference number. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are a technology partner, service partner, or system integrator, send information about the application, so that we can offer you more support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website or app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nHow you handle the action depends on the action type (action.type):\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, redirect the shopper to another site to complete the payment.\nHow you handle the redirect depends on if it is a payment method redirect or a 3D Secure 2 redirect.\n\n\n \n \n \n \n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2Fingerprint or threeDS2Challenge, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow. Use one of our 3D Secure 2 solutions to handle the action.\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.qrCodeData\nContains the URL for the QR code.\n\n\n\n\n\nGet the qrCodeData from the action object. This parameter contains a URL for the QR code.\n\n\nShow the QR code to the shopper.\n\n\nThe shopper scans the QR code.\n\n\nSend additional payment details to finish the payment flow.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\n \n\n\n\nFrom the \/payments response, get the following from the action object:\n\n\n\nParameter\nDescription\n\n\n\n\nsdkData\nThe data that you must pass to the SDK.\n\n\n\n\n\nPass the data from the sdkData object to the SDK.\n\n\nThe shopper uses the SDK to finish the payment.\n\n\nGet the result from the SDK.\n\n\nSend additional payment details to finish the payment flow.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n \n\n\n\nThe data included in the \/payments response is different for each voucher payment method. Get the available information from it. For example, for DOKU vouchers, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\nexpiresAt\nThe date when the voucher expires.\n\n\ninitialAmount\nThe payment amount and currency.\n\n\nmerchantName\nThe name of your shop.\n\n\ninstructionsUrl\nThe URL where you shopper can get additional information and instructions about how to pay.\n\n\n\n\n\nShow voucher information to the shopper that your shopper uses to pay outside of your client.\n\n\nSend additional payment details to finish the payment flow.\n\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.paymentData\nAdditional payment data.\n\n\n\n\n\nThe shopper finishes the additional action for the payment.\n\n\nSend additional payment details to finish the payment flow.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your client, you do not get additional payment details to send. Instead, wait for the corresponding webhook message for the outcome of the payment.\n\nFrom your server, make a POST \/payments\/details request. The parameters that you must include depends on the payment method. For the parameters for an individual payment method, go to the API-only page for the individual payment method .\n\n \n\nThe response includes information about the current payment status.\n\n \n\n\n \nGet the payment outcome\nAfter the shopper finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website or app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account.\nAssess your PCI DSS compliance by submitting:\n\nthe Self-Assessment Questionnaire-A, if you are using the Custom Card Component.\nthe Self-Assessment Questionnaire-D, if you are submitting raw card data.\n\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.requiredAdd payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Web","API only"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=iOS&integration=Drop-in","title":"iOS Drop-in","content":"iOS Drop-in\nRender a list of available payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLowest development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\nDrop-in is our pre-built UI solution for accepting payments in your app. Drop-in shows all payment methods as a list, in the same block. For the Advanced flow, your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.Requirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\nInstall the Adyen iOS client-side library\nChoose how you want to install the Adyen iOS client-side library:\n\n\n \n \n \n \n\n\nGet your client key\nYou need a client key, a public key linked to your API credential, that the iOS Drop-in uses for client-side authentication.\n\nLog in to your Customer Area.\nGo to Developers > API credentials, and select the API credential for your integration, for example ws@Company.[YourCompanyAccount].\nUnder Authentication, select Generate New Client Key.\nSelect Save.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\n \n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nCreate an instance of Drop-in.\nFrom your server, submit a payment request with the data returned by Drop-in.\nDetermine from the response if you need to perform additional actions on your client app.\nFrom your server, submit additional payment details with the data returned by Drop-in.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\nPayment serverGo to the integration steps for your server.\n Payment server\n Client appGo to the integration steps for your client app.\n Client\n Webhook serverGo to the integration steps for your webhook server.\n Webhook server\n \nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. Use iOS. Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same ShopperLocale within your Drop-in configuration.\n\n\n\nThe following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. You will use this in the next step to present which payment methods are available to the shopper.Add Drop-in to your payment form\n\n \n Client app\n \n\n\nNext, use Drop-in to show the available payment methods and to collect payment details from your shopper.\n\n\nDecode the \/paymentMethods response with the PaymentMethods structure.\n\n\n\n\n\n\nCreate an instance of APIContext that contains to following:\n\n\n\n\nDescription\n\n\n\n\nClient key\nAuthenticates requests from your payment environment.\n\n\nEnvironment setting\nThe environment value that matches the endpoint that your server uses. Use Environment.test for your test environment.\n\n\n\n\n\n\n\n\nCreate an instance of AdyenContext that contains the following: \n\n\n\n\nDescription\n\n\n\n\nAPI context\nYour instance of APIContext.\n\n\nPayment information\nA Payment object with the payment amount and currency.\n\n\n\n\n\n\n\n\n\nCreate a Drop-in configuration object (DropInComponent.Configuration). You can add the following: \n\n\n\nType of configuration\nDescription\n\n\n\n\nPayment method configuration\nSome payment methods require additional configuration or have optional configuration.\n\n\nOptional configuration\nYou can add optional configuration for Drop-in.\n\n\n\nThe following example shows an optional configuration for cards.\n\n\n\n\n\n\nInitialize Drop-in (\n DropInComponent\n). \n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\npaymentMethods\n\nThe full, decoded \/paymentMethods response.\n\n\ncontext\n\nThe AdyenContext that you created.\n\n\npaymentMethodsConfiguration\nFor some payment methods.\nConfiguration for specific payment methods.\n\n\n\n\n\n\n\n\n\nAfter the shopper selects a payment method and provides payment details, Drop-in invokes the didSubmit method. Get the contents of data.paymentMethod and pass this to your server.\nfunc didSubmit(_ data: PaymentComponentData, for paymentMethod: PaymentMethod, from component: DropInComponent)\nIf an error occurs on the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\nfunc didFail(with error: Error, from component: DropInComponent)\nIf the shopper decides not to continue with the selected payment method, Drop-in invokes the didCancel method. You can use didCancel to track the state of the payment.\nfunc didCancel(component: PaymentComponent, from dropInComponent: DropInComponent)\n\n\n\nFor more information on iOS Drop-in classes, see our reference documentation page.\nMake a payment\n\n \n Payment server\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the full data from didSubmit to your server.\n\n\nFrom your server, make a POST \/payments request including the following:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0of the payment and\u00a0its value\u00a0in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete data.paymentMethod object from the didSubmit method from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by Drop-in to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nThe URL the shopper should be taken back to after a redirection. Use the custom URL for your app, for example, my-app:\/\/adyen, to take the shopper back to your app after they complete the payment outside of your app. For more information on setting a custom URL scheme, read the Apple Developer documentation. The URL can contain a maximum of 1024 characters. You can also include your own additional query parameters, for example, shopper ID or order reference number.\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\nTo handle the action:\n\n\nPass the full action object from your server to your client app.\n\n\nCall \n dropInComponent.handle(action)\n to trigger Drop-in to handle the additional action.\n\n\n\n\n\nDrop-in performs the additional action in your app.\n\n\nYou handle the payment data, depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\n\nWhen the \/payments response includes action.type redirect, Drop-in redirects your shopper to another website to complete the payment.\n\n\nWhen the shopper returns to your app, inform Drop-in. To do this, implement the following in your UIApplicationDelegate:\nfunc application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {\nRedirectComponent.applicationDidOpen(from: url)\nreturn true\n}\n\n\nAfter Drop-in completes the additional action, Drop-in invokes the didProvide method.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss Drop-in immediately or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\n\nDrop-in handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\n\n\nAfter Drop-in completes the additional action, it invokes the didProvide method.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss dropInComponent now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the UI for QR code payment.\n\n\nDrop-in polls the payment status and, if completed, calls the didProvide method.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss dropInComponent now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use the payment method's app to complete the payment.\n\n\nAdyenActionComponent triggers the app switch from your app to the payment method's app, if installed in the shopper's device.\n\n\nWhen the shopper returns to your app, Drop-in invokes the didProvide method.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss dropInComponent now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the UI for the voucher.\n\n\nThe shopper shares, saves the voucher as an image or, in some cases, adds the voucher to Apple Wallet.\n\n\nWhen the shopper completes the flow, Drop-in invokes the didComplete method.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nDismiss dropInComponent. The payment flow in your app is complete.\n\n\n\nAfter the shopper pays, or the voucher expires, your webhook server gets the webhook to update the payment status.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the await UI. The shopper continues payment process outside of your app.\n\n\nDrop-in polls the payment status and, if completed, calls the didProvide the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, Drop-in invokes the didFail method. Dismiss Drop-in's view controller and display an error message.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss dropInComponent now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your app, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass the full data object from the didProvide method to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nDismiss Drop-in\n\n \n Client app\n \n\n\nAfter you make a \/payments request to submit the payment data or a \/payments\/details request to send additional details, dismiss Drop-in to finalize the payment flow.\nCall finalizeIfNeeded and do the following, depending on what the Drop-in handled:\n\n\n\n\nWhat to do\n\n\n\n\nResult code\nIf no further steps are required from the application, dismiss Drop-in.\n\n\nError\nDismiss Drop-in, and show an error message.\n\n\n\nImplement the following in your dropInComponent object:\n\n \nGet the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore 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.\nYou can check the status of a test payment in your Customer Area, under Transactions > Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. \u00a0\nAssess your PCI DSS compliance, and submit the Self-Assessment Questionnaire-A.\nConfigure your live account.\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Drop-in from one of our live environments and set the \n dropInComponent.environment\n to match your live endpoints:\n\n\n\nEndpoint region\nenvironment value\n\n\n\n\nEurope\nliveEurope\n\n\nAustralia\nliveAustralia\n\n\nUS\nliveUnitedStates\n\n\nAsia Pacific and South East\nliveApse\n\n\n\n\nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nOptional configuration\n\n \n Client app\n \n\n\nYou can set additional configuration on the Drop-in configuration.\n\n\n\nParameter name\nDescription\n\n\n\n\nshopperInformation\nPrefilled shopper information.\n\n\nlocalizationParameters\nLocalization parameters, like custom placeholders in other languages.\n\n\nstyle\nCustom styling of the UI.\n\n\nLocalization\niOS Drop-in supports the languages listed here.\nTo customize a localization, add a new localizable.strings file for the language that you need. You can also override existing strings by using the same keys.\nFor example, to override the cardholder name field title, set the following on your localizable.strings file:\n\"adyen.card.nameItem.title\" = \"Your cardholder name\";\nTo find localized strings, the library first checks your custom localizable.strings file, and then the default Adyen file.\nYou can use LocalizationParameters to customize the localization file name, bundle, or the separator for translation strings.\nFor example, if you store translations in MyLocalizable.strings files in the shared bundle CommonBundle:\nlet localizationParameters = LocalizationParameters(bundle: commonBundle, tableName: \"MyLocalizable\")\ndropInComponent.localizationParameters = localizationParameters\nSee also\n\n\n Adyen iOS Reference\n \n Adyen iOS on GitHub\n \n Tokenization\n \nNext steps\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.Add payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["iOS","Drop-in"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=iOS&integration=Components","title":"iOS Components","content":"iOS Components\nRender individual payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate each payment method component\nUI styling customization for each payment method\nFlexibility to add payment method components with configuration for each\n3D Secure 2 support using the 3D Secure 2 Component\nComponents are our pre-built UI solution for accepting payments in your app. Each Component renders a payment method you can render anywhere in your app. For the Advanced flow, your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.Requirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\nInstall the Adyen iOS client-side library\nChoose how you want to install the Adyen iOS client-side library:\n\n\n \n \n \n \n\n\nGet your client key\nYou need a client key, a public key linked to your API credential, that the iOS Components use for client-side authentication.\n\nLog in to your Customer Area.\nGo to Developers > API credentials, and select the API credential for your integration, for example ws@Company.[YourCompanyAccount].\nUnder Authentication, select Generate New Client Key.\nSelect Save.\nHow it works\nFor a Components integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nAdd Components to your payments form.\nFrom your server, submit a payment request with the data returned by the Component.\nDetermine from the response if you need to perform additional actions on your client app, such as to redirect the shopper.\nFrom your server, verify the payment result.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. Use iOS. Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. By default, the shopper locale is set to en-US. If this is provided, the payment method names are translated to the specified language.\n\n\n\nThe following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. You then use this in the next step to present which payment methods are available to the shopper.Add Components to your payment form\n\n \n Client app\n \n\n\nUse the Component to collect payment details from your shopper.\n\n\nDecode the \/paymentMethods response with the PaymentMethods structure. Find the payment method object for the Component that you want to instantiate. For example, for a card payment, you need to find the CardPaymentMethod object.\n\n\n\nGet the payment method from the payment methods object. For example, the card payment method:\n\n\n\n\n\n\n\n\nCreate an instance of APIContext that contains to following:\n\n\n\n\nDescription\n\n\n\n\nClient key\nAuthenticates requests from your payment environment.\n\n\nEnvironment setting\nThe environment value that matches the endpoint that your server uses. Use Environment.test for your test environment.\n\n\n\n\n\n\n\n\n\n\n\nCreate an instance of AdyenContext that contains the following: \n\n\n\n\nDescription\n\n\n\n\nAPI context\nYour instance of APIContext.\n\n\nPayment information\nA Payment object with the payment amount and currency.\n\n\n\n\n\n\n\n\n\n\n\nCreate a configuration object. You can add the following: \n\n\n\nType of configuration\nDescription\n\n\n\n\nPayment method configuration\nSome payment methods require additional configuration or have optional configuration.\n\n\nOptional configuration\nYou can add optional configuration to each component.\n\n\n\nThe following example shows creating a configuration object for the Card Component.\n\n\n\n\n\n\n\n\nInitialize the Component class. \n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\npaymentMethod\n\nThe full, decoded \/paymentMethods response.\n\n\ncontext\n\nThe AdyenContext that you created.\n\n\nconfiguration\n\nThe configuration object that you created.\n\n\n\nThe following example shows initializing an instance of \n CardComponent\n.\n\n\n\n\n\n\nGet the contents of data.paymentMethod and pass this to your server. Dismiss the Component immediately, or wait until you have submitted the details to your server.\n\n\n\nIn case an error occurs on the app, the Component invokes the didFail method from the PaymentComponentDelegate. Dismiss the Component's view controller and display an error message.\n\n\n\n\nMake a payment\n\n \n Payment server\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the full data from didSubmit to your server.\n\n\nFrom your server, make a POST \/payments request including the following:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0of the payment and\u00a0its value\u00a0in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete data.paymentMethod object from the didSubmit method from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nThe URL the shopper should be taken back to after a redirection. Use the custom URL for your app, for example, my-app:\/\/adyen, to take the shopper back to your app after they complete the payment outside of your app. For more information on setting a custom URL scheme, read the Apple Developer documentation. The URL can contain a maximum of 1024 characters. You can also include your own additional query parameters, for example, shopper ID or order reference number.\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\nUse \n AdyenActionComponent\n and the action object from the API response to handle the action.\n\n\nPass the full action object from your server to your client app.\n\n\nCreate and persist instance of AdyenActionComponent.\n\n\n\n\n\nUse it to handle the action.\n\n\n\n\n\nAdyenActionComponent performs the additional action in your app.\n\n\nYou handle the payment data, depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\n\nWhen the \/payments response includes action.type redirect, the Component redirects your shopper to another website to complete the payment.\n\n\nWhen the shopper returns to your app, inform AdyenActionComponent. To do this, implement the following in your UIApplicationDelegate:\nfunc application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {\nRedirectComponent.applicationDidOpen(from: url)\nreturn true\n}\n\n\nAfter the Redirect Component (under the hood of AdyenActionComponent) completes the additional action, the Component invokes the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss the Component immediately or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\n\nThe Component handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\n\n\nAfter the Component completes the additional action, it invokes the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss current component now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the UI for QR code payment.\n\n\nThe Component polls the payment status and, if completed, calls the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss current component now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use the payment method's app to complete the payment.\n\n\nAdyenActionComponent triggers the app switch from your app to the payment method's app, if installed in the shopper's device.\n\n\nWhen the shopper returns to your app, the Component invokes the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss current component now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the UI for the voucher.\n\n\nThe shopper shares, saves the voucher as an image or, in some cases, adds the voucher to Apple Wallet.\n\n\nWhen the shopper completes the flow, the Component invokes the didComplete method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nDismiss current component. The payment flow in your app is complete.\n\n\n\nAfter the shopper pays, or the voucher expires, your webhook server gets the webhook to update the payment status.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment.\n\n\nAdyenActionComponent uses presentationDelegate to show the await UI. The shopper continues payment process outside of your app.\n\n\nThe Component polls the payment status and, if completed, calls the didProvide the didProvide method from the ActionComponentDelegate.\n\n\n\nIf an error occurs in the app, the Component invokes the didFail method from the ActionComponentDelegate. Dismiss the Component's view controller and show an error message in your app.\n\n\n\n\n\nGet the data from the didProvide method.\n\n\nDismiss current component now or after the following step.\n\n\nPass the contents of data to your server.\n\n\nSend additional payment details.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your app, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass the full data object from the didProvide method to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nDismiss the Component\n\n \n Client app\n \n\n\nAfter you make a \/payments request to submit the payment data or a \/payments\/details request to send additional details, dismiss the Component to finalize the payment flow.\nCall finalizeIfNeeded and do the following, depending on what the Component handled:\n\n\n\n\nWhat to do\n\n\n\n\nResult code\nIf no further steps are required from the application, dismiss the Component.\n\n\nError\nDismiss the Component, and show an error message.\n\n\n\nImplement the following in your currentComponent object:\n\n \nGet the payment outcome\nAfter the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the resultCode to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore 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.\nYou can check the status of a test payment in your Customer Area, under Transactions > Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. \u00a0\nAssess your PCI DSS compliance, and submit the Self-Assessment Questionnaire-A.\nConfigure your live account.\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad the Components from one of our live environments and set the Component's \n environment\n to match your live endpoints:\n\n\n\nEndpoint region\nenvironment value\n\n\n\n\nEurope\nliveEurope\n\n\nAustralia\nliveAustralia\n\n\nUS\nliveUnitedStates\n\n\nAsia Pacific and South East\nliveApse\n\n\n\n\nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nOptional configuration\n\n \n Client app\n \n\n\nYou can set additional configuration on the Component configuration.\n\n\n\nParameter name\nDescription\n\n\n\n\nshowsSubmitButton\nSet to false to hide the default pay button, so that you can implement a custom button instead. Default: true.\n\n\nshopperInformation\nPrefilled shopper information.\n\n\nlocalizationParameters\nLocalization parameters, like custom placeholders in other languages.\n\n\nstyle\nCustom styling of the UI.\n\n\n\nThe following example shows how to set optional configuration parameters on the Card Component.\n\n \n\nImplement a custom pay button\nTo implement a custom pay button, hide the default one and use the included functions to validate and submit payment data.\n\nThis is not supported for Apple Pay and BACS Direct Debit.\n\n\nWhen you create the configuration object, set showsSubmitButton to false. \nInitialize the Component.\nYou can optionally show a confirmation page to the shopper, where payment data is validated.\nCreate and show your custom button.\n\nYou can use the following functions.\n\n\n\nFunction\nRequired\nDescription\n\n\n\n\nvalidate()\n\nValidates the payment data.\n\n\nsubmit()\n\nMakes a \/payments request to submit the payment data.\n\n\n\nThe following example shows the Card Component with a custom pay button.\n\n \nLocalization\niOS Components support the languages listed here.\nTo customize a localization, add a new localizable.strings file for the language that you need. You can also override existing strings by using the same keys.\nFor example, to override the cardholder name field title, set the following on your localizable.strings file:\n\"adyen.card.nameItem.title\" = \"Your cardholder name\";\n\nFor more information on iOS Components classes, see our reference documentation page.\n\nTo find localized strings, the library first checks your custom localizable.strings file, and then the default Adyen file.\nYou can use LocalizationParameters to customize the localization file name, bundle, or the separator for translation strings.\nFor example, if you store translations in MyLocalizable.strings files in the shared bundle CommonBundle:\nlet localizationParameters = LocalizationParameters(bundle: commonBundle, tableName: \"MyLocalizable\")\ncardComponentConfiguration.localizationParameters = localizationParameters\nSee also\n\n\n Adyen iOS Reference\n \n Adyen iOS on GitHub\n \n Tokenization\n \nNext steps\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.Add payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["iOS","Components"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=iOS&integration=API only","title":"iOS API only","content":"API only\nCreate your own client-side UI and use our API endpoints to get the list of available payment methods and submit a payment.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nFull control of styling on your checkout page\nYour own UI elements\nCreating your own client-side logic\n\nHandling secure card data and authentication\nYou must ensure that your integration complies with regulatory requirements such as PCI DSS and PSD2 SCA.\nWe recommend that you use our pre-built client-side solutions to securely do the following:\n\nCollect, validate, and encrypt card details: Implement our solution to handle encrypted card data with your custom UI and comply with PCI DSS regulations.\nAuthenticate transactions with 3D Secure 2: Handle the 3D Secure 2 authentication action using our solution and comply with PSD2 SCA regulations for online payments.\nWith an API-only integration, you create your own UI, implement your own client-side logic, and use our API to send and receive payment data. You have full control over the look and feel of your checkout page.\nTo reduce your development time and resources, you can use one of our pre-built UI options (Drop-in\/Components) instead.Requirements\nBefore you build your integration, take into account the following requirements and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that you have the following role: Checkout webservice role\n\n\nCustomer Area roles\nMake sure that you have one of the following roles: Merchant admin role Manage API credentials\n\n\nWebhooks\nSubscribe to the following webhook: Standard webhooks\n\n\nLimitations\nYour PCI compliance assesment determines your integration options for card payments.For 3D Secure 2 authentication for shoppers using Chrome, your cookies must use the SameSite attribute. \n\n\nSetup steps\nBefore you begin: Create your Adyen test accountGet your API key.Get your client key.Set up webhooks.If you want to process payments using raw card data, contact your Adyen Account Manager to confirm that you are eligible.\n\n\nHow it works\nFor an API-only integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\nYour client: shows your custom UI where the shopper makes the payment. Passes data to and receives data from your payment server to handle the payment flow and additional actions on your client.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIntegration steps\nThe parts of your integration work together to handle the payment flow:\n\nFrom your server, make an API request to get a list of payment methods available to the shopper.\nShow the payment form to collect the shopper's payment details in your UI.\nFrom your server, make a payment request with the data that you have collected from the shopper.\nFor some payment methods, you use your client to handle the additional action that your shopper must do. For example, you redirect your shopper to another website or show a QR code that the shopper uses to complete the payment.\nFrom your server, send additional payment details.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website or app\n Go to the integration steps for your client.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper goes to your checkout page, get a list of the available payment methods to show the shopper.\n\n\nFrom your server, make a\u00a0POST \/paymentMethods request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nchannel\n\niOS\n\n\ncountryCode\n\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. This is used to translate the payment methods names in the response. Default value: en-US.\n\n\n\nThe information that you include is used to filter the list of available payment methods.\n\n\n\nThe response includes the list of available payment methods, in the paymentMethods object. The payment methods are ordered by popularity in the shopper's country. For each payment method, the response contains:\n\n\n\nParameter name\nDescription\n\n\n\n\nname\nThe name of the payment method that you can show in your payment form.\n\n\ntype\nThe unique payment method code. You must include this when you make a payment.\n\n\n\n\n\n\n\n\nPass the list of available payment methods and the required input fields for each payment method to your client.\n\nBuild your payment form\n\n \n Client website or app\n \n\n\nCreate your payment form where the shopper enters their information. We recommend that you collect commonly-used shopper information in your payment form to process a transactions, depending on your type of business.\n\nSome payment methods require you to collect, or optionally accept, additional information that you include in the payment request. For the additional information you must collect in your payment form for an individual payment method, go to our API-only guide for the individual payment method.\nWe provide payment method and issuer logos that you can download and use in your payment form.\nCredit and debit card details\nBecause governing bodies and organizations regulate the handling of credit and debit card information strictly, you must make sure that you are compliant when collecting card details. When a shopper selects to pay with a card, use the integration option that corresponds to your level of PCI compliance:\n\n(Recommended) Adyen's Custom Card Component with encryption: our pre-built UI with logic to securely encrypt and handle payment card data.\nYour own UI and logic to collect and handle raw card data: before you build an integration that collects raw credit and debit card data, you must assess your PCI compliance according to the most extensive self-assessment form and contact your Adyen Account Manager to confirm that you are eligible.\n\nInformation in the payment form\nAfter collecting information in your payment form, you must add it to corresponding API parameters that you include in the payment request.\nFor example, for commonly-used information:\n\n\n\nField in the payment form\nAPI request parameter\n\n\n\n\nFirst name\nshopperName.firstName\n\n\nLast name\nshopperName.lastName\n\n\nEmail address\nshopperEmail\n\n\nBilling address (multiple fields)\nbillingAddress (object)\n\n\nShipping address (multiple fields)\ndeliveryAddress (object)\n\n\nPhone number\ntelephoneNumber\n\n\n\n \n \n \n \n \n Downloading logos\n \n \n \n \nIf you are building your own UI, we provide payment method and issuing bank logos that you can use on your checkout page. The images are available in PNG format with different sizes and screen resolutions and in SVG format.\nIf you cannot find a payment method or issuer logo, contact our Support Team.\nPayment method logos\nDownload the images from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type returned in the \/paymentMethods response. For example, googlepay or primeiropay_boleto.\nFor cards, the values you should use are specified under brands with type: scheme. For example, mc, visa, and amex. To get a generic card logo, set pm-type to card.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/mc.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/large\/googlepay@2x.png\nIssuing bank logos\nSome payment methods such as iDEAL present a list of issuing banks to the shopper.\nDownload the issuing bank logos from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type in objects with details.key issuer returned in the \/paymentMethods response. For example, ideal.\n\n\nissuerid: The details.items.id referring to the issuing bank. For example, 1121 and 1151 for iDEAL.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/ideal\/1121.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/small\/ideal\/1151-xxhdpi.png\n\n \n \n\nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from your client to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod.type\n\nThe payment method type. From the \/paymentMethods response, this is the value in paymentMethod.type.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. Use the custom URL scheme for your app. Example: com.mydomain.adyencheckout:\/\/ Format: Maximum 1024 characters.If it includes non-ASCII characters, such as spaces or special letters, URL encode it.You can include your own additional query parameters, such as a shopper ID or order reference number. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are a technology partner, service partner, or system integrator, send information about the application, so that we can offer you more support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website or app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nHow you handle the action depends on the action type (action.type):\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, redirect the shopper to another site to complete the payment.\nHow you handle the redirect depends on if it is a payment method redirect or a 3D Secure 2 redirect.\n\n\n \n \n \n \n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2Fingerprint or threeDS2Challenge, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow. Use one of our 3D Secure 2 solutions to handle the action.\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.qrCodeData\nContains the URL for the QR code.\n\n\n\n\n\nGet the qrCodeData from the action object. This parameter contains a URL for the QR code.\n\n\nShow the QR code to the shopper.\n\n\nThe shopper scans the QR code.\n\n\nSend additional payment details to finish the payment flow.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\n \n\n\n\nFrom the \/payments response, get the following from the action object:\n\n\n\nParameter\nDescription\n\n\n\n\nsdkData\nThe data that you must pass to the SDK.\n\n\n\n\n\nPass the data from the sdkData object to the SDK.\n\n\nThe shopper uses the SDK to finish the payment.\n\n\nGet the result from the SDK.\n\n\nSend additional payment details to finish the payment flow.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n \n\n\n\nThe data included in the \/payments response is different for each voucher payment method. Get the available information from it. For example, for DOKU vouchers, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\nexpiresAt\nThe date when the voucher expires.\n\n\ninitialAmount\nThe payment amount and currency.\n\n\nmerchantName\nThe name of your shop.\n\n\ninstructionsUrl\nThe URL where you shopper can get additional information and instructions about how to pay.\n\n\n\n\n\nShow voucher information to the shopper that your shopper uses to pay outside of your client.\n\n\nSend additional payment details to finish the payment flow.\n\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.paymentData\nAdditional payment data.\n\n\n\n\n\nThe shopper finishes the additional action for the payment.\n\n\nSend additional payment details to finish the payment flow.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your client, you do not get additional payment details to send. Instead, wait for the corresponding webhook message for the outcome of the payment.\n\nFrom your server, make a POST \/payments\/details request. The parameters that you must include depends on the payment method. For the parameters for an individual payment method, go to the API-only page for the individual payment method .\n\n \n\nThe response includes information about the current payment status.\n\n \n\n\n \nGet the payment outcome\nAfter the shopper finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website or app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account.\nAssess your PCI DSS compliance by submitting:\n\nthe Self-Assessment Questionnaire-A, if you are using the Custom Card Component.\nthe Self-Assessment Questionnaire-D, if you are submitting raw card data.\n\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.requiredAdd payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["iOS","API only"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Android&integration=Drop-in","title":"Android Drop-in","content":"Android Drop-in\nRender a list of available payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLowest development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\n \n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nConfigure and launch Drop-in to collect the shopper's details.\nFrom your server, make a payment request with data that you receive from Drop-in.\nHandle additional client-side actions, if required.\nFrom your server, send additional payment details with data you receive from Drop-in, if required.\nGet the payment outcome to inform the shopper and update your order management system.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\n\n\nFrom your server, make a POST \/paymentMethods request, including:\n\nWe recommend that you include all the optional parameters to get the most accurate list of available payment methods.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\nchannel\n\nUse Android. Adyen returns only the payment methods available for Android.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same ShopperLocale within your Drop-in configuration.\n\n\n\nFor example, to get available payment methods for a shopper in the Netherlands, for a payment of 10 EUR:\n\n\n\nThe response includes the list of available paymentMethods:\n\n\n\n\n\nDeserialize the response to a PaymentMethodsApiResponse:\n\n\n\n \n\n\nPass the PaymentMethodsApiResponse object to your client app to launch and show Drop-in.\nSet up Drop-in\n\n \n Client app\n \n\n\n1: Import the library\nThe default implementation is with Jetpack Compose, but you can import the library without Jetpack Compose instead.\nImport the compatibility module in your build.gradle file:\n\n\n \n \n \n \n\n2: Create the configuration object\nCreate the configuration object to pass when you launch and show Drop-in.\n\n\nSet the following properties in the configuration object: \n\n\n\nProperty\nRequired\nDescription\n\n\n\n\namount\nIf you want to show the amount on the Pay button.\nThe currency and value of the payment amount shown on the Pay button.\n\n\nenvironment\n\nUse Environment.TEST for testing. When going live, use one of our live environments.\n\n\nclientKey\n\nYour client key.\n\n\nshopperLocale\n\nThe shopper's locale. By default, this is the device's locale.\n\n\n\n\n\nAdd additional configuration to this object. Some payment methods require additional configuration, and you can add optional configuration for Drop-in.\nFor example, to configure for a payment of 10 EUR:\n\n\n\n\n\nExtend the DropInService class so that you can interact with Drop-in.\n\n\nImplement methods to pass data between your client app and your server. You must also handle the DropInServiceResult which includes the result of the API requests from your server.\nFor example:\n\n\n\nDrop-in uses the DropInServiceResult to complete or dismiss the payment and determine if you need to handle additional actions. Additional actions include redirecting the shopper to another app or performing 3D Secure 2 authentication.\n\n\nAdd your DropInService to your manifest file.\nFor example:\n<service\nandroid:name=\".YourDropInService\"\nandroid:exported=\"false\" \/>\n\nLaunch and show Drop-in\n\n\n \n \n \n \n\n\nYour app shows Drop-in, and your shopper can choose a payment method.Make a payment\n\n \n Payment server\n \n\n\nWhen the shopper enters their payment details and selects the Pay button, the onSubmit method in your DropInService class is called, passing the paymentComponentJson object.\n\n\nPass the paymentComponentJson object to your server.\n\n\nFrom your server, make a POST \/payments request including the following:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete paymentComponentData.paymentMethod object from your client app that includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by Drop-in to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nIn case of a redirection, this is the URL to where your shopper is redirected after they complete the payment. Maximum length: 1024 characters. Get this URL from Drop-in in the RedirectComponent.getReturnUrl(context).\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support.\n\n\n\n\nYou must include additional parameters in your payment request to:\n\nIntegrate some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to Required risk fields.\nUse native 3D Secure 2 authentication.\nTokenize your shopper's payment details or make recurring payments.\n\n\nFor example, to make a payment request for EUR 10:\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\n\nError handling\nIf the \/payments request fails, return DropInServiceResult.Error to your client app, including the action object.Handle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nDeserialize the action object it and pass it to Drop-in.\n\nPass the full action object from your server to Drop-in.\nUse ActionResponse.SERIALIZER to deserialize the action object.\nReturn it as DropInServiceResult.Action to Drop-in.\nDrop-in handles the additional action on the client side.\n\nYou handle the payment data, depending on the type of action (action.type).\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, Drop-in redirects your shopper to another website to complete the payment.\n\nWhen the shopper returns to your app, Drop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.`\nPass the actionComponentJson object from your client app to your server.\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nDrop-in handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nDrop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must use a QR code to complete the payment.\n\nDrop-in shows the QR code to the shopper.\nWhen the shopper uses the QR code to complete the payment, Drop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nDrop-in shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nDrop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nDrop-in shows the voucher to the shopper.\nWhen the shopper completes the additional action with the voucher (for example: saving it to their digital wallet or forwarding it to their email), Drop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nDrop-in shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nDrop-in calls the onAdditionalDetails method in your DropInService class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details to Adyen.\n\n\nPass the full actionComponentJson object to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data from the actionComponentJson object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in a webhook with eventCode: AUTHORISATION. Use this to update your order management system.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. Use the Adyen Android test cards app to access, copy, and autofill card details from within your Android device. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\nEUROPE\n\n\nUnited States (US) live\nUNITED_STATES\n\n\nAustralia (AU) live\nAUSTRALIA\n\n\nAsia Pacific & Southeast (APSE) live\nAPSE\n\n\nIndia (IN) live\nINDIA\n\n\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Android","Drop-in"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Android&integration=Components","title":"Android Components","content":"Android Components\nRender individual payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate each payment method component\nUI styling customization for each payment method\nFlexibility to add payment method components with configuration for each\n3D Secure 2 support using the 3D Secure 2 Component\nHow it works\nFor a Components integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\n\nFrom your server, submit a request to get a list of payment methods available to the shopper.\nConfigure and launch the Component to collect the shopper's details.\nFrom your server, make a payment request with data that you receive from the Component.\nHandle additional client-side actions, if required.\nFrom your server, send additional payment details that you receive from the Component, if required.\nGet the payment outcome to inform the shopper and update your order management system.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a POST \/paymentMethods request, including:\n\nWe recommend that you include all the optional parameters to get the most accurate list of available payment methods.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\nchannel\n\nUse Android. Adyen returns only the payment methods available for Android.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same ShopperLocale within your Checkout configuration.\n\n\n\nFor example, to get available payment methods for a shopper in the Netherlands, for a payment of 10 EUR:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nYou must pass the response to your client app to launch and show Components.Set up Components\n\n \n Client app\n \n\n\n1: Import the library\nThe default implementation is with Jetpack Compose, but you can import the library without Jetpack Compose instead.\nImport the compatibility module in your build.gradle file. For example, to import the Card Component:\n\n\n \n \n \n \n\n\nYou can find the module to import for each payment method on the corresponding payment method page.2: Create the configuration object\n\n\nSet the following properties in the configuration object:\n\n\n\nProperty\nRequired\nDescription\n\n\n\n\namount\nIf you want to show the amount on the Pay button.\nThe currency and value of the payment amount shown on the Pay button.\n\n\nenvironment\n\nUse Environment.TEST for testing. When going live, use one of our live environments.\n\n\nclientKey\n\nYour client key.\n\n\nshopperLocale\n\nThe shopper's locale. By default, this is the device's locale.\n\n\n\n\n\nInclude other configurations for the Component.\n\n\nFor example, to configure the card Component:\n\n \n\n\n\nImplement methods in ComponentCallback to pass data between your client app and your server.\n\n\n\nMethod\nDescription\n\n\n\n\nonSubmit\nMake a \/payments request.\n\n\nonAdditionalDetails\nMake a \/payments\/details request.\n\n\nonError\nHandle an error if the Component encounters one.\n\n\n\n\n\nFor example, for the card Component:\n\n \nLaunch and show the Component\n\n \n Client app\n \n\n\n\n\n \n \n \n \n\n\nYour app shows the Component.Make a payment\n\n \n Payment server\n \n\n\nWhen the shopper enters their payment details and selects the Pay button, the onSubmit method in your ComponentCallback class is called, passing the paymentComponentJson object.\n\n\nPass the paymentComponentJson object to your server.\n\n\nFrom your server, make a POST \/payments request including the following\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete paymentComponentData.paymentMethod object from your client app that includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nIn case of a redirection, this is the URL to where your shopper is redirected after they complete the payment. Maximum length: 1024 characters. Get this URL from the RedirectComponent.getReturnUrl(context).\n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, refer to our payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\n\nError handling\nIf the \/payments request fails, show the error to the shopper in your client UI.Handle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nWhen you get the action object in the response, do the following:\n\nPass the full action object from your server to the Component.\nUse ActionResponse.SERIALIZER to serialize the action object.\nReturn the serialized object to The Component.\nThe Component handles the additional action on the client side.\nYou handle the payment data, depending on the type of action (action.type).\n\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type: redirect, the Component redirects your shopper to another website or app to complete the payment.\n\n\nAdd an IntentFilter to your Activity that handles redirects.\n\n\n\nThe android:host value is your package name at build time. This must match the returnUrl from the \/payments request.\nTo get your returnUrl from the Component, you can use the RedirectComponent.getReturnUrl(context) function.\n\n\nPass the full action object from your server to the Component.\n\n\nThe Component redirects the shopper to another website or app.\n\n\nThe shopper returns to your app.\n\n\nFrom your Activity, get the result of the redirect.\n\n\nPass the Intent to the the Component. Depending on your activity's launch mode, you get the intent in either onCreate or onNewIntent.\n\n\n\n\n\nThe Component notifies you through the ComponentCallback.onAdditionalDetails method with the actionComponentData object from intent.data.\n\n\nPass the actionComponentData object from your client app to your server.\n\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nThe Component handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nThe Component calls the onAdditionalDetails method in your ComponentCallback class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must use a QR code to complete the payment.\n\nThe Component shows the QR code to the shopper.\nWhen the shopper uses the QR code to complete the payment, the Component calls the onAdditionalDetails method in your ComponentCallback class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nThe Component shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nThe Component calls the onAdditionalDetails method in your ComponentCallback class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nThe Component shows the voucher to the shopper.\nWhen the shopper completes the additional action with the voucher (for example: saving it to their digital wallet or forwarding it to their email), The Component calls the onAdditionalDetails method in your ComponentCallback class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nThe Component shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nThe Component calls the onAdditionalDetails method in your ComponentCallback class.\nFrom onAdditionalDetails, get the actionComponentJson object.\nPass the actionComponentJson object from your client app to your server.\nSend additional payment details.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details to Adyen.\n\n\nPass the full actionComponentJson object to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data from the actionComponentJson object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. Use the Adyen Android test cards app to access, copy, and autofill card details from within your Android device. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\nEUROPE\n\n\nUnited States (US) live\nUNITED_STATES\n\n\nAustralia (AU) live\nAUSTRALIA\n\n\nAsia Pacific & Southeast (APSE) live\nAPSE\n\n\nIndia (IN) live\nINDIA\n\n\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Android","Components"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Android&integration=API only","title":"Android API only","content":"API only\nCreate your own client-side UI and use our API endpoints to get the list of available payment methods and submit a payment.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nFull control of styling on your checkout page\nYour own UI elements\nCreating your own client-side logic\n\nHandling secure card data and authentication\nYou must ensure that your integration complies with regulatory requirements such as PCI DSS and PSD2 SCA.\nWe recommend that you use our pre-built client-side solutions to securely do the following:\n\nCollect, validate, and encrypt card details: Implement our solution to handle encrypted card data with your custom UI and comply with PCI DSS regulations.\nAuthenticate transactions with 3D Secure 2: Handle the 3D Secure 2 authentication action using our solution and comply with PSD2 SCA regulations for online payments.\nWith an API-only integration, you create your own UI, implement your own client-side logic, and use our API to send and receive payment data. You have full control over the look and feel of your checkout page.\nTo reduce your development time and resources, you can use one of our pre-built UI options (Drop-in\/Components) instead.Requirements\nBefore you build your integration, take into account the following requirements and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that you have the following role: Checkout webservice role\n\n\nCustomer Area roles\nMake sure that you have one of the following roles: Merchant admin role Manage API credentials\n\n\nWebhooks\nSubscribe to the following webhook: Standard webhooks\n\n\nLimitations\nYour PCI compliance assesment determines your integration options for card payments.For 3D Secure 2 authentication for shoppers using Chrome, your cookies must use the SameSite attribute. \n\n\nSetup steps\nBefore you begin: Create your Adyen test accountGet your API key.Get your client key.Set up webhooks.If you want to process payments using raw card data, contact your Adyen Account Manager to confirm that you are eligible.\n\n\nHow it works\nFor an API-only integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\nYour client: shows your custom UI where the shopper makes the payment. Passes data to and receives data from your payment server to handle the payment flow and additional actions on your client.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIntegration steps\nThe parts of your integration work together to handle the payment flow:\n\nFrom your server, make an API request to get a list of payment methods available to the shopper.\nShow the payment form to collect the shopper's payment details in your UI.\nFrom your server, make a payment request with the data that you have collected from the shopper.\nFor some payment methods, you use your client to handle the additional action that your shopper must do. For example, you redirect your shopper to another website or show a QR code that the shopper uses to complete the payment.\nFrom your server, send additional payment details.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website or app\n Go to the integration steps for your client.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper goes to your checkout page, get a list of the available payment methods to show the shopper.\n\n\nFrom your server, make a\u00a0POST \/paymentMethods request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nchannel\n\nAndroid\n\n\ncountryCode\n\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. This is used to translate the payment methods names in the response. Default value: en-US.\n\n\n\nThe information that you include is used to filter the list of available payment methods.\n\n\n\nThe response includes the list of available payment methods, in the paymentMethods object. The payment methods are ordered by popularity in the shopper's country. For each payment method, the response contains:\n\n\n\nParameter name\nDescription\n\n\n\n\nname\nThe name of the payment method that you can show in your payment form.\n\n\ntype\nThe unique payment method code. You must include this when you make a payment.\n\n\n\n\n\n\n\n\nPass the list of available payment methods and the required input fields for each payment method to your client.\n\nBuild your payment form\n\n \n Client website or app\n \n\n\nCreate your payment form where the shopper enters their information. We recommend that you collect commonly-used shopper information in your payment form to process a transactions, depending on your type of business.\n\nSome payment methods require you to collect, or optionally accept, additional information that you include in the payment request. For the additional information you must collect in your payment form for an individual payment method, go to our API-only guide for the individual payment method.\nWe provide payment method and issuer logos that you can download and use in your payment form.\nCredit and debit card details\nBecause governing bodies and organizations regulate the handling of credit and debit card information strictly, you must make sure that you are compliant when collecting card details. When a shopper selects to pay with a card, use the integration option that corresponds to your level of PCI compliance:\n\n(Recommended) Adyen's Custom Card Component with encryption: our pre-built UI with logic to securely encrypt and handle payment card data.\nYour own UI and logic to collect and handle raw card data: before you build an integration that collects raw credit and debit card data, you must assess your PCI compliance according to the most extensive self-assessment form and contact your Adyen Account Manager to confirm that you are eligible.\n\nInformation in the payment form\nAfter collecting information in your payment form, you must add it to corresponding API parameters that you include in the payment request.\nFor example, for commonly-used information:\n\n\n\nField in the payment form\nAPI request parameter\n\n\n\n\nFirst name\nshopperName.firstName\n\n\nLast name\nshopperName.lastName\n\n\nEmail address\nshopperEmail\n\n\nBilling address (multiple fields)\nbillingAddress (object)\n\n\nShipping address (multiple fields)\ndeliveryAddress (object)\n\n\nPhone number\ntelephoneNumber\n\n\n\n \n \n \n \n \n Downloading logos\n \n \n \n \nIf you are building your own UI, we provide payment method and issuing bank logos that you can use on your checkout page. The images are available in PNG format with different sizes and screen resolutions and in SVG format.\nIf you cannot find a payment method or issuer logo, contact our Support Team.\nPayment method logos\nDownload the images from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type returned in the \/paymentMethods response. For example, googlepay or primeiropay_boleto.\nFor cards, the values you should use are specified under brands with type: scheme. For example, mc, visa, and amex. To get a generic card logo, set pm-type to card.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/mc.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/large\/googlepay@2x.png\nIssuing bank logos\nSome payment methods such as iDEAL present a list of issuing banks to the shopper.\nDownload the issuing bank logos from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type in objects with details.key issuer returned in the \/paymentMethods response. For example, ideal.\n\n\nissuerid: The details.items.id referring to the issuing bank. For example, 1121 and 1151 for iDEAL.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/ideal\/1121.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/small\/ideal\/1151-xxhdpi.png\n\n \n \n\nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from your client to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod.type\n\nThe payment method type. From the \/paymentMethods response, this is the value in paymentMethod.type.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. Use the combination of: adyencheckout:\/\/ schemeYour package nameA path. Example: adyencheckout:\/\/com.adyen.adyen_checkout_example\/adyenPayment Format: Maximum 1024 characters.If it includes non-ASCII characters, such as spaces or special letters, URL encode it.You can include your own additional query parameters, such as a shopper ID or order reference number. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are a technology partner, service partner, or system integrator, send information about the application, so that we can offer you more support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website or app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nHow you handle the action depends on the action type (action.type):\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, redirect the shopper to another site to complete the payment.\nHow you handle the redirect depends on if it is a payment method redirect or a 3D Secure 2 redirect.\n\n\n \n \n \n \n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2Fingerprint or threeDS2Challenge, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow. Use one of our 3D Secure 2 solutions to handle the action.\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.qrCodeData\nContains the URL for the QR code.\n\n\n\n\n\nGet the qrCodeData from the action object. This parameter contains a URL for the QR code.\n\n\nShow the QR code to the shopper.\n\n\nThe shopper scans the QR code.\n\n\nSend additional payment details to finish the payment flow.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\n \n\n\n\nFrom the \/payments response, get the following from the action object:\n\n\n\nParameter\nDescription\n\n\n\n\nsdkData\nThe data that you must pass to the SDK.\n\n\n\n\n\nPass the data from the sdkData object to the SDK.\n\n\nThe shopper uses the SDK to finish the payment.\n\n\nGet the result from the SDK.\n\n\nSend additional payment details to finish the payment flow.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n \n\n\n\nThe data included in the \/payments response is different for each voucher payment method. Get the available information from it. For example, for DOKU vouchers, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\nexpiresAt\nThe date when the voucher expires.\n\n\ninitialAmount\nThe payment amount and currency.\n\n\nmerchantName\nThe name of your shop.\n\n\ninstructionsUrl\nThe URL where you shopper can get additional information and instructions about how to pay.\n\n\n\n\n\nShow voucher information to the shopper that your shopper uses to pay outside of your client.\n\n\nSend additional payment details to finish the payment flow.\n\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.paymentData\nAdditional payment data.\n\n\n\n\n\nThe shopper finishes the additional action for the payment.\n\n\nSend additional payment details to finish the payment flow.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your client, you do not get additional payment details to send. Instead, wait for the corresponding webhook message for the outcome of the payment.\n\nFrom your server, make a POST \/payments\/details request. The parameters that you must include depends on the payment method. For the parameters for an individual payment method, go to the API-only page for the individual payment method .\n\n \n\nThe response includes information about the current payment status.\n\n \n\n\n \nGet the payment outcome\nAfter the shopper finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website or app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account.\nAssess your PCI DSS compliance by submitting:\n\nthe Self-Assessment Questionnaire-A, if you are using the Custom Card Component.\nthe Self-Assessment Questionnaire-D, if you are submitting raw card data.\n\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.requiredAdd payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Android","API only"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=React Native&integration=Drop-in","title":"React Native Drop-in","content":"React Native Drop-in\nRender a list of available payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLowest development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\nDrop-in is our pre-built UI solution for accepting payments in your app. Drop-in shows all payment methods as a list, in the same block. Your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\n\nThe parts of your integration work together to complete the payment flow:\n\nThe shopper goes to the checkout page.\nYour server uses the shopper's country and currency information from your client to get available payment methods.\nDrop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and shows the payment result to the shopper.\nYour webhook server receives the notification containing the payment outcome.\n\n\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. For example, when you set this to iOS, Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. The front end also uses this locale.\n\n\n\nFor example, to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. Use this in the next step to show available payment methods to the shopper.Add Adyen Drop-in to your app\n\n \n Client app\n \n\n\n1. Add Adyen React Native to your project\n\n \n\n2. Install\n\n\n \n \n \n \n\n3. Create a configuration object\nCreate a configuration object with the following properties:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nenvironment\n\nUse test. When you're ready to accept live payments, change the value to one of our live environments.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication.\n\n\nreturnUrl\n\nFor iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. For Android, this value is automatically overridden by AdyenCheckout.\n\n\ncountryCode\nIf you want to show the amount on the Pay button.\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\namount\nIf you want to show the amount on the Pay button.\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\n\n\nFor example: \n\n \n\nTo add configuration for specific payment methods, add these in a payment method specific configuration object. For example, for Apple Pay:\n\n \n\nOptional configuration\nOptionally, you can configure the following properties for Drop-in.\n\n\n\nParameter\nDescription\n\n\n\n\nshowPreselectedStoredPaymentMethod\nWhen enabled, shows the preselected stored payment method view. Defaults to true.\n\n\nskipListWhenSinglePaymentMethod\nSet to true to skip showing the payment methods list when only one non-instant payment method is available. Defaults to false.\n\n\ntitle Only for iOS\nSet a custom title for the pre-selected stored payment view. By default, the app's name is used.\n\n\nshowRemovePaymentMethodButton\nAllows the shopper to remove a stored payment method. Defaults to false. When enabled, you must also implement the onDisableStoredPaymentMethod callback.\n\n\nonDisableStoredPaymentMethod(storedPaymentMethod, resolve, reject) => {}\nCalled when a shopper removes a stored payment method. To remove the selected payment method, make a DELETE storedPaymentMethods request using the storedPaymentMethodId. Then call either resolve() or reject(), depending on the \/storedPaymentMethods\/{storedPaymentMethodId} response.\n\n\n\nFor example:\n\n \n\n4. Initialize Drop-in\n\nConfigure AdyenCheckout, setting the following:\n\n\n\n\nParameter\nDescription\n\n\n\n\nconfig\nYour configuration object.\n\n\npaymentMethods\nThe full response from the \/paymentMethods endpoint.\n\n\nonSubmit\nCallback that uses data to make a \/payments request when the shopper selects the Pay button and the payment details are valid.\n\n\nonAdditionalDetails\nCallback that uses data to make a \/payments\/details request when a payment requires additional details, for example to authenticate with 3D Secure or to pay using a QR code.\n\n\nonError\nCallback that handles errors.\n\n\n\nIn your onSubmit, onAdditionalDetails, and onError callbacks, you must call component.hide(result) to dismiss the payment UI when the API request is completed and the payment result is known.\n\nSet AdyenCheckout as the context for your \n View\n.\n\nFor example:\n\n \n\n\nCreate a way, like a button, for AdyenCheckout to call the start function.\n\n\n \n\nThe context starts Adyen's Native Component for Drop-in.\nMake a payment\n\n \n Payment server\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, the Native Component calls onSubmit, and you must make a payment request to Adyen.\n\n\nPass the data from onSubmit to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete paymentMethod object from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n For Android, this value is automatically overridden by AdyenCheckout.\nFor iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\n\nErrors\nIf an error occurs, you get an error object from the onError callback with one of the following error codes:\n\n\n\nError code\nDescription\nAction to take\n\n\n\n\ncanceledByShopper\nThe shopper canceled the payment.\nTake the shopper back to the checkout page.\n\n\nnotSupported\nThe payment method isn't supported by the shopper's device.\nTell the shopper that the payment method isn't supported by their device.\n\n\nnoClientKey\nNo clientKey configured.\nTell the shopper that an error occurred.\n\n\nnoPayment\nNo payment information configured.\nTell the shopper that an error occurred.\n\n\ninvalidPaymentMethods\nCan't parse the paymentMethods list, or the list is empty.\nTell the shopper that an error occurred.\n\n\nnoPaymentMethod\nCan't find the selected payment method.\nTell the shopper that their selected payment method is currently unavailable.\n\n\nHandle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nTo handle these additional front-end actions, the AdyenCheckout provides a handle function.\n\n\nCall handle from one of Adyen's Native Components and pass the action to it. For example:\n\n\n\n\n\nThe Native Component performs the additional action on the client side.\n\n\nYou handle the payment data, depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, Drop-in redirects your shopper to another website to complete the payment.\n\nWhen the shopper returns to your app, Drop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nDrop-in handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nDrop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must use a QR code to complete the payment.\n\nDrop-in shows the QR code to the shopper.\nWhen the shopper uses the QR code to complete the payment, Drop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nDrop-in shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nDrop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nDrop-in shows the voucher to the shopper.\nWhen the shopper completes the additional action with the voucher (for example: saving it to their digital wallet or forwarding it to their email), Drop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nDrop-in shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nDrop-in calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your app, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass the full data object from the didProvide method to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\nLoad Drop-in from one of our live environments and set the environment to match your live endpoints:\n\n\n\n\nEndpoint region\nenvironment value\n\n\n\n\nEurope\nlive-eu\n\n\nAustralia\nlive-au\n\n\nUS\nlive-us\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["React Native","Drop-in"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=React Native&integration=Components","title":"React Native Components","content":"React Native Components\nRender individual payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate each payment method component\nUI styling customization for each payment method\nFlexibility to add payment method components with configuration for each\n3D Secure 2 support using the 3D Secure 2 Component\nComponents are our pre-built UI solution for accepting payments in your app. Each Component renders a payment method you can render anywhere in your app. Your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\nHow it works\nFor a Components integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\n\nThe parts of your integration work together to complete the payment flow:\n\nThe shopper goes to the checkout page.\nYour server uses the shopper's country and currency information from your client to get available payment methods.\nThe Component collects the shopper's payment details, handles additional actions, and shows the payment result to the shopper.\nYour webhook server receives the notification containing the payment outcome.\n\n\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. For example, when you set this to iOS, Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. The front end also uses this locale.\n\n\n\nFor example, to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. Use this in the next step to show available payment methods to the shopper.Add Adyen Components to your app\n1. Add Adyen React Native to your project\n$ yarn add @adyen\/react-native\n2. Install\n\n\n \n \n \n \n\n3. Create a configuration object\nCreate a configuration object with the following properties:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nenvironment\n\nUse test. When you're ready to accept live payments, change the value to one of our live environments.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication.\n\n\nreturnUrl\n\nFor iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. For Android, this value is automatically overridden by AdyenCheckout.\n\n\ncountryCode\nIf you want to show the amount on the Pay button.\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\namount\nIf you want to show the amount on the Pay button.\nThe\u00a0currency\u00a0and\u00a0value\u00a0of the payment, in minor units.\n\n\n\n\nFor example: \n\n \n\nTo add configuration for specific payment methods, add these in a payment method specific configuration object. For example, for Apple Pay:\n\n \n\n4. Initialize Components\n\nConfigure AdyenCheckout, setting the following:\n\n\n\n\nParameter\nDescription\n\n\n\n\nconfig\nYour configuration object.\n\n\npaymentMethods\nThe full response from the \/paymentMethods endpoint.\n\n\nonSubmit\nCallback that uses data to make a \/payments request when the shopper selects the Pay button and the payment details are valid.\n\n\nonAdditionalDetails\nCallback that uses data to make a \/payments\/details request when a payment requires additional details, for example to authenticate with 3D Secure or to pay using a QR code.\n\n\nonError\nCallback that handles errors.\n\n\n\nIn your onSubmit, onAdditionalDetails, and onError callbacks, you must call component.hide(result) to dismiss the payment UI when the API request is completed and the payment result is known.\n\nSet AdyenCheckout as the context for your View.\n\nFor example:\n\n \n\n\nCreate a way, like a button, for AdyenCheckout to call the start function.\n\n\n \n\nThe context starts Adyen's Native Component for the corresponding payment method.\nMake a payment\n\n \n Payment server\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, the Native Component calls onSubmit, and you must make a payment request to Adyen.\n\n\nPass the data from onSubmit to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete paymentMethod object from your client app. It includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n For Android, this value is automatically overridden by AdyenCheckout.\nFor iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\n\nErrors\nIf an error occurs, you get an error object from the onError callback with one of the following error codes:\n\n\n\nError code\nDescription\nAction to take\n\n\n\n\ncanceledByShopper\nThe shopper canceled the payment.\nTake the shopper back to the checkout page.\n\n\nnotSupported\nThe payment method isn't supported by the shopper's device.\nTell the shopper that the payment method isn't supported by their device.\n\n\nnoClientKey\nNo clientKey configured.\nTell the shopper that an error occurred.\n\n\nnoPayment\nNo payment information configured.\nTell the shopper that an error occurred.\n\n\ninvalidPaymentMethods\nCan't parse the paymentMethods list, or the list is empty.\nTell the shopper that an error occurred.\n\n\nnoPaymentMethod\nCan't find the selected payment method.\nTell the shopper that their selected payment method is currently unavailable.\n\n\nHandle the additional action\n\n \n Client app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nTo handle these additional front-end actions, the AdyenCheckout provides a handle function.\n\n\nCall handle from one of Adyen's Native Components and pass the action to it. For example:\n\n\n\n\n\nThe Native Component performs the additional action on the client side.\n\n\nYou handle the payment data, depending on the value of action.type.\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, the Component redirects your shopper to another website to complete the payment.\n\nWhen the shopper returns to your app, the Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\n\nSend additional payment details.\n\nIf the shopper fails to return to your app, you do not get the additional data to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow.\n\nThe Component handles 3D Secure 2 authentication. If a challenge is required, the shopper performs the authentication challenge to complete the payment.\nThe Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must use a QR code to complete the payment.\n\nThe Component shows the QR code to the shopper.\nWhen the shopper uses the QR code to complete the payment, the Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\nThe Component shows a different UI in an overlay.\nThe shopper uses the UI overlay to complete the payment.\nThe Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\nThe Component shows the voucher to the shopper.\nWhen the shopper completes the additional action with the voucher (for example: saving it to their digital wallet or forwarding it to their email), the Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\nThe Component shows the instructions for the additional action to complete the payment.\nThe shopper does the additional action.\nThe Component calls the onAdditionalDetails event.\nPass the data object from the didProvide method to your server.\nSend additional payment details.\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your app, you do not get additional payment details to send. Instead, wait for the corresponding webhook for the outcome of the payment.\n\n\n\nPass the full data object from the didProvide method to your server.\n\n\nFrom your server, make a POST \/payments\/details request including the full data object.\n\n\n\n\n\nPass the \/payments\/details response from your server to your client app.\n\n\n\n\n\n\n\nGet the payment outcome\nAfter the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the resultCode to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\nLoad Components from one of our live environments and set the environment to match your live endpoints:\n\n\n\n\nEndpoint region\nenvironment value\n\n\n\n\nEurope\nlive-eu\n\n\nAustralia\nlive-au\n\n\nUS\nlive-us\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["React Native","Components"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=React Native&integration=API only","title":"React Native API only","content":"API only\nCreate your own client-side UI and use our API endpoints to get the list of available payment methods and submit a payment.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nFull control of styling on your checkout page\nYour own UI elements\nCreating your own client-side logic\n\nHandling secure card data and authentication\nYou must ensure that your integration complies with regulatory requirements such as PCI DSS and PSD2 SCA.\nWe recommend that you use our pre-built client-side solutions to securely do the following:\n\nCollect, validate, and encrypt card details: Implement our solution to handle encrypted card data with your custom UI and comply with PCI DSS regulations.\nAuthenticate transactions with 3D Secure 2: Handle the 3D Secure 2 authentication action using our solution and comply with PSD2 SCA regulations for online payments.\nWith an API-only integration, you create your own UI, implement your own client-side logic, and use our API to send and receive payment data. You have full control over the look and feel of your checkout page.\nTo reduce your development time and resources, you can use one of our pre-built UI options (Drop-in\/Components) instead.Requirements\nBefore you build your integration, take into account the following requirements and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that you have the following role: Checkout webservice role\n\n\nCustomer Area roles\nMake sure that you have one of the following roles: Merchant admin role Manage API credentials\n\n\nWebhooks\nSubscribe to the following webhook: Standard webhooks\n\n\nLimitations\nYour PCI compliance assesment determines your integration options for card payments.For 3D Secure 2 authentication for shoppers using Chrome, your cookies must use the SameSite attribute. \n\n\nSetup steps\nBefore you begin: Create your Adyen test accountGet your API key.Get your client key.Set up webhooks.If you want to process payments using raw card data, contact your Adyen Account Manager to confirm that you are eligible.\n\n\nHow it works\nFor an API-only integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\nYour client: shows your custom UI where the shopper makes the payment. Passes data to and receives data from your payment server to handle the payment flow and additional actions on your client.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIntegration steps\nThe parts of your integration work together to handle the payment flow:\n\nFrom your server, make an API request to get a list of payment methods available to the shopper.\nShow the payment form to collect the shopper's payment details in your UI.\nFrom your server, make a payment request with the data that you have collected from the shopper.\nFor some payment methods, you use your client to handle the additional action that your shopper must do. For example, you redirect your shopper to another website or show a QR code that the shopper uses to complete the payment.\nFrom your server, send additional payment details.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website or app\n Go to the integration steps for your client.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper goes to your checkout page, get a list of the available payment methods to show the shopper.\n\n\nFrom your server, make a\u00a0POST \/paymentMethods request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nchannel\n\nThe shopper's device: iOS or Android.\n\n\ncountryCode\n\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. This is used to translate the payment methods names in the response. Default value: en-US.\n\n\n\nThe information that you include is used to filter the list of available payment methods.\n\n\n\nThe response includes the list of available payment methods, in the paymentMethods object. The payment methods are ordered by popularity in the shopper's country. For each payment method, the response contains:\n\n\n\nParameter name\nDescription\n\n\n\n\nname\nThe name of the payment method that you can show in your payment form.\n\n\ntype\nThe unique payment method code. You must include this when you make a payment.\n\n\n\n\n\n\n\n\nPass the list of available payment methods and the required input fields for each payment method to your client.\n\nBuild your payment form\n\n \n Client website or app\n \n\n\nCreate your payment form where the shopper enters their information. We recommend that you collect commonly-used shopper information in your payment form to process a transactions, depending on your type of business.\n\nSome payment methods require you to collect, or optionally accept, additional information that you include in the payment request. For the additional information you must collect in your payment form for an individual payment method, go to our API-only guide for the individual payment method.\nWe provide payment method and issuer logos that you can download and use in your payment form.\nCredit and debit card details\nBecause governing bodies and organizations regulate the handling of credit and debit card information strictly, you must make sure that you are compliant when collecting card details. When a shopper selects to pay with a card, use the integration option that corresponds to your level of PCI compliance:\n\n(Recommended) Adyen's Custom Card Component with encryption: our pre-built UI with logic to securely encrypt and handle payment card data.\nYour own UI and logic to collect and handle raw card data: before you build an integration that collects raw credit and debit card data, you must assess your PCI compliance according to the most extensive self-assessment form and contact your Adyen Account Manager to confirm that you are eligible.\n\nInformation in the payment form\nAfter collecting information in your payment form, you must add it to corresponding API parameters that you include in the payment request.\nFor example, for commonly-used information:\n\n\n\nField in the payment form\nAPI request parameter\n\n\n\n\nFirst name\nshopperName.firstName\n\n\nLast name\nshopperName.lastName\n\n\nEmail address\nshopperEmail\n\n\nBilling address (multiple fields)\nbillingAddress (object)\n\n\nShipping address (multiple fields)\ndeliveryAddress (object)\n\n\nPhone number\ntelephoneNumber\n\n\n\n \n \n \n \n \n Downloading logos\n \n \n \n \nIf you are building your own UI, we provide payment method and issuing bank logos that you can use on your checkout page. The images are available in PNG format with different sizes and screen resolutions and in SVG format.\nIf you cannot find a payment method or issuer logo, contact our Support Team.\nPayment method logos\nDownload the images from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type returned in the \/paymentMethods response. For example, googlepay or primeiropay_boleto.\nFor cards, the values you should use are specified under brands with type: scheme. For example, mc, visa, and amex. To get a generic card logo, set pm-type to card.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/mc.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/large\/googlepay@2x.png\nIssuing bank logos\nSome payment methods such as iDEAL present a list of issuing banks to the shopper.\nDownload the issuing bank logos from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type in objects with details.key issuer returned in the \/paymentMethods response. For example, ideal.\n\n\nissuerid: The details.items.id referring to the issuing bank. For example, 1121 and 1151 for iDEAL.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/ideal\/1121.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/small\/ideal\/1151-xxhdpi.png\n\n \n \n\nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from your client to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod.type\n\nThe payment method type. From the \/paymentMethods response, this is the value in paymentMethod.type.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. iOS: Use the custom URL scheme for your app. iOS example: com.mydomain.adyencheckout:\/\/ Android: Use the combination of: adyencheckout:\/\/ schemeYour package nameA path. Android example: adyencheckout:\/\/com.adyen.adyen_checkout_example\/adyenPayment Format: Maximum 1024 characters.If it includes non-ASCII characters, such as spaces or special letters, URL encode it.You can include your own additional query parameters, such as a shopper ID or order reference number. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are a technology partner, service partner, or system integrator, send information about the application, so that we can offer you more support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website or app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nHow you handle the action depends on the action type (action.type):\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, redirect the shopper to another site to complete the payment.\nHow you handle the redirect depends on if it is a payment method redirect or a 3D Secure 2 redirect.\n\n\n \n \n \n \n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2Fingerprint or threeDS2Challenge, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow. Use one of our 3D Secure 2 solutions to handle the action.\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.qrCodeData\nContains the URL for the QR code.\n\n\n\n\n\nGet the qrCodeData from the action object. This parameter contains a URL for the QR code.\n\n\nShow the QR code to the shopper.\n\n\nThe shopper scans the QR code.\n\n\nSend additional payment details to finish the payment flow.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\n \n\n\n\nFrom the \/payments response, get the following from the action object:\n\n\n\nParameter\nDescription\n\n\n\n\nsdkData\nThe data that you must pass to the SDK.\n\n\n\n\n\nPass the data from the sdkData object to the SDK.\n\n\nThe shopper uses the SDK to finish the payment.\n\n\nGet the result from the SDK.\n\n\nSend additional payment details to finish the payment flow.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n \n\n\n\nThe data included in the \/payments response is different for each voucher payment method. Get the available information from it. For example, for DOKU vouchers, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\nexpiresAt\nThe date when the voucher expires.\n\n\ninitialAmount\nThe payment amount and currency.\n\n\nmerchantName\nThe name of your shop.\n\n\ninstructionsUrl\nThe URL where you shopper can get additional information and instructions about how to pay.\n\n\n\n\n\nShow voucher information to the shopper that your shopper uses to pay outside of your client.\n\n\nSend additional payment details to finish the payment flow.\n\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.paymentData\nAdditional payment data.\n\n\n\n\n\nThe shopper finishes the additional action for the payment.\n\n\nSend additional payment details to finish the payment flow.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your client, you do not get additional payment details to send. Instead, wait for the corresponding webhook message for the outcome of the payment.\n\nFrom your server, make a POST \/payments\/details request. The parameters that you must include depends on the payment method. For the parameters for an individual payment method, go to the API-only page for the individual payment method .\n\n \n\nThe response includes information about the current payment status.\n\n \n\n\n \nGet the payment outcome\nAfter the shopper finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website or app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account.\nAssess your PCI DSS compliance by submitting:\n\nthe Self-Assessment Questionnaire-A, if you are using the Custom Card Component.\nthe Self-Assessment Questionnaire-D, if you are submitting raw card data.\n\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.requiredAdd payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["React Native","API only"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Flutter&integration=Drop-in","title":"Flutter Drop-in","content":"Flutter Drop-in\nRender a list of available payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate payment methods\nUI styling customization for the list of payment methods\nAdding payment methods to the list requires no extra development time\n3D Secure 2 support built in\nDrop-in is our pre-built UI solution for accepting payments in your app. Drop-in shows all payment methods as a list, in the same block. Your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\nRequired versions:\n\niOS 12 or later.\nAndroid 5.0 or later.\nKotlin 1.8 or later.\nGradle v8 or later.\nHow it works\nFor a Drop-in integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\nThe shopper goes to the checkout screen.\nYour server uses the shopper's country and currency information from your client to get available payment methods.\nDrop-in shows the available payment methods, collects the shopper's payment details, handles the additional action, and shows the payment result to the shopper.\nYour webhook server receives the notification containing the payment outcome.\n\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. For example, when you set this to iOS, Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. Your client app also uses this locale.\n\n\n\nFor example, to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. Use this in the next step to show available payment methods to the shopper.Add Drop-in to your app\n\n \n Client app\n \n\n\n1. Add platform-specific configurations\n\n\n \n \n \n \n\n2. Create a configuration object\nCreate a configuration object with the following properties:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nenvironment\n\nUse test. When you are ready to accept live payments, change the value to one of our live environments.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, this is set to en-US. To change the language, set this to the shopper's language and country code. If you included shopperLocale in your \/payments request, Drop-in uses that one.\n\n\namount\n\nThe currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.\n\n\n\nFor example: \n\n \n\nTo add configuration for specific payment methods, create an additional configuration object. For example, for Apple Pay:\n\n \n\nOptional configuration\n\n\n\nParameter name\nDescription\n\n\n\n\npreselectedPaymentMethodTitle Only for iOS.\nWhen you have a preselected payment method, sets the title of the Drop-in overlay.\n\n\npaymentMethodNames\nIf you want to use custom names when displaying payment methods, set the name to use for each payment method.\n\n\n\n\n \n\n3. Add required callbacks\nIn an instance of AdvancedCheckout, add the following callbacks:\n\n\n\nCallback\nDescription\n\n\n\n\nonSubmit\nFrom your server, make a \/payments request. The callback returns: - data: payment data that you must pass to your server. - extra: additional information, like the shopper's shipping address, for some payment methods. This can be null if no additional information is provided.\n\n\nonAdditionalDetails\nFrom your server, make a \/payments\/details request, passing the data object from the onSubmit callback.\n\n\n\n\n \n4. Show Drop-in in your app\nCall startDropin to show the Drop-in, passing the following:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\ndropInConfiguration\n\nThe configuration object you created.\n\n\npaymentMethodsResponse\n\nThe full \/paymentMethods response.\n\n\ncheckout\n\nThe advancedCheckout that you created.\n\n\n\n\n \n\nDrop-in handles the payment flow.\n5. Dismiss Drop-in (optional)\n\n \n Client app\n \n\n\nYou can optionally implement the method to dismiss Drop-in, if this is required for your app. For example, if you want to stop showing the Drop-in UI when the shopper abandons your payment page for an extended period of time.\nUse the global AdyenCheckout.advanced.stopDropIn(); method to dismiss Drop-in. If you do not implement this method, Drop-in is automatically dismissed when the payment flow ends.\n\nIf the shopper has been redirected to a third-party app, for example to authorize the payment on an issuer-hosted website, they can still complete the payment even after you dismiss the Drop-in UI.\n\nMake a payment\n\n \n Payment server\n \n\n \n \n Client app\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, Drop-in calls onSubmit.\n\n\nFrom your server, make a POST \/payments request specifying:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete payload of the onSubmit event from your client app that includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by Drop-in to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. iOS: Use the custom URL scheme for your app. You also need to: Add the return URL handler to your AppDelegate in your native iOS layer. Configure the custom URL scheme in your Info.plist file. iOS example: com.mydomain.adyencheckout:\/\/ Android: Use the combination of: adyencheckout:\/\/ schemeYour package name Use the AdyenCheckout.instance.getReturnUrl() method to get the value, or hardcode the string. Android example: adyencheckout:\/\/com.adyen.adyen_checkout_example Format: Maximum 1024 characters. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nMap the response to one of the following \n PaymentEvent\n objects:\n\n\n\nType\nDescription\n\n\n\n\nFinished\nThe payment is finished.\n\n\nAction\nAn additional action is required. Drop-in automatically handles the additional action.\n\n\nError\nAn error has occured.\n\n\n\n\n\nPass the object to your client. The onSubmit callback expects it.\n\n\nErrors\nIf an error occurs, you get one of the following error codes:\n\n\n\nError code\nDescription\nAction to take\n\n\n\n\ncanceledByShopper\nThe shopper canceled the payment.\nTake the shopper back to the checkout page.\n\n\nnotSupported\nThe payment method isn't supported by the shopper's device.\nTell the shopper that the payment method isn't supported by their device.\n\n\nnoClientKey\nNo clientKey configured.\nTell the shopper that an error occurred.\n\n\nnoPayment\nNo payment information configured.\nTell the shopper that an error occurred.\n\n\ninvalidPaymentMethods\nCan't parse the paymentMethods list, or the list is empty.\nTell the shopper that an error occurred.\n\n\nnoPaymentMethod\nCan't find the selected payment method.\nTell the shopper that their selected payment method is currently unavailable.\n\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf the shopper performed additional actions to complete the payment, Drop-in calls onAdditionalDetails to make a POST \/payments\/details request from your server:\n\n \n\nExample responses:\n\n\n \n \n \n \n\n\n\nMap the response to a PaymentEvent object.\nPass the object from your server to your client app. The onAdditionalDetail callback expects it.\n\nIf another additional action is required, Drop-in handles it.\nIf no additional action is required, Drop-in completes the payment flow.\n\nHandle the result\n\n \n Client app\n \n\n\nWhen Drop-in completes the payment flow, you get one of the following objects:\n\n\n\nObject\nDescription\n\n\n\n\nPaymentAdvancedFinished\nThe payment was successfully submitted. Contains a resultCode with the status of the payment.\n\n\nPaymentCancelledByUser\nThe payment was canceled by the user.\n\n\nPaymentError\nThe payment encountered an error.\n\n\n\nHandle the object and inform the shopper.Get the payment outcome\nAfter Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Drop-in from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\neurope\n\n\nUnited States (US) live\nunitedStates\n\n\nAustralia (AU) live\naustralia\n\n\nAsia Pacific & Southeast (APSE) live\napse\n\n\nIndia (IN) live\nindia\n\n\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Flutter","Drop-in"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Flutter&integration=Components","title":"Flutter Components","content":"Flutter Components\nRender individual payment methods anywhere in your app.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nLow development time to integrate each payment method component\nUI styling customization for each payment method\nFlexibility to add payment method components with configuration for each\n3D Secure 2 support using the 3D Secure 2 Component\nComponents are our pre-built UI solution for accepting payments in your app. Each Component renders a payment method you can render anywhere in your app. Your server makes API requests to the \/paymentMethods, \/payments, and \/payments\/details endpoints.\nRequirements\nBefore you begin to integrate, make sure you have followed the Get started with Adyen guide to:\n\nGet an overview of the steps needed to accept live payments.\nCreate your test account.\n\nAfter you have created your test account:\n\nGet your API key.\nGet your client key.\nSet up webhooks to know the payment outcome.\n\nRequired versions:\n\niOS 12 or later.\nAndroid 5.0 or later.\nKotlin 1.8 or later.\nGradle v8 or later.\nHow it works\nFor a Components integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details. \n\nYour client app: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client app. \nYour webhook server: receives webhooks that include the outcome of each payment.\n\nThe parts of your integration work together to complete the payment flow:\n\nThe shopper goes to the checkout screen.\nYour server uses the shopper's country and currency information from your client to get available payment methods.\nThe Component collects the shopper's payment details, handles the additional action, and shows the payment result to the shopper.\nYour webhook server receives the notification containing the payment outcome.\n\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client app\n Go to the integration steps for your client app.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.\nFrom your server, make a\u00a0POST \/paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.\n\nWe use the optional parameters to tailor the list of available payment methods to your shopper.\n\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nchannel\n\nThe platform where the payment is taking place. For example, when you set this to iOS, Adyen returns only the payment methods available for iOS.\n\n\ncountryCode\n\nThe shopper's country\/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. Your client app also uses this locale.\n\n\n\nFor example, to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:\n\n \n\nThe response includes the list of available paymentMethods:\n\n \n\nPass the response to your client app. Use this in the next step to show available payment methods to the shopper.Add Components to your app\n\n \n Client app\n \n\n\n1. Add platform-specific configurations\n\n\n \n \n \n \n\n2. Create a configuration object\nCreate a configuration object with the following properties:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nenvironment\n\nUse test. When you are ready to accept live payments, change the value to one of our live environments.\n\n\nclientKey\n\nA public key linked to your API credential, used for client-side authentication.\n\n\ncountryCode\n\nThe shopper's country\/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nBy default, this is set to en-US. To change the language, set this to the shopper's language and country code. If you included shopperLocale in your \/payments request, the Component uses that one.\n\n\namount\n\nThe currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.\n\n\n\nMost payment methods use the InstantComponent that takes the InstantComponentConfiguration, so they do not have specific configuration. \nSome payment methods use another type of Component that requires specific configuration. Check the Github repo for configuration for different payment method Components.\n\n\n \n \n \n \n\n\n3. Add required callbacks\nIn an instance of AdvancedCheckout, add the following callbacks:\n\n\n\nCallback\nDescription\n\n\n\n\nonSubmit\nFrom your server, make a \/payments request. The callback returns: - data: payment data that you must pass to your server. - extra: additional information, like the shopper's shipping address, for some payment methods. This can be null if no additional information is provided.\n\n\nonAdditionalDetails\nFrom your server, make a \/payments\/details request, passing the data object from the onSubmit callback.\n\n\n\n\n \n4. Show the Component in your app\nCheck that the selected payment method is available in your \/paymentMethods response.\n\n\nFrom the list of payment methods from the \/paymentMethods response, put the selected payment method in an object of the type Map<String, dynamic>.\n\n\n \n \n \n \n\n\n\n\nThe Component handles the payment flow.Make a payment\n\n \n Payment server\n \n\n \n \n Client app\n \n\n\nWhen the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, the Component calls onSubmit.\nFrom your server, make a POST \/payments request specifying:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nThe currency of the payment and its value in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod\n\nThe complete payload of the onSubmit event from your client app that includes the payment method details and other required information.\n\n\npaymentMethod.sdkData\n\nThe object that includes information collected by the Component to track the user's payment journey, including information like the checkout attempt identifier. This is required to use the Checkout dashboard that lets you analyze your checkout performance.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. iOS: Use the custom URL scheme for your app. You also need to: Add the return URL handler to your AppDelegate in your native iOS layer. Configure the custom URL scheme in your Info.plist file. iOS example: com.mydomain.adyencheckout:\/\/ Android: Use the combination of: adyencheckout:\/\/ schemeYour package nameA path. You must add an intent filter to your Manifest.xml file with this path. This is required for Components. Android example: adyencheckout:\/\/com.adyen.adyen_checkout_example\/adyenPayment Format: Maximum 1024 characters. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\n\n applicationInfo\n\n\nIf you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.\n\n\n\n \nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, see Required risk fields.\nNative 3D Secure 2 authentication.\nCreating a token to store the shopper's payment details.\n\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\n\nMap the response to one of the following \n PaymentEvent\n objects:\n\n\n\nType\nDescription\n\n\n\n\nFinished\nThe payment is finished.\n\n\nAction\nAn additional action is required. The Component automatically handles the additional action.\n\n\nError\nAn error has occured.\n\n\n\n\n\nPass the object to your client. The onSubmit callback expects it.\n\n\nErrors\nIf an error occurs, you get one of the following error codes:\n\n\n\nError code\nDescription\nAction to take\n\n\n\n\ncanceledByShopper\nThe shopper canceled the payment.\nTake the shopper back to the checkout page.\n\n\nnotSupported\nThe payment method isn't supported by the shopper's device.\nTell the shopper that the payment method isn't supported by their device.\n\n\nnoClientKey\nNo clientKey configured.\nTell the shopper that an error occurred.\n\n\nnoPayment\nNo payment information configured.\nTell the shopper that an error occurred.\n\n\ninvalidPaymentMethods\nCan't parse the paymentMethods list, or the list is empty.\nTell the shopper that an error occurred.\n\n\nnoPaymentMethod\nCan't find the selected payment method.\nTell the shopper that their selected payment method is currently unavailable.\n\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf the shopper performed additional actions to complete the payment, the Component calls onAdditionalDetails to make a POST \/payments\/details request from your server:\n\n \n\nExample responses:\n\n\n \n \n \n \n\n\n\nMap the response to a PaymentEvent object.\nPass the object from your server to your client app. The onAdditionalDetail callback expects it.\n\nIf another additional action is required, the Component handles it.\nIf no additional action is required, the Component completes the payment flow.\n\nHandle the result\n\n \n Client app\n \n\n\nWhen the Component completes the payment flow, you get one of the following objects:\n\n\n\nObject\nDescription\n\n\n\n\nPaymentAdvancedFinished\nThe payment was successfully submitted. Contains a resultCode with the status of the payment.\n\n\nPaymentCancelledByUser\nThe payment was canceled by the user.\n\n\nPaymentError\nThe payment encountered an error.\n\n\n\nHandle the object and inform the shopper.Get the payment outcome\nAfter the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client app\n \n\n\nUse the resultCode to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account. Review the process to start accepting payments on Get started with Adyen.\nAssess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nLoad Components from one of our live environments and set the environment to match your live endpoints:\n\n\n\nEndpoint region\nValue\n\n\n\n\nEurope (EU) live\neurope\n\n\nUnited States (US) live\nunitedStates\n\n\nAustralia (AU) live\naustralia\n\n\nAsia Pacific & Southeast (APSE) live\napse\n\n\nIndia (IN) live\nindia\n\n\n\n\nNext steps\n\nrequiredModify paymentsFind out how to cancel, refund, or capture a payment using our API.Add payment methodsLearn about payment methods and how to add them to your account.TokenizationSave shopper payment details for later payments.3D Secure authenticationComply with regulations such as PSD2 SCA in Europe.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Flutter","Components"]},{"url":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration\/advanced-flow?platform=Flutter&integration=API only","title":"Flutter API only","content":"API only\nCreate your own client-side UI and use our API endpoints to get the list of available payment methods and submit a payment.\nSupported payment methods\nCards, buy now pay later, wallets, and many more.\nSee all supported payment methods\nFeatures\n\nFull control of styling on your checkout page\nYour own UI elements\nCreating your own client-side logic\n\nHandling secure card data and authentication\nYou must ensure that your integration complies with regulatory requirements such as PCI DSS and PSD2 SCA.\nWe recommend that you use our pre-built client-side solutions to securely do the following:\n\nCollect, validate, and encrypt card details: Implement our solution to handle encrypted card data with your custom UI and comply with PCI DSS regulations.\nAuthenticate transactions with 3D Secure 2: Handle the 3D Secure 2 authentication action using our solution and comply with PSD2 SCA regulations for online payments.\nWith an API-only integration, you create your own UI, implement your own client-side logic, and use our API to send and receive payment data. You have full control over the look and feel of your checkout page.\nTo reduce your development time and resources, you can use one of our pre-built UI options (Drop-in\/Components) instead.Requirements\nBefore you build your integration, take into account the following requirements and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that you have the following role: Checkout webservice role\n\n\nCustomer Area roles\nMake sure that you have one of the following roles: Merchant admin role Manage API credentials\n\n\nWebhooks\nSubscribe to the following webhook: Standard webhooks\n\n\nLimitations\nYour PCI compliance assesment determines your integration options for card payments.For 3D Secure 2 authentication for shoppers using Chrome, your cookies must use the SameSite attribute. \n\n\nSetup steps\nBefore you begin: Create your Adyen test accountGet your API key.Get your client key.Set up webhooks.If you want to process payments using raw card data, contact your Adyen Account Manager to confirm that you are eligible.\n\n\nHow it works\nFor an API-only integration, you must implement the following parts:\n\nYour payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.\nYour client: shows your custom UI where the shopper makes the payment. Passes data to and receives data from your payment server to handle the payment flow and additional actions on your client.\nYour webhook server: receives webhooks that include the outcome of each payment.\n\nIntegration steps\nThe parts of your integration work together to handle the payment flow:\n\nFrom your server, make an API request to get a list of payment methods available to the shopper.\nShow the payment form to collect the shopper's payment details in your UI.\nFrom your server, make a payment request with the data that you have collected from the shopper.\nFor some payment methods, you use your client to handle the additional action that your shopper must do. For example, you redirect your shopper to another website or show a QR code that the shopper uses to complete the payment.\nFrom your server, send additional payment details.\nGet the payment outcome.\n\nIf you are integrating these parts separately, you can start at the corresponding part of this integration guide:\n\n\n Payment server\n Go to the integration steps for your server.\n Client website or app\n Go to the integration steps for your client.\n Webhook server\n Go to the integration steps for your webhook server.\nInstall an API library\n\n \n Payment server\n \n\n\nWe provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:\n\nUse an API version that is up to date.\nHave generated models to help you construct requests.\nSend the request to Adyen using their built-in HTTP client, so you do not have to create your own.\n\n\n\n \n \n \n \n\nGet available payment methods\n\n \n Payment server\n \n\n\nWhen the shopper goes to your checkout page, get a list of the available payment methods to show the shopper.\n\n\nFrom your server, make a\u00a0POST \/paymentMethods request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nchannel\n\nWeb\n\n\ncountryCode\n\nThe shopper's country\/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nshopperLocale\n\nLanguage and country code. This is used to translate the payment methods names in the response. Default value: en-US.\n\n\n\nThe information that you include is used to filter the list of available payment methods.\n\n\n\nThe response includes the list of available payment methods, in the paymentMethods object. The payment methods are ordered by popularity in the shopper's country. For each payment method, the response contains:\n\n\n\nParameter name\nDescription\n\n\n\n\nname\nThe name of the payment method that you can show in your payment form.\n\n\ntype\nThe unique payment method code. You must include this when you make a payment.\n\n\n\n\n\n\n\n\nPass the list of available payment methods and the required input fields for each payment method to your client.\n\nBuild your payment form\n\n \n Client website or app\n \n\n\nCreate your payment form where the shopper enters their information. We recommend that you collect commonly-used shopper information in your payment form to process a transactions, depending on your type of business.\n\nSome payment methods require you to collect, or optionally accept, additional information that you include in the payment request. For the additional information you must collect in your payment form for an individual payment method, go to our API-only guide for the individual payment method.\nWe provide payment method and issuer logos that you can download and use in your payment form.\nCredit and debit card details\nBecause governing bodies and organizations regulate the handling of credit and debit card information strictly, you must make sure that you are compliant when collecting card details. When a shopper selects to pay with a card, use the integration option that corresponds to your level of PCI compliance:\n\n(Recommended) Adyen's Custom Card Component with encryption: our pre-built UI with logic to securely encrypt and handle payment card data.\nYour own UI and logic to collect and handle raw card data: before you build an integration that collects raw credit and debit card data, you must assess your PCI compliance according to the most extensive self-assessment form and contact your Adyen Account Manager to confirm that you are eligible.\n\nInformation in the payment form\nAfter collecting information in your payment form, you must add it to corresponding API parameters that you include in the payment request.\nFor example, for commonly-used information:\n\n\n\nField in the payment form\nAPI request parameter\n\n\n\n\nFirst name\nshopperName.firstName\n\n\nLast name\nshopperName.lastName\n\n\nEmail address\nshopperEmail\n\n\nBilling address (multiple fields)\nbillingAddress (object)\n\n\nShipping address (multiple fields)\ndeliveryAddress (object)\n\n\nPhone number\ntelephoneNumber\n\n\n\n \n \n \n \n \n Downloading logos\n \n \n \n \nIf you are building your own UI, we provide payment method and issuing bank logos that you can use on your checkout page. The images are available in PNG format with different sizes and screen resolutions and in SVG format.\nIf you cannot find a payment method or issuer logo, contact our Support Team.\nPayment method logos\nDownload the images from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type returned in the \/paymentMethods response. For example, googlepay or primeiropay_boleto.\nFor cards, the values you should use are specified under brands with type: scheme. For example, mc, visa, and amex. To get a generic card logo, set pm-type to card.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/mc.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/large\/googlepay@2x.png\nIssuing bank logos\nSome payment methods such as iDEAL present a list of issuing banks to the shopper.\nDownload the issuing bank logos from the links below, specifying:\n\n\nimg-size: Specify the size for PNG format. Use the following values:\n\nsmall: Image size 40x26 pixels\nmedium: Image size 77x50 pixels\nlarge: Image size 154 x 100 pixels\n\n\n\nsuffix: Specify the image density for PNG format. If not specified, the images will have the same size as the img-size. Append any of the following values:\n\n@2x\n@3x\n-ldpi\n-hdpi\n-xhdpi\n-xxhdpi\n-xxxhdpi\n\n\n\npm-type: The paymentMethods.type in objects with details.key issuer returned in the \/paymentMethods response. For example, ideal.\n\n\nissuerid: The details.items.id referring to the issuing bank. For example, 1121 and 1151 for iDEAL.\n\n\nDownload link for SVG:\n\n \n\nDownload link for PNG:\n\n \n\nExamples:\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/ideal\/1121.svg\nhttps:\/\/checkoutshopper-live.adyen.com\/checkoutshopper\/images\/logos\/small\/ideal\/1151-xxhdpi.png\n\n \n \n\nMake a payment\n\n \n Payment server\n \n\n\nAfter the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you must make a payment request to Adyen.\n\n\nPass the data from your client to your server.\n\n\nFrom your server, make a POST \/payments request including the following parameters:\n\n\n\nParameter name\nRequired\nDescription\n\n\n\n\nmerchantAccount\n\nYour merchant account name.\n\n\namount\n\nAn object with the following parameters: currency: The three-character ISO currency code.value: The value of the payment in minor units.\n\n\nreference\n\nYour unique reference for this payment.\n\n\npaymentMethod.type\n\nThe payment method type. From the \/paymentMethods response, this is the value in paymentMethod.type.\n\n\nreturnUrl\n\nThe URL where the shopper should return to after a redirection. Format: Include the protocol: http:\/\/ or https:\/\/.Maximum 1024 characters.If it includes non-ASCII characters, such as spaces or special letters, URL encode it.You can include your own additional query parameters, such as a shopper ID or order reference number. The URL must not include personally identifiable information (PII), for example name or email address. \n\n\napplicationInfo\n\nIf you are a technology partner, service partner, or system integrator, send information about the application, so that we can offer you more support.\n\n\n\n\nFor the following cases, you must include additional parameters in your request:\n\nIntegrating some payment methods. For more information, go to payment method integration guides.\nUsing our risk management features. For more information, go to data quality and risk field reference.\nCreating a token to store the shopper's payment details.\nUsing a token to make a recurring payment with stored payment details.\n\n\n\n\n\n\n\n\n\n\nYour next step depends on if the \/payments response contains an action object:\n\nIf the response has no action object, get the payment outcome.\n\nIf the response contains an action object, handle the additional action.\n\n\n\n\n\n\nHandle the additional action\n\n \n Client website or app\n \n\n\nSome payment methods require additional action from the shopper. Common examples of additional actions include:\n\nLogging in to a bank's website or app.\nAuthenticating a payment with 3D Secure 2.\nScanning a QR code.\n\n\nImplement logic to handle all action types, so that your integration can handle different payment methods. To see if an individual payment method requires an additional action, see the corresponding payment method guide for it.\n\nHow you handle the action depends on the action type (action.type):\n\n\n\nType\naction.type value\n\n\n\n\nRedirect action\nredirect\n\n\n3D Secure 2 authentication action\nthreeDS2\n\n\nQR code action\nqrCode\n\n\nSDK action\nsdk\n\n\nVoucher action\nvoucher\n\n\nAwait action\nawait\n\n\n\nRedirect action\nWhen the \/payments response includes action.type redirect, redirect the shopper to another site to complete the payment.\nHow you handle the redirect depends on if it is a payment method redirect or a 3D Secure 2 redirect.\n\n\n \n \n \n \n\n\n3D Secure 2 authentication action\nWhen the \/payments response includes action.type: threeDS2Fingerprint or threeDS2Challenge, the payment qualifies for 3D Secure 2 and it goes through the frictionless or the challenge flow. Use one of our 3D Secure 2 solutions to handle the action.\nQR code action\nWhen the \/payments response includes action.type: qrCode, the shopper must scan a QR code to complete the payment.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.qrCodeData\nContains the URL for the QR code.\n\n\n\n\n\nGet the qrCodeData from the action object. This parameter contains a URL for the QR code.\n\n\nShow the QR code to the shopper.\n\n\nThe shopper scans the QR code.\n\n\nSend additional payment details to finish the payment flow.\n\n\nSDK action\nWhen the \/payments response includes action.type: sdk, the shopper must use another UI overlay to complete the payment. For example, a payment method requires the shopper to use its specific UI to enter payment details.\n\n \n\n\n\nFrom the \/payments response, get the following from the action object:\n\n\n\nParameter\nDescription\n\n\n\n\nsdkData\nThe data that you must pass to the SDK.\n\n\n\n\n\nPass the data from the sdkData object to the SDK.\n\n\nThe shopper uses the SDK to finish the payment.\n\n\nGet the result from the SDK.\n\n\nSend additional payment details to finish the payment flow.\n\n\nVoucher action\nWhen the \/payments response includes action.type: voucher, the shopper must use a voucher to complete the payment.\n\n \n\n\n\nThe data included in the \/payments response is different for each voucher payment method. Get the available information from it. For example, for DOKU vouchers, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\nexpiresAt\nThe date when the voucher expires.\n\n\ninitialAmount\nThe payment amount and currency.\n\n\nmerchantName\nThe name of your shop.\n\n\ninstructionsUrl\nThe URL where you shopper can get additional information and instructions about how to pay.\n\n\n\n\n\nShow voucher information to the shopper that your shopper uses to pay outside of your client.\n\n\nSend additional payment details to finish the payment flow.\n\n\nAwait action\nWhen the \/payments response includes action.type: await, the shopper must take an additional action to complete the payment. For example: entering a code into their banking app.\n\n \n\n\n\nFrom the \/payments response, get the following:\n\n\n\nParameter\nDescription\n\n\n\n\naction.paymentData\nAdditional payment data.\n\n\n\n\n\nThe shopper finishes the additional action for the payment.\n\n\nSend additional payment details to finish the payment flow.\n\nSend additional payment details\n\n \n Payment server\n \n\n\nIf you handled an additional action, you must send additional payment details.\n\nFor redirects: if the shopper fails to return to your client, you do not get additional payment details to send. Instead, wait for the corresponding webhook message for the outcome of the payment.\n\nFrom your server, make a POST \/payments\/details request. The parameters that you must include depends on the payment method. For the parameters for an individual payment method, go to the API-only page for the individual payment method .\n\n \n\nThe response includes information about the current payment status.\n\n \n\n\n \nGet the payment outcome\nAfter the shopper finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.\nInform the shopper\n\n \n Client website or app\n \n\n\nUse the \n resultCode\n to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.\nUpdate your order management system\n\n \n Webhook server\n \n\n\nYou get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.\nFor a successful payment, the event contains success: true.\n\n \n\nFor an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.\n\n \nError handling\nIn case you encounter errors in your integration, refer to the following:\n\nAPI error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.\nPayment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.\nTest and go live\nBefore going live, use our list of test cards and other payment methods to\u00a0test your integration. We recommend testing each payment method that you intend to offer to your shoppers.\nYou can check the status of a test payment in your\u00a0Customer Area, under Transactions >\u00a0Payments.\nTo debug or troubleshoot test payments, you can also use API logs in your test environment.\nWhen you are ready to go live, you need to:\n\nApply for a live account.\nAssess your PCI DSS compliance by submitting:\n\nthe Self-Assessment Questionnaire-A, if you are using the Custom Card Component.\nthe Self-Assessment Questionnaire-D, if you are submitting raw card data.\n\nConfigure your live account.\u00a0\nSubmit a request to add payment methods in your live Customer Area .\nSwitch from test to our live endpoints.\n\nMake sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for \/payments and \/payments\/details requests may result in errors, for example, when authenticating with 3D Secure 2.\n\n\nrequiredSet up notificationsReceive confirmation when a payment is authorised or fails.requiredAdd payment methodsLearn about payment methods and how to add them to your account.Payment modificationsFind out how to cancel, refund, or capture a payment using our API.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Build your integration","lvl3":"Advanced flow integration guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/build-your-integration","lvl3":"\/online-payments\/build-your-integration\/advanced-flow"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Flutter","API only"]}],"articleFiles":{"payment-methods-request-android-71.js":"

payment-methods-request-android-71.js<\/p>","payment-methods-request-ios-71.js":"

payment-methods-request-ios-71.js<\/p>","payment-methods-request-web-71.js":"

payment-methods-request-web-71.js<\/p>","payments-details-request-71.js":"

payments-details-request-71.js<\/p>","payments-request-web-71.js":"

payments-request-web-71.js<\/p>"}}