Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
Payment-method icon

Cards Drop-in integration

Add cards to an existing Drop-in integration.

On this page, you can find additional configuration for adding cards to your Drop-in integration.

Before you begin

This page assumes you've already:

API reference

You don't need to send additional fields for cards. To see optional fields that you can send for all payment methods, choose the endpoint you integrated:

You can also send additional fields for specific use cases, for example if you want to present debit and credit cards separately.

Presenting debit and credit cards separately

Select which endpoint you're integrating:

This is the default with Drop-in v5.0.0 or later.

To split debit and credit cards in your payment form, include in your POST /sessions request splitCardFundingSources: true.

Drop-in then automatically renders separate payment forms for Credit card and Debit card. If you sent a request with countryCode of SE, Drop-in automatically presents Debit Card before Credit Card, in order to comply with Swedish legislations.

Drop-in configuration

Optional configuration

When creating an instance of Drop-in, you can include a configuration object with the following parameters:

Field Description Default
name String that is used to display the payment method name to the shopper. Depends on the shopperLocale specified in /paymentMethods request.
showStoredPaymentMethods Set to false if you don't want Drop-in to show previously stored payment methods in the payment method list. true
brands Array of card brands that will be recognized. For a list of possible values, refer to Supported card types. ['mc','visa','amex']
brandsConfiguration
v4.5.0 or later
Object where you can customize the icons for different brands. For example, to customize the icon for Visa, include inside the brandsConfiguration:
visa: { icon: 'https://...' }

showBrandIcon Set to false to not show the brand logo when the card brand has been recognized. true
showBrandsUnderCardNumber
v5.12.0 or later
Shows brand logos under the card number field when the shopper selects the card payment method.

This setting also shows a maximum of 4 brand logos in the list of payment methods. If you support more than 4 brands, it shows 3 brand logos and the number of additional supported brands.
true
enableStoreDetails Set to true to show the checkbox for saving the card details for recurring payments. false
hasHolderName Set to true to show the input field for the cardholder name. false
holderNameRequired Set to true to make the cardholder name a required field. To show the field, you additionally need to set hasHolderName to true. false
positionHolderNameOnTop
v4.2.0 or later
Renders the cardholder name field at the top of the payment form. false
hideCVC Set to true to hide the CVC field. false
configuration.socialSecurityNumberMode
v4.2.0 or later
Renders a social security number field. For example, this is required for certain card payments in Brazil. Possible values are:
- show: Always renders the field.
- hide: Never renders the field.
- auto: Renders the field based on the card's BIN.
auto
styles Set a style object to customize the card input fields.
For a list of supported properties, refer to Styling card input fields.
Refer to
Default styles and labels.

billingAddressRequired Set to true to collect the shopper's billing address and mark the fields as required. false
billingAddressMode
v5.14.0 or later
If billingAddressRequired is set to true, you can set this to partial to require the shopper's postal code instead of the full address. If billingAddressRequired is false: none.
If billingAddressRequired is true: full.

billingAddressAllowedCountries Specify allowed country codes for the billing address. For example, ['US', 'CA', 'BR']. The Country field dropdown menu shows a list of all countries.
data Object that contains placeholder information that you can use to prefill fields.
For example:
- holderName: Placeholder for the cardholder name field.
- billingAddress: Object that contains placeholder information for the billing address such as street, postalCode, city, country, and stateOrProvince.
Empty
installmentOptions If you want to offer credit card installments, specify here the numbers of monthly installments that the shopper can choose from.
For example, to have 2, and 3, and 4 as the default installment options for all cards:
{ "card": { "values": [2, 3, 4] }}.

Added in v3.15.0:
You can also configure plans for Japanese installments: regular, revolving, or both.
Refer to Show installment payment options for a code sample.
Added in v3.15.0:
plans: regular

minimumExpiryDate
 v4.3.0 or later
If a shopper enters a date that is earlier than specified here, they will see the following error:
"Your card expires before check out date."
Format: mm/yy

showInstallmentAmounts
v3.15.0 or later
If you want to offer credit card installments, set to true to show the payment amount per installment.
Refer to Show installment payment options for a code sample.
false
autoFocus Automatically move the focus from date field to the CVC field.

v5.8.0 or later:
the focus also moves to the date field when the entered card number reaches the expected length.
true
SRConfig Object for configuring screen reader behavior. Does not affect what gets rendered in the checkout form.
SRConfig.collateErrors Indicates if all errors in the form are read out after each validation. For example, if there is an error in the card number field, the error is read out after validating each of the other fields, until the error is fixed. true
SRConfig.moveFocus Indicates if focus automatically switches to the first field with an error when the shopper selects the Pay button.
Can only be set if SRConfig.collateErrors is true.
false

Events

You can also customize your shopper's experience when specific events occur.

Event Description
onChange Called when the shopper enters data in the card input fields.
onLoad Called when all card input fields have been created but are not yet ready to use.
onConfigSuccess Called when all card input fields are ready to use.
onFieldValid Called when a field becomes valid, and if a valid field changes and becomes invalid. When the card number field is valid, it returns:
- the last 4 digits of the card number.
- v5.10.0 or later: the first 8 digits of the card number, in the issuerBin prop.

