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:
Requirement | Description |
---|---|
Integration type | Make sure that you have built a Sessions flow Android Drop-in integration. The minimum required version is 5.0.0. |
Setup steps | Before you begin, add cards in your Customer Area. |
API reference
When you make the /sessions
request, cards does not require any additional fields.
Drop-in Configuration
When you configure Drop-in, cards does not require any additional 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 : BooleanDefault: false. |
setHideCvcStoredCard |
If the security code (CVC/CVV) field is hidden for stored cards. | hideCvcStoredCard : BooleanDefault: false. |
setHolderNameRequired |
If the cardholder name is required. | holderNameRequired : BooleanDefault: 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:
// Create an addressConfiguration object to configure the postal code field. val addressConfiguration = AddressConfiguration.PostalCode( addressFieldPolicy = AddressConfiguration.CardAddressFieldPolicy.OptionalForCardTypes( brands = listOf("mc", "jcb") // List of the brands that the Postal Code field is optional for. ) ) // Create a configuration object. val checkoutConfiguration = CheckoutConfiguration( environment = environment, clientKey = clientKey, ) { // Optional: add or change default configuration for the card payment method. card { setAddressConfiguration(addressConfiguration) // Optional additional configuration for address fields. } }
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 thebrand
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 thebrand
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.
After adding configuration to Drop-in, create the checkout session.
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:
To let your shoppers use the address lookup functionality:
-
In your
DropInService
, implement theonAddressLookupQueryChanged(query: String)
callback to make an API request to the address lookup API you use with thequery
parameter. -
Map the values you receive in the response to an array of
LookupAddress
objects that include the following:Field Required Description id
The unique identifier for this address search result. name
The name of the item that shows up in the list of suggested addresses. street
The name of the street. houseNumberOrName
The number or name of the house. postalCode
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries/regions. city
The name of the city. country
The two-character ISO-3166-1 alpha-2 country code. For example, US. If you do not collect the shopper's country/region, use the placeholder ZZ. stateOrProvince
Required for Android The two-character ISO 3166-2 state or province code. For example, CA (California) in the US or ON (Ontario) in Canada. apartmentSuite
The name or number of the apartment/suite. -
Pass the lookup result to Drop-in using the
AddressLookupDropInServiceResult
class.
For example:Your DropInServiceExpand viewCopy link to code blockCopy codeclass YourDropInService : DropInService() { // Implement the callback to suggest addresses to your shopper. override fun onAddressLookupQueryChanged(query: String) { // Make an API request to your desired endpoint. // Map the LookupAddress object fields to address objects. // Pass it back to Drop-in. sendAddressLookupResult(AddressLookupDropInServiceResult.LookupResult(options)) } }
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.
When you make a /sessions request from your server, include:
- splitCardFundingSources: Set to true.
The following example shows how to do this for a shopper in the Netherlands, making a EUR 47.00 payment.
curl https://checkout-test.adyen.com/v70/sessions \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "countryCode": "NL", "amount": { "currency": "EUR", "value": 4700 }, "splitCardFundingSources": true }'
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.
Storing the shopper's payment details
Include the storedPaymentMethodMode
parameter in your /sessions request. Possible values:
Value | Description |
---|---|
disabled (default) | Do not store payment details. |
askForConsent | If shopperReference is included in the request, show a checkbox in the payment form that the shopper can select to store their payment details. |
enabled | If shopperReference is included in the request, store the shopper's payment details without showing a toggle. For example, use this for a page where the shopper enters their details for a subscription service that charges the shopper on a recurring basis. |
If you or the shopper chooses to store payment details, Adyen creates a token for the shopper's payment details when the shopper pays.
Making a payment with stored payment details
When the shopper pays, Drop-in uses the token for the shopper's payment details. You can also use tokens to make shopper-not-present payments for subscriptions or contracts.
Accepting installment payments
If you want to accept credit card installments, include in the /sessions request, include the installmentOptions
object which includes the following fields:
Field | Required | Description |
---|---|---|
values |
An array of the number of installments that the shopper can choose. | |
preselectedValue |
The preselected number of installments in the payment form. | |
plans |
An array that shows the types of installment plans that the shopper can choose. Possible values: regular and revolving. If not included, the default is regular. |
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.