Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Custom Card Component

Use our Custom Card Component to build your own card input fields.

Use our Custom Card Component as a PCI-compliant way to securely collect and encrypt card details.

If you'd rather not build your own card input fields, use our Card Component or Drop-in solution instead.

Before you begin

These instructions explain how to add card payments to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.

Before starting your integration:

  1. Make sure that you have set up your back end implementation.
  2. Add the cards that you want to support in your test Customer Area.

Show the available cards in your payment form

For information about the supported countries and currencies for each card, refer to Payment methods.

  1. Specify in your /paymentMethods request a combination of countryCode and amount.currency, and use the /paymentMethods response to determine which cards are available to the shopper. For more information, refer to our API-only integration guide.

  2. Include the following script in the <body> above any other JavaScript in your checkout page: 

    <script src="https://checkoutshopper-live.adyen.com/checkoutshopper/sdk/3.3.0/adyen.js"></script>
  3. Use the following CSS file:

    <link rel="stylesheet" href="https://checkoutshopper-live.adyen.com/checkoutshopper/sdk/3.3.0/adyen.css"/>

    You can add your own styling by overriding the rules of this CSS file. For more information, refer to Styling.

  4. Create an instance of AdyenCheckout, specifying the following parameters:

    Parameter Description
    locale The shopper's locale. This is used to set the language rendered in the Components. For a list of supported locales, see Localization.
    originKey The Origin Key of your website. To find out how to generate one, see How to get an Origin Key.
    environment When you're ready to accept live payments, change the value to one of our live environments
    onChange Specify a function to handle the onChange event that the Component calls after the shopper provides the required card details.
    Alternatively, you can use our pre-built Pay button, together with the onSubmit event. For more information, refer to Using the Pay button.
       function handleOnChange(state, component) {
           state.isValid // True or false. Specifies if all the information that the shopper provided is valid.
           state.data // Provides the data that you need to pass in the `/payments` call.
           component // Provides the active component instance that called this event.
       }
    
       const configuration = {
           locale: "en_US",
           environment: "test",
           originKey: "YOUR_ORIGIN_KEY",
           onChange: handleOnChange
       };
    
       const checkout = new AdyenCheckout(configuration);
  5. Implement callbacks to handle the following events triggered by the Custom Card Component:

    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 specific field is validated and encrypted or becomes invalid.
    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.
    onBinValue Provides the BIN Number of the card (up to 6 digits), called as the user types in the PAN.
  6. Add the Custom Card Component to your payment form:

    a. Create a DOM element, placing it where you want the card input fields to be rendered:

    <div id="customCard-container">
        <label>
            <span>Card number:</span>
            <span data-cse="encryptedCardNumber"></span>
        </label>
        <label>
            <span>Expiry date:</span>
            <span data-cse="encryptedExpiryDate"></span>
        </label>
        <label>
            <span>CVV/CVC:</span>
            <span data-cse="encryptedSecurityCode"></span>
        </label>
    </div>

    b. Create an instance of the Custom Card Component, and mount it. You can also include optional configuration.

    Field Description Default
    ariaLabels Specify aria attributes for the input fields for web accessibility. Refer to Default labels.
    autoFocus Automatically shift the focus from date field to the CVC field. true
    brands Array of card brands that will be recognized by the component. For a list of possible values, refer to Supported card types. ['mc','visa','amex']
    styles Set a style object to customize the input fields. For a list of supported properties, refer to Styling. Refer to Default styles.
    const customCard = checkout.create('securedfields', {
        // Optional configuration
        type: 'card',
        brands: ['mc', 'visa', 'amex', 'bcmc', 'maestro'],
        styles: {
            error: {
                color: 'red'
            },
            validated: {
                color: 'green'
            },
            placeholder: {
                color: '#d8d8d8'
            }
        },
        ariaLabels: {
            lang: 'en-GB',
            encryptedCardNumber: {
                label: 'Credit or debit card number field'
            }
        },
        // Events
        onChange: function() {},
        onValid : function() {},
        onLoad: function() {},
        onConfigSuccess: function() {},
        onFieldValid : function() {},
        onBrand: function() {},
        onError: function() {},
        onFocus: function() {},
        onBinValue: function(bin) {}
    }).mount('#customCard-container');

Make a payment

When the shopper selects to pay, the Component calls the onChange event, which contains a state.data.

  1. If state.isValid is true, collect the state.data and pass this to your server.
  2. From your server, make a /payments request, specifying:

    • paymentMethod: The state.data.paymentMethod from the onChange event.

curl https://checkout-test.adyen.com/v50/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"USD",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "{hint:state.data.paymentMethod from onChange or onSubmit}paymentMethod{/hint}": {
    "type": "scheme",
    "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "holderName": "S. Hopper"
  },
  "returnUrl": "https://your-company.com/...",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"
 
