Cards Drop-in integration

Add cards to an existing Drop-in integration.

This page explains how to add cards to your existing Android Drop-in integration.

This page is for v5.0.0, released in October 2023. If you are using an earlier version, use the guide for earlier versions instead.

Requirements

Select the server-side flow that your integration uses:

API reference

Drop-in Configuration

Optional configuration

You can include the following functions in the configuration object:

Configuration function	Description	Parameter
`setAddressConfiguration`	Options for address fields.	An `AddressConfiguration` object.
`setHideCvc`	If the security code (CVC/CVV) field is hidden.	`hideCvc`: Boolean Default: false.
`setHideCvcStoredCard`	If the security code (CVC/CVV) field is hidden for stored cards.	`hideCvcStoredCard`: Boolean Default: false.
`setHolderNameRequired`	If the cardholder name is required.	`holderNameRequired`: Boolean Default: false.
`setInstallmentConfiguration`	Options for installment payments.	An `InstallmentConfiguration` object.
`setKcpAuthAvailability`	Options for the security field for Korean cards.	A `KCPAuthVisibility` object. Enum values: - HIDE - SHOW
`setShopperReference`	Your unique shopper reference. This is passed back to you in the `PaymentComponentData` when the payment flow finishes.	`shopperReference`: String
`setSocialSecurityNumberVisibility`	For Brazil card payments, if the CPF/CNPJ social security number field is shown.	A `SocialSecurityNumberVisibility` object. Enum values: - HIDE - SHOW
`setSupportedCardTypes`	The card brands or types supported for the payment. While the shopper enters their card number, supported brands or types are shown on the payment form.	An array of `supportCardBrands` or `supportCardTypes`. Default: `PaymentMethod.brands`, if it exists. Otherwise, `DEFAULT_SUPPORTED_CARDS_LIST`.

For example, to add configuration to set the Postal Code field to be optional for Mastercard and JCB:

Address fields configuration

In the AddressConfiguration object, you can configure the following classes:

FullAddress: all of the address fields on the payment form. You can include the following:

Parameter	Description	Default value
`addressFieldPolicy`	If shoppers are required to fill in the fields. Possible values: - Required - Optional - OptionalForCardTypes: include the `brand` parameter, which is a list of values of data type String to specify which brands input is optional for.	Required
`defaultCountryCode`	The default country code that is selected when the payment form initializes. String value, for example, NL.	null
`supportedCountryCodes`	The supported country codes. A list of String values.

PostalCode: the Postal Code field on the payment form. You can include the following:

Parameter	Description	Default value
`addressFieldPolicy`	If shoppers are required to fill in the fields. Possible values: - Required - Optional - OptionalForCardTypes: include the `brand` parameter, which is a list of values of data type String to specify which brands input is optional for.	Required

Lookup: the address lookup functionality that suggests addresses to the shopper when they enter data into address input fields.

Implement address lookup

Drop-in includes optional callbacks that you can use to suggest addresses to the shopper when they enter data into address input fields. The callbacks work with an external application that you choose to get addresses.

There are different ways that external APIs work:

One request: one API request is required that returns a list of items with full address details. For example, you can use this with Radar.
Two requests: two API requests are required. The first returns a list of items with partial address details. After selecting an item from the list, the second request returns the full details of the selected item. For example, you can use this with Google Places.

To use the address lookup functionality, set AddressConfiguration to Lookup.

Choose the implementation you require:

Showing debit and credit cards separately

Drop-in can show separate payment forms for debit cards and credit cards. Here are example use cases for this feature:

In Brazil, Mexico, and Finland, many shoppers use combo cards that can make both debit or credit transactions. Separate forms for Debit Card and Credit Card lets the shopper choose the type of transaction.
To accept card payments in Sweden, local legislation requires you to show the debit card payment options before the credit card ones.

Combo cards

For debit transactions, we highly recommend using 3D Secure and Automatic Capture due to some issuers' restrictions.

Sweden

To comply with local legislation, set countryCode to SE in your request. Drop-in shows the payment form for Debit Card before the one for Credit Card.

Card brand recognition

When the shopper is entering their card details, Drop-in tries to recognize the card brand. When successful, Drop-in renders the brand icon and the corresponding input field for the card security code (CVC, CVV, or CID).

Co-badged cards

Co-badged cards are rendered by Drop-in according to the co-badged card regulations for the applicable regions. This means that Drop-in renders all supported brands, and allows the cardholder to choose their preferred brand.

Stored card payments

Adyen's tokenization service allows you to securely store shopper's payment details for future payments. You first need to create a token.

Accepting installment payments

Test and go live

If your client-side integration isn't ready, you can test API requests with encrypted card details by adding a test_ prefix to the test card details.

Before making live card payments:

Test your integration using our test card numbers. You can check the status of test payments in your Customer Area > Transactions > Payments.
Add the cards that you want to accept in your live Customer Area.
Before you can start accepting card payments in the live environment, you need to assess your PCI DSS compliance and submit the required Self-Assessment Questionnaire A document.