onBrand Called when Drop-in detects the card brand.
onError Called when Drop-in detects an invalid card number, invalid expiry date, or incomplete field. Called again when errors are cleared.
Starting from v5.0.0, the onError handler is no longer used only for card component related errors, and returns an object for every component.

onFocus Called when focus moves to or away from a field.
onBinLookup
v3.21.0 or later
Called as the shopper types in the card number. Provides the type of the card, and the brands, supportedBrands, and detectedBrands arrays.
onBinValue
v3.10.1 or later
Called as the shopper types in the card number. Requires the client key for client-side authentication. It returns the first six digits of the card number.

Including optional configuration

If you want to add optional configuration, include this in a configuration object. The following example shows how to configure Drop-in to collect the cardholder name and billing address as required, and customize the icon for Visa:

const cardConfiguration = {
   hasHolderName: true,
   holderNameRequired: true,
   billingAddressRequired: true, // Set to true to show the billing address input fields.
   brandsConfiguration: {
     visa: {                // Customize the icon for Visa
       icon: 'https://...' }
   }
};

If you created a cardConfiguration object, include this when creating a configuration object:

AdyenCheckout configuration
const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    card: cardConfiguration
  }
};

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-branded cards

Co-branded cards issued in Europe are rendered by Drop-in according to the European regulatory guidelines (EU IFR Regulation 2015/751 article 8). This means that Drop-in renders all supported brands, and allows the cardholder to choose their preferred brand. This functionality is supported in version 3.18.2 and later.

Stored card payments

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

Create a token

To store shopper's card details, set enableStoreDetails to true when adding the Card Component. This will show a checkbox to your shopper for saving their card details for future payments.

If the shopper chooses to save their card details when making a payment, the onChange (or onSubmit) method from the Component will include a state.data.storePaymentMethod. Pass this to your server.

To create a token, include in your /payments request:

  • storePaymentMethod: The state.data.storePaymentMethod from your front end.
  • shopperReference: Your unique identifier for the shopper.

Show stored cards


To show stored cards in your payment form, include in your /paymentMethods request:

  • shopperReference: The unique shopper identifier that you specified when creating the token.

If you don't want to show previously stored payment methods in the Drop-in payment method list, set showStoredPaymentMethods to false when creating an instance of Drop-in.

Optional configuration

You can configure the following for stored cards:

Field Description Default
hideCVC Set to true to hide the CVC field. false
styles Set a style object to customize the styling of card fields. See default styles and labels.
installmentOptions If you want to offer credit card installments, specify here the numbers of monthly installments that the shopper can choose from.
For example, to have 2, and 3, and 4 as the default installment options for all cards:
{ "card": { "values": [2, 3, 4] }}.

Added in v3.15.0:
You can also configure plans for Japanese installments: regular, revolving, or both.
Added in v3.15.0:
plans: regular
minimumExpiryDate
 Added in v4.3.0
If a shopper enters a date that is earlier than specified here, they will see the following error:
"Your card expires before check out date."
Format: mm/yy
showInstallmentAmounts
 Added in v3.15.0
If you want to offer credit card installments, set to true to show the payment amount per installment. false


Add the configuration to the configuration object of your AdyenCheckout instance.

Add stored card configurations to the configuration object
const configuration = {
  //...other configuration parameters
  paymentMethodsConfiguration: {
    storedCard: {
      hideCVC: true,
      styles: //your styles for stored cards
    }
  },
};

Make a payment with a token


When the shopper selects to pay, Drop-in calls the onSubmit event, which contains a state.data.

  1. Pass the state.data to your server.
  2. From your server, make a /payments request, specifying:
    • paymentMethod: The state.data.paymentMethod from the onSubmit event.
    • shopperReference: The unique shopper identifier that you specified when creating the token.
    • shopperInteractionContAuth.
    • recurringProcessingModel: CardOnFile.
    Payment request with a token
    curl https://checkout-test.adyen.com/v68/payments \
    -H "X-API-key: [Your API Key here]" \
    -H "Content-Type: application/json" \
    -d '{
     "amount":{
       "value":2000,
       "currency":"USD"
     },
     "paymentMethod":{
       "type":"scheme",
       "storedPaymentMethodId":"8415718415172204",
       "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH..."
     },
     "reference":"YOUR_ORDER_NUMBER",
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "returnUrl":"...",
     "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
     "shopperInteraction":"ContAuth",
     "recurringProcessingModel":"CardOnFile"
    }'

The /payments response contains:

Response
{
   "pspReference": "8815329842815468",
   "resultCode": "Authorised"
}

You can also use tokens to make shopper-not-present payments for subscriptions or contracts. For more information, refer to Making a payment for a subscription or contract.

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.

v5.20.0 or later: Card input fields use JSON Web Encryption, so your test environment must be a secure context. Use either a local or https domain, and add it to your allowed origins.


Before making live card payments:

  1. Test your integration using our test card numbers. You can check the status of test payments in your Customer Area > Transactions > Payments.
  2. Add the cards that you want to accept in your live Customer Area.
  1. 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. For more information, refer to PCI DSS compliance guide.

See also