response = adyen.checkout.payments({
  :amount => {
    :currency => "USD",
    :value => 1000
  },
  :reference => "YOUR_ORDER_NUMBER",
  :paymentMethod => {
    :type => "scheme",
    :encryptedCardNumber => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryMonth => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryYear => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedSecurityCode => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :holderName => "S. Hopper"
  },
  :returnUrl => "https://your-company.com/...",
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})
// Set your X-API-KEY with the API key from the Customer Area.
Client client = new Client(xApiKey,Environment.TEST);
 
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
Amount amount = new Amount();
amount.setCurrency("USD");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
String encryptedCardNumber = "adyenjs_0_1_18$...encryptedCardNumber";
String encryptedExpiryMonth = "adyenjs_0_1_18$...encryptedExpiryMonth";
String encryptedExpiryYear = "adyenjs_0_1_18$...encryptedExpiryYear";
String encryptedSecurityCode = "adyenjs_0_1_18$...encryptedSecurityCode";
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.addEncryptedCardData(encryptedCardNumber,encryptedExpiryMonth, encryptedExpiryYear, encryptedSecurityCode, "S. Hopper");
paymentsRequest.setReturnUrl("https://your-company.com/...");
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "USD",
    "value" => 1000
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "paymentMethod" => array(
    "type" => "scheme",
    "encryptedCardNumber" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "holderName" => "S. Hopper"
  ),
  "returnUrl" => "https://your-company.com/...",
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);
#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
   'amount': {
      'value': 1000,
      'currency': 'USD'
   },
   'reference': 'YOUR_ORDER_NUMBER',
   'paymentMethod': {
      'type': 'scheme',
      'encryptedCardNumber': 'adyenjs_0_1_18$MT6ppy0FAMVMLH...',
      'encryptedExpiryMonth': 'adyenjs_0_1_18$MT6ppy0FAMVMLH...',
      'encryptedExpiryYear': 'adyenjs_0_1_18$MT6ppy0FAMVMLH...',
      'encryptedSecurityCode': 'adyenjs_0_1_18$MT6ppy0FAMVMLH...',
      'holderName': 'S. Hopper'
   },
   'returnUrl': 'https://your-company.com/...',
   'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})
// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var amount = new Model.Checkout.Amount("USD", 1000);
var details = new Model.Checkout.DefaultPaymentMethodDetails{
  Type = "scheme",
  EncryptedCardNumber = "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
  EncryptedExpiryMonth = "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
  EncryptedExpiryYear = "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
  EncryptedSecurityCode = "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
};
var paymentsRequest = new Model.Checkout.PaymentRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  Amount = amount,
  ReturnUrl = @"https://your-company.com/...",
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  PaymentMethod = details
};

var paymentResponse = checkout.Payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    amount: { currency: "USD", value: 1000 },
    paymentMethod: {
        type: 'scheme',
        encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedExpiryMonth: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedExpiryYear: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        holderName: "S. Hopper",
        encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
    },
    reference: "YOUR_ORDER_NUMBER",
    merchantAccount: config.merchantAccount,
    returnUrl: "https://your-company.com/..."
}).then(res => res);

The /payments response contains:

  • pspReference: Our unique identifier for the transaction.
  • resultCode: Use this to present the payment result to your shopper.
  • merchantReference: The reference from the /payments request.
  • additionalData: Additional information about the transaction.
    To specify the fields that you want to receive in additionalData, log in to your Customer Area, and go to Account > API URLs > Additional data settings.

{
  "additionalData": {
    "cardSummary": "1111"
  },
  "pspReference": "851572424333194G",
  "resultCode": "Authorised",
  "merchantReference": "YOUR_ORDER_NUMBER"
}

Present the payment result

Use the resultCode from the /payments response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a notification webhook.

For card payments, you can receive the following resultCode values:

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
If you are using manual capture, you also need to capture the payment.
Cancelled The shopper cancelled the payment. Ask the shopper whether they want to continue with the order, or request that they select a different payment method.
Error There was an error when the payment was being processed. For more information, check the refusalReason field. Inform the shopper that there was an error processing their payment.
Refused The payment was refused. For more information, check the refusalReason field. Ask the shopper to try the payment again using a different payment method.
Additional resultCode values are possible in case of the 3D Secure authentication flow. For more information, refer to Result codes.

Styling

