Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Payment-method icon

Card Component

Add card payments to an existing Components integration.

On this page, you can find additional configuration for adding cards to your Components 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.

Component configuration

Step 1: Create a DOM element

Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered:

 <div id="card-container"></div>

Step 2: Create an instance of the Component

Use the create method of your AdyenCheckout instance, in this case checkout, to create the Component:

const cardComponent =  checkout.create('card').mount('#card-container');

Optional configuration

When creating an instance of the Component, you can include the following optional configuration:

Field Description Default
brands Array of card brands that will be recognized. For a list of possible values, refer to Supported card types. ['mc','visa','amex']
brandsConfiguration v 4.5.0 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 have Components not show the brand logo when the card brand has been recognized. true
enableStoreDetails Set to true to show the check box for saving the card details for recurring payments. false
hasHolderName Set to true to show the input field for the card holder name. false
holderNameRequired Set to true to make the card holder name a required field. To show the field, you additionally need to set hasHolderName to true. false
positionHolderNameOnTop v 4.2.0 Renders the cardholder name field at the top of the payment form. false
hideCVC Set to true to hide the CVC field. false
socialSecurityNumberMode v 4.2.0 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 v 3.5.0 Set to true to collect the shopper's billing address. false
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 card holder 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] }}.

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

minimumExpiryDate v 4.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 v 3.15.0 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

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. Here you have the option to override your main Adyen Checkout configuration.
onLoad Called once all the card input fields have been created but are not yet ready to use.
onConfigSuccess Called once the card input fields are ready to use.
onFieldValid Called when a field becomes valid and also if a valid field changes and becomes invalid. For the card number field, it returns the last 4 digits of the card number.
onBrand Called once we detect the card brand.
onError Called in case of an invalid card number, invalid expiry date, or incomplete field. Called again when errors are cleared.
onFocus Called when a field gains or loses focus.
onBinLookup v 3.21.0 Provides the type of the card, and the brands, supportedBrands, and detectedBrands arrays. Called as the user inputs the PAN.
onBinValue v 3.10.1 Provides the BIN Number of the card (up to 6 digits), called as the user types in the PAN. Requires the client key for client-side authentication.

If you want to add optional configuration, include this in a configuration object. The following example shows how to configure the Component to collect the card holder name and billing address as required, and show a check box for saving card details for later payments:

const cardConfiguration = {
   hasHolderName: true,
   holderNameRequired: true,
   billingAddressRequired: true, // Set to true to show the billing address input fields.
   enableStoreDetails: true
};

Use the create method of your AdyenCheckout instance, in this case checkout, to create an instance of the Component. Add the configuration object if you created one.

const cardComponent = checkout.create('card', cardConfiguration).mount('#card-container');

Card brand recognition

When the shopper is entering their card details, the Component tries to recognize the card brand. When successful, the Component 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 the Component according to the European regulatory guidelines (EU IFR Regulation 2015/751 article 8). This means that the Component renders all supported brands, and allows the cardholder to choose their preferred brand. This functionality is supported in version 3.18.2 and later.

Presenting debit and credit cards separately

To learn how to present debit and credit cards separately on your payment form, choose the endpoint you're integrating:

This is the default with Components v5.0.0 or later.

Step 1:

In your POST /sessions request, include splitCardFundingSources: true.

Step 2:

In your front end create two DOM elements, placing these where you want the forms to be rendered.

When accepting payments in Sweden, present debit cards before credit cards, and label the forms clearly in order to comply with Swedish legislations.

 <h1>Debit card</h1>
 <div id="debit-container"></div>

 <h1>Credit card</h1>
 <div id="credit-container"></div>

Check if the paymentMethodsResponse loaded in your AdyenCheckout instance includes objects with fundingSource debit and credit, then mount the instances.

const debitCards = checkout.paymentMethodsResponse.paymentMethods.find(paymentMethod => paymentMethod.fundingSource === 'debit');

if (debitCards) {
  checkout.create('card', debitCards).mount('#debit-container');
}

const creditCards = checkout.paymentMethodsResponse.paymentMethods.find(paymentMethod => paymentMethod.fundingSource === 'credit');

if (creditCards) {
   checkout.create('card', creditCards).mount('#credit-container');
}

If you implemented an advanced use case, or integrated Components before v5.0.0.

Step 1:

In your POST /paymentMethods request, include splitCardFundingSources: true.

Step 2:

In your front end create two DOM elements, placing these where you want the forms to be rendered.

When accepting payments in Sweden, present debit cards before credit cards, and label the forms clearly in order to comply with Swedish legislations.

 <h1>Debit card</h1>
 <div id="debit-container"></div>

 <h1>Credit card</h1>
 <div id="credit-container"></div>

Check if the /paymentMethods response returns objects that contain fundingSource debit and credit, then mount the instances.

const debitCards = paymentMethodsResponse.paymentMethods.find(paymentMethod => paymentMethod.fundingSource === 'debit');

if (debitCards) {
  checkout.create('card', debitCards).mount('#debit-container');
}

const creditCards = paymentMethodsResponse.paymentMethods.find(paymentMethod => paymentMethod.fundingSource === 'credit');

if (creditCards) {
   checkout.create('card', creditCards).mount('#credit-container');
}

Recurring payments

Adyen's tokenization service allows you to securely store shopper's card details for recurring payments. To make recurring payments, you first need to create a shopper token, and then use the token to make future payments for the shopper.

Create a token

To store shopper's card details, set enableStoreDetails to true when adding the Card Component. This will show a check box 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 a stored card in your payment form

To show a stored card payment in your payment form:

  1. Include in your /paymentMethods request:
  • shopperReference: The unique shopper identifier that you specified when creating the token.

The /paymentMethods response includes a storedPaymentMethods array containing the stored payment methods for this shopper.

Response with stored payment methods
 {
   ...
   "storedPaymentMethods":[
     {
       "brand":"visa",
       "expiryMonth":"10",
       "expiryYear":"2020",
       "holderName":"John Smith",
       "id":"8415718415172204",
       "lastFour":"1111",
       "name":"VISA",
       "supportedShopperInteractions":[
         "Ecommerce",
         "ContAuth"
       ],
       "type":"scheme"
     },
     {
       "brand":"visa",
       "expiryMonth":"12",
       "expiryYear":"2020",
       "holderName":"John Smith",
       "id":"8315720121476805",
       "lastFour":"0008",
       "name":"VISA",
       "supportedShopperInteractions":[
         "ContAuth",
         "Ecommerce"
       ],
       "type":"scheme"
    }
  ]
 ...
 }

When creating an instance of the AdyenCheckout, pass the full /paymentMethods response to the paymentMethodsResponse object .

  1. Add stored cards to your payment form:
    a. Create a DOM element for stored payment methods, placing it where you want the form to be rendered:
    <div id="stored-card"></div>
    b. Get the stored payment method that you want to display from the checkout.paymentMethodsResponse object, and pass this when creating an instance of the Card Component:
    const storedPaymentMethod = checkout.paymentMethodsResponse.storedPaymentMethods[0];
    const card = checkout.create("card", storedPaymentMethod).mount("#stored-card");
To configure how the stored card renders in your payment form, refer to Configuring the Component.

When the shopper selects to pay, the Component calls the onChange event, which contains a state.data. If state.isValid is true, collect the state.data and pass this to your server. You'll need this to make a payment.

Make a payment with a token

When the shopper selects to pay, the Component calls the onChange 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 onChange 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/v67/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

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.
    If you want to test API calls but your client-side integration is not yet ready, add a test_ prefix to the test card credentials. Refer to test with encrypted card details.
  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