Build your own custom checkout experience using our API integration.
With our online payments API integration, you'll be able to accept key payment methods across different regions, channels, and verticals, while maintaining full control over the UI and user experience.
For many local payment methods and 3D Secure, you'll need to redirect the shopper to the payment method's website so they can complete the payment.
To accept online payments, you need an integration that can:
- Get a list of payment methods available to the shopper.
- Collect the shopper's payment details.
- Make a payment.
- Redirect the shopper to complete the payment.
- Present the payment result to the shopper.
We also recommend that you test your integration before you start accepting live payments.
Before you begin
Before you start integrating with our online payments API, make sure that you have performed the following steps:
- Sign up for an Adyen test account at https://www.adyen.com/signup.
- Get your API Key. Save a copy as you need it for API calls you make to the Adyen payments platform.
- Install one of our Libraries to connect with the Adyen APIs.
For more information on these steps, refer to Get started with Adyen.
Step 1: Get available payment methods
First, you need to present a list of available payment methods to your shopper:
- Make a
merchantAccount: Your merchant account name.
countryCode: The shopper's country.
valueof the payment.
channel: The platform of the shopper's device (specify either Android, iOS, or Web).
We use the
channelto tailor the list of payment methods to your shopper.
A list of available
paymentMethods is returned in the response. Each payment method has a:
name: Name of the payment method, which you can display to your shopper in your payments form.
type: Pass this back to indicate the shopper's chosen payment method when you make the payment.
Step 2: Collect shopper details
Before you can make a payment, you need to collect any required details from your shopper. To do this, you can either:
- Use our drop-in Components: The simplest way to collect required shopper details.
- Build your own payment form: Full control over the look and feel of your payment form.
Create your own static or dynamically generated payment form to collect required shopper details.
Components are not available for every payment method. You need to build your own form for payment methods that do not have a pre-built Component.
Collect details with Components
See sample code
Check out Components on GitHub.
They render as input fields that collect required shopper details, and provide the values you need to make a payment.
To integrate Components into your website:
Include the following script in the
Apply the following CSS file:
This styles any Components that appear in your payments form. Add your own styling by overriding the rules of this CSS file.
Add the following code to your payments page, specifying:
locale: The shopper's locale. This is used to set the language rendered in the Components. For a list of supported locales, see Localization.
originKey: The Origin Key of your website. To find out how to generate one, see How to get an Origin Key.
loadingContext: Change this to https://checkoutshopper-live.adyen.com/checkoutshopper/ when you're ready to accept live payments.
- Apple Pay
- Google Pay
- SEPA Direct Debit
We're actively building Components for more payment methods.
To accept credit card payments, for example, add the Cards Component to your payments form:
Add Components for the payment methods that you'll be accepting. We currently provide Components for:
Create a DOM element, placing it where you want the card form to be rendered:
Create an instance of the Card Component and assign a function to handle the
onChangeevent, an event that is triggered when the shopper enters their payment details. Next, mount the component:
Collect the values passed in
onChangeevent. These are the shopper details you need to make the payment.
The following example is from the card Component, which provides the payment method
typeas well as the shopper details needed to make a credit card payment:
Any sensitive shopper details, such as credit card data, is encrypted by the Component. You can safely transmit this to Adyen.
Next, use the shopper details you collected to make the payment.
Step 3: Make a payment
If you have a subscription or recurring business model, we recommend using our tokenization service. See Recurring and subscription payments for details.
- Make a
reference: Your unique reference for this payment.
paymentMethod: Specify the shopper's chosen payment method with the
type, and include the details you collected from the shopper.
returnUrl: Use to redirect the shopper back to your payments page. This is used for payment methods that require a redirect.
The example below shows how you would make a card payment using encrypted values generated by the Card Component.
If the payment is successful you receive:
pspReference: Our unique identifier for the transaction.
You can immediately present the payment result to the shopper.
We rely on webhook notifications to inform your system of payment results, changes in status, and other key communications. Receiving and handling these webhooks are key to a successful integration.
For many payment methods, you receive a redirectShopper
resultCode instead. This means you need to redirect the shopper before the payment can be completed.
Step 4: Redirect shopper
For many local payment methods, or card payments with 3D Secure, you need to redirect the shopper to a webpage or app to complete the payment. For these payment methods the
/payments response contains:
redirect.url: URL you use to redirect the shopper.
To complete a payment that requires a redirect:
Redirect the shopper to the
For 3D Secure payments, you need to POST additional fields. See Cards with 3D Secure for more information.
When the shopper has verified the payment, they return back to your website or app using the
returnUrlyou provided earlier. This is appended with a
/payments/detailsendpoint to verify the result of the payment:
If the payment was successful you receive:
pspReference: Our unique identifier for the transaction.
For some payment methods, you receive a Pending or Received
resultCodeinstead. This means we're still confirming whether the payment was successful. We provide confirmation asynchronously, in a webhook notification.
Next, let the shopper know the status of their payment by presenting the payment result.
Step 5: Present payment result
When a payment is completed you receive a
resultCode. Use this to present the shopper with the result of the payment in your website or app.
To find out more about the
resultCodes you can receive and how you can action these, see Result codes.
Testing your integration
Before 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.
You can check the status of a test payment in your Customer Area, under Transactions > Payments.
When you've completed testing, there are some additional steps you need to complete before you can accept live payments from shoppers. Refer to Getting started with Adyen for more information.
Change the domain to https://checkoutshopper-live.adyen.com/ when you're ready to accept live payments.
Recurring and subscription payments
If you have a subscription or recurring business model we recommend using our tokenization service.
To tokenize the shopper's payment details:
- When you make the payment additionally pass:
shopperReference: Your unique ID for the shopper. This acts as the container for the shopper's tokenized payment details.
If the payment is successful the response contains:
recurringDetailReference: Token representing the shopper's stored details.
recurringDetailReference. You will use this and your
shopperReferenceto make the recurring payments. For more information, see Making payments with tokens.
Set up notifications
Receive confirmation when a payment is authorised or fails.
Add payment methods
Learn about payment methods and how to integrate them.
Find out how to cancel, refund, or capture a payment using our API.