All card input fields on the Custom Card form are represented as iframe elements, which securely capture payment data from your shoppers. Use JavaScript to style the fields:

  1. Create an object and set the following CSS values: 

    You can provide styling for the following:

    • base: Base styling applied to the iframe. All styling extends from this style.
    • error: Styling applied when a field fails validation.
    • placeholder: Styling applied to the field's placeholder values.
    • validated: Styling applied once a field passes validation.

    Here is an example style object:

    // Define style object
    var styleObject = {
      base: {
        color: 'black',
        fontSize: '16px',
        fontSmoothing: 'antialiased',
        fontFamily: 'Helvetica'
      },
      error: {
        color: 'red'
      },
      placeholder: {
        color: '#d8d8d8'
      },
      validated: {
        color: 'green'
      }
    };
  2. Style the elements with the following properties. These properties map to CSS properties and accept allowed CSS values:

    JavaScript CSS

    background

    background

    caretColor

    caret-color

    color

    color

    display display

    font

    font

    fontFamily

    font-family

    fontSize

    font-size

    fontSizeAdjust

    font-size-adjust

    fontSmoothing

    font-smoothing

    fontStretch

    font-stretch

    fontStyle

    font-style

    fontVariant

    font-variant

    fontVariantAlternates

    font-variant-alternates

    fontVariantCaps

    font-variant-caps

    fontVariantEastAsian

    font-variant-east-asian

    fontVariantLigatures

    font-variant-ligatures

    fontVariantNumeric

    font-variant-numeric

    fontWeight

    font-weight

    letterSpacing

    letter-spacing

    lineHeight

    line-height

    mozOsxFontSmoothing

    moz-osx-font-smoothing

    mozTransition

    moz-transition

    outline

    outline

    opacity

    opacity

    padding

    padding

    textAlign

    text-align

    textShadow

    text-shadow

    transition

    transition

    webkitFontSmoothing

    webkit-font-smoothing

    webkitTransition

    webkit-transition

Default styles and labels

If you don't provide configuration for styles and labels, the Component will use the following default properties.

{
    styles: {
            base: {
                color: "#001b2b",
                fontSize: "16px",
                fontWeight: "400"
            },
            placeholder: {
                color: "#90a2bd",
                fontWeight: "200"
            },
            error: {
                color: "#001b2b"
            }
    },
    ariaLabels: {
        lang: "en-GB",
        encryptedCardNumber: {
            label: "Credit or debit card number",
            iframeTitle: "Iframe for card data input field"
        },
        encryptedExpiryDate: {
            label: "Credit or debit card expiration date",
            iframeTitle: "Iframe for card data input field"
        },
        encryptedSecurityCode: {
            label: "Iframe for card data input field"
        }
    }
}

Supported card types

Use the values in this list when specifying card types in the brands array. If card types are not provided, the configuration defaults to ['mc','visa','amex']

Card Type Description
amex Amex
argencard Argencard
bcmc Bancontact/Mister Cash
bijcard de Bijenkorf Card
cabal Cabal
cartebancaire Carte Bancaires
codensa Codensa
cup China Union Pay
dankort Dankort
diners Diners Club
discover Discover
elo ELO
forbrugsforeningen Forbrugsforeningen
hiper HiperCard
hipercard HiperCard
jcb JCB
karenmillen Karen Millen GiftCard
laser Laser
maestro Maestro
maestrouk Maestro UK
mc Mastercard
mcalphabankbonus Alpha Bank Mastercard Bonus
mir MIR
naranja Naranja
oasis Oasis GiftCard
shopping Tarjeta Shopping
solo Solo
troy Troy
uatp UATP
visa Visa
visaalphabankbonus Alpha Bank Visa Bonus
visadankort Visa Dankort
warehouse Warehouse GiftCard

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, include in your /payments request:

  • storePaymentMethod: true
  • shopperReference: Your unique identifier for the shopper.

The /payments response contains:

  • recurringDetailReference: This is the token that you'll need to make recurring payments for this shopper.
The recurringDetailReference is also contained in the AUTHORISATION notification that you will receive for this payment.

Show a stored card in your payment form

To get the stored payment methods for a shopper, include in your /paymentMethods request:

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

The /paymentMethods response will include a storedPaymentMethods array that contains all the stored payment methods for this shopper.

         {
         ...
         "storedPaymentMethods":[
             {
                "brand":"visa",
                "expiryMonth":"10",
                "expiryYear":"2020",
                "holderName":"John Smith",
                "id":"8415718415172204",
                "lastFour":"1111",
                "name":"VISA",
                "supportedShopperInteractions":[
                   "Ecommerce",
                   "ContAuth"
                ],
                "type":"scheme"
             },
             {
                "brand":"visa",
                "expiryMonth":"08",
                "expiryYear":"2018",
                "holderName":"John Smith",
                "id":"8315720121476805",
                "lastFour":"0008",
                "name":"VISA",
                "supportedShopperInteractions":[
                   "ContAuth",
                   "Ecommerce"
                ],
                "type":"scheme"
             }
]
         ...
         }

Make a payment with a token

To make a payment with the token, include in your /payments request:

  • paymentMethod.storedPaymentMethodId: the id from the the /paymentMethods. This is the recurringDetailReference that you received when creating the token.

You can use tokens to make:

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.
  2. Add the cards that you wish to accept in your live Customer Area.

See also