In-app quick integration
Before starting with this integration, make sure that you created a test account, as described in the Getting started tutorial.
To start accepting card payments, you must first create a web service user to connect to the Adyen platform. For this:
- Go to Adyen Customer Area (CA), open Settings → Users → ws@Company.YourCompany, and click Generate Password. Save this password for future use in a secure place.
- To get the public key and URL to your encryption library, locate the Easy Encryption pane and click Generate.
Then you are able to set up your mobile app and the server. The diagram below briefly explains the flow of a payment made with a card.
For iOS, this can be done using CocoaPods, which you need to have installed on your machine.
If you already have CocoaPods, do the following:
In your existing Xcode project, add this line to your Podfile:
To complete the installation, execute the following in your terminal:
To update, execute the following in your terminal:
For Android, you can use the de.undercouch.download plugin for downloading the binaries of the Adyen Mobile SDK.
To enable this plugin, add the following code to the root directory's
In the app module's
build.gradlefile, add the following task:
Run this task using
./gradlew downloadAdyenLibrarycommand to download the
adyenpaysdk.aarfiles to you
Finally, add the following snippet in your
build.gradleof the app module:
For the Checkout screen in your mobile application, add this code that should be triggered when a shopper presses the Pay button.
Make sure to URL-encode the
encryptedCard value before sending it from the app to your server, as the
encryptedCard is generated by the CSE library and must be exactly the same as you send it from the server to the Adyen API.
For your mobile application to be able to communicate with the Adyen platform, your server must provide an interface to accept encrypted data from your mobile application and send it to the Adyen platform. Below is the example of the URLs that should be exposed by your server:
For security reasons you have to make sure the app (user) is authenticated on your server. For example, we advise using OAuth 2.0 for authentication.
To see the sample implementation of this functionality, refer to https://github.com/Adyen/adyen-php-api-library.
After the encrypted payment data reaches your server, you should pass it to our test endpoint to authorize a payment. For this, make sure to include your valid web service credentials when making the request.
The following example shows a basic authorize request with data passed in JSON format.
The amount is specified in minor units (in this case, 20000 is 200 euros), the number of decimal points per currency can be found in the currency codes topic. You can use one of our test credit cards to make the request.
To know more about making authorize requests for card payments, refer to API reference.
After the request from your server passes initial validation, the Adyen platform performs a risk analysis. If the calculated risk score for the submitted payment satisfies your current risk settings, Adyen attempts to authorize this payment.
As an outcome, you receive a payment response, which includes a PSP reference to uniquely identify each payment. You can store this reference in your server database and use it later to refer to this specific transaction (for instance, to cancel or refund it, if needed).
For other possible response codes and fields of the payment response, refer to API Reference.
Local payment methods
Local payment methods can vary per country or region. Some examples of local payment methods are direct bank transfer, eWallets, or mobile payments. To know which methods can be enabled for you, contact Adyen Support Team.
In mobile applications, you can support local payment methods in a browser. Since some payment methods restrict WebView in mobile apps for security reasons, we recommend using the following approaches in your app:
The flow of a payment using a local payment method is illustrated in the diagram below.
To process local payment methods:
- Create a new skin and style the form to let your shopper select a payment method. Go to Adyen Customer Area (CA) → Skins → Create a new skin .
- Add the skin description.
- Generate the HMAC keys for the test and live platforms (remember to take a note of this key) and click Save.
- Select the skin from the list and click Test from the menu bar to verify that Currently on Test displays the version information in green.
Request local payment methods
To retrieve a list of available local payment methods make a lookup request to the directory endpoint with the fields in the code example. For Adyen to verify the authenticity of the request calculate the signature of the request and include this in the
The example below shows how to make such a request. For additional fields and more details for the payment methods request refer to the API Reference.
Display local payment methods
A response returns a JSON object containing a list of applicable payment methods. Each payment method has a
logo, and optionally, a list of issuers (depending on the payment method). In this case, the
issuerId identifies a specific issuer and can be used to direct a shopper to the related method's webpage.
When parsing this response, you can format and display the methods according to your design if you like.
Submit a payment request
After your shopper selects the local payment method, make a GET request including the
issuerId (if available) of the selected payment method.
Recalculate the signature of your payment request with the
issuerId as extra fields and post the request to the
skipDetails.shtml endpoint. Your shopper is then redirected to the selected local method to finalize the payment.
After shoppers have completed the payment, they are redirected to a result page of your choice. You can set a custom result URL in the Customer Area on the skin configuration page. Another option is to include the result URL in the
resURL field in the payment request.
Adyen appends parameters to this result URL to inform you about the payment status. If the status is already determined (either authorised or refused), you can use this information to display a payment successful or payment failed page. In a case when the current status is pending, use payment notifications to get the outcome of a payment request and store this result in your back office, if necessary.
An example of a redirect URL to your app:
An example of a corresponding
To ensure that the response is not tampered with validate the response by calculating the signature of the returned fields, except the merchantSig field. Adyen uses your secret HMAC key to sign the data, so the calculated signature should be the same as the
merchantSig included in the response.
For more information on additional response fields, visit the API Reference.
Complete the payment
You can opt for automatic or manual capture - for instance, if you are processing more than a handful of payments on a daily basis we recommend that you automate this process. The Adyen Customer Area (CA) offers an option to configure an automated capture process to automatically capture payments after a specified number of days, ranging from no delay, 1 day, 2 days, 3 days, 4 days, 5 days, 6 days, 7 days, and manual. To define a capture delay, go to CA → Settings → Merchant Setting → Capture Delay.
To manually capture an authorized payment, send a request to the capture endpoint passing the fields as in the example below. To uniquely identify the payment to be captured, pass the PSP reference (e.g. 9914430855683260) that is returned to you in the authorise payment response.
Besides synchronous responses, Adyen uses notifications to keep you updated about actions and their result (e.g. a payment authorization). In addition, notifications help you synchronize your back-office system to always have up-to-date information on payment statuses.
It is mandatory for you to integrate with Adyen notifications when testing your integration. For more information, refer to Notifications.
Cancel and/or refund
Sometimes you may need to cancel or refund a payment. To know how this can be done with the Adyen platform, refer to Cancel or refund.
Enable recurring payments
If your business model requires billing your customers on a recurring basis, you may enable recurring payments using the Adyen platform. In this case, Adyen securely stores payment details when you make the first authorisation call, so that you no longer need to provide this data in the future.
To do this, add the recurring field to the payment request you make from your server to the Adyen platform. For example, if you want to enable both shopper-not-present and one-click recurring modes for a specific payment, add the following field to the API call above:
For more information on recurring payments, refer to the Recurring payments.