Payment-method icon

Card Component integration

Add cards to an existing Components integration.

This page explains how to add cards to your existing Components integration.

Requirements

Select the server-side flow that your integration uses:

Requirement Description
Integration type Make sure that you have built a Flutter Components integration.
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.

Components configuration

When you configure the Component, cards does not require any additional configuration.

Optional configuration

You can include the following parameters in the configuration object:

Parameter Description
holderNameRequired Set to true to require the cardholder name.
addressMode Specify which address fields are required. Possible values:
-full: require the full address.
-postalCode: require the postal code.
-none: address not required.
showCvc Set to true to show the security code (CVC/CVV/CID) in the payment form.
supportedCardTypes A list of supported card types that you recognize.
socialSecurityNumberFieldVisibility Specify if the social security number field shows. Possible values
-show: show the field.
-hide: do not show the field.
showStorePaymentMethodField Set to true to show the option to store card details for recurring payments.
showCvcForStoredCard Set to true to show the security code (CVC/CVV/CID) of stored cards.
kcpFieldVisibility For Korean cards, sets if the security field shows in the payment form. Possible values:
-show: show the field.
-hide: do not show the field.

You can refer to the CardConfiguration class in Github.

After adding the configuration object for cards, initialize and show the Component.

Showing debit and credit cards separately

Components 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:

The following example shows how to do this for a shopper in the Netherlands, making a EUR 47.00 payment.

/sessions request
Expand view
Copy link to code block
Copy code
Copy code
curl https://checkout-test.adyen.com/checkout/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. Components shows the payment form for Debit Card before the one for Credit Card.

Card brand recognition

When the shopper is entering their card details, Components tries to recognize the card brand. When successful, Components 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 the Component according to the co-badged card regulations for the applicable regions. This means that Components renders all supported brands, and allows the cardholder to choose their preferred brand.

Stored card payments

Use Adyen's tokenization feature to securely store shopper's payment details for future payments.

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.

Showing stored payment methods in your payment form

To show stored payment methods in your payment form:

  1. Include in your /sessions request:

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

    The /paymentMethods response includes the stored payment methods for this shopper.

  2. Pass the API response to your client-side app.

  3. When you launch and show the Component, use the stored payment methods.

Making a payment with stored payment details

When the shopper pays, the Component uses the token for the shopper's payment details. You can also use tokens to make shopper-not-present payments for subscriptions or contracts.

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:

  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.

  3. 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.

See also