Sessions flow integration guide

These parameters are specific to Drop-in and are only accepted on the DropIn instance.

Properties

Methods

Events

Drop-in orders the payment methods by popularity, the most popular payment methods in the shopper's country appearing at the top.

In your Customer Area, you can configure which payment methods are rendered based on the shopper's country. If you want to customize rendered payment methods for specific transactions, you can do this on your server.

Customize based on shopper's country

To configure which payment methods are rendered (and in which order) based on the shopper's country:

1. Log in to your Customer Area.

2. Go to Settings > Checkout settings.

   If Checkout settings does not appear in the Settings menu, ask your admin user to give you the Change payment methods user role.

3. Select a Shopper country.

4. Drag the payment methods into the order you want them to appear to shoppers in this country.

5. To hide a payment method from shoppers in this country, drag it to the Other configured payment methods box.

Customize for specific transactions (on your server)

When making a /sessions request, you can include one of the following parameters:

• allowedPaymentMethods: Drop-in renders only the payment methods that you specify.
• blockedPaymentMethods: Drop-in doesn't render payment methods that you specify.

The following example shows how to make a request to only show iDEAL and credit cards in the payment form:

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",
  "allowedPaymentMethods": ["ideal", "scheme"],
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Web",
  "shopperLocale": "NL"
}'

The Drop-in UI can be styled to match your website and brand. The styling of fonts, colors, layouts, and buttons can be customized using CSS.

Using custom styling

Drop-in includes a pre-styled payment form. You can override this styling using Drop-in CSS classes and common CSS properties.

To override the default Drop-in styling:

1. In your CSS, add Drop-in classes that represent styling that you want to customize in your payment form.

2. Customize the styling of these classes using common CSS properties.

   For example, to change the Pay button to have:

   • Green background (#0abf53).
   • Heavier text.
   • Square corners.

   Include the following to your CSS:

   Add button styling

   Expand view

   Copy link to code block

   Copy code

   Copy code

   .adyen-checkout__button--pay {
       background-color: #0abf53;
       font-weight: 900;
       border-radius: 0;
   }

Drop-in CSS classes

You can customize the styling for Drop-in using the CSS classes below.

These classes follow the BEM (.block__element--modifier) methodology, where state is represented by a modifier (such as --selected).

.adyen-checkout__payment-method {
    /* Payment method container */
}
.adyen-checkout__payment-method--selected {
    /* Payment method that has been selected */
}
.adyen-checkout__payment-method__header {
    /* Payment method icon and name */
}
.adyen-checkout__payment-method__radio {
    /* Radio button in payment method header */
}
.adyen-checkout__payment-method__radio--selected {
    /* Selected radio button in payment method header */
}
.adyen-checkout__payment-method__name {
    /* Payment method name in the payment method header */
}
.adyen-checkout__spinner__wrapper {
    /* Spinning icon */
}
.adyen-checkout__button {
    /* Buttons */
}
.adyen-checkout__button--pay {
    /* Pay button */
}
.adyen-checkout__field {
    /* Form field container */
}
.adyen-checkout__label {
    /* Form label container */
}
.adyen-checkout__label__text {
    /* Text element inside the form label container */
}
.adyen-checkout__input {
    /* Input fields */
}
.adyen-checkout__input--error {
    /* Error state for the input fields */
}
.adyen-checkout__error-text {
    /* Error message text */
}
.adyen-checkout__card__cardNumber__input {
    /* Input field for the card number */
}
.adyen-checkout__field--expiryDate {
    /* Input field for the expiry date */
}
.adyen-checkout__field__cvc {
    /* Input field for the CVC security code */
}
.adyen-checkout__card__holderName {
    /* Input field for cardholder name */
}
.adyen-checkout__checkbox__input {
    /* Checkboxes */
}
.adyen-checkout__checkbox__label {
    /* Checkbox labels */
}
.adyen-checkout__radio_group__input {
    /* Radio buttons */
}
.adyen-checkout__dropdown__button {
    /* Dropdown button showing list of options */
}
.adyen-checkout__dropdown__list {
    /* Dropdown list */
}
.adyen-checkout__dropdown__element {
    /* Elements in the dropdown list */
}
.adyen-checkout__link {
    /* Links */
}

Styling card input fields

If you want to change the styling of the card number, CVC, and expiry date of a card, you can do so by including a styles property in the card configuration when creating the main AdyenCheckout instance.

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.

For a list of supported properties, refer to Styling card input fields.

For example, to change the color of the card input fields to white:

const checkout = new AdyenCheckout({
  paymentMethodsConfiguration: {
    card: {
      styles: {
        base: {
          color: "#ffffff" // CSS color code for white
        }
      }
    }
  }
});

Supported languages

We include UI localizations for some languages. The fields and text are in the files for the included locales.

To use a language or localization that isn't included, create your own.

Change the language

By default, the UI is presented according to the shopperLocale from your /sessions request. If this language isn't supported, the UI is presented in US English.

You can also set the language by specifying a locale on the AdyenCheckout instance.

Customize the localization

The text displayed in each localization can be customized, allowing you to replace the default text with your own.

To customize a localization:

1. Create a translations object on your payments page.

2. In this object, specify the locale you want to customize, and add key-value pairs corresponding to any text you want to customize.

   The following example shows how to customize the US English (en-US) translation so that:

   • Shipping Address appears instead of Delivery Address (the default en-US text).
   • State appears instead of State or Province (the default en-US text).
   Customize translations

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const translations = {
   		"en-US": {
   			"deliveryAddress": "Shipping Address",
   			"stateOrProvince": "State"
   		}
   	};

3. To use the customized localization in your payment form, provide the following parameters in the configuration object:

   Parameter name	Required	Description
   locale		The locale you customized in the previous step.
   translations		Use translations

   The following example shows how to use a customized en-US localization in Drop-in.

   Example of US English localization

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const configuration = {
   	locale: "en-US",
   	translations: translations,
   	...
   };

Create your custom localization

To use a language or localization that we do not included, create your own.

1. Create a translations object on your payments page.

2. In this object, specify the locale you want to create. For example, you can use the locale en-GB to create a British English localization, and add key-value pairs corresponding to text shown in the UI.

   The example below shows a translation object for creating a en-GB localization.

   British English translations example

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const translations = {
       "en-GB": {
           "paymentMethods.moreMethodsButton": "More payment methods",
           "payButton": "Pay",
           "storeDetails": "Save for my next payment",
           ...
       }
   };

3. To use your localization in your payment form, provide the following parameters in the configuration object:

   Parameter name	Required	Description
   locale		The locale you created in the previous step.
   translations		Use translations

   The example below shows how to use a created localization for en-GB.

   Copy code
   const configuration = {
       locale: "en-GB",
       translations: translations,
       ...
   };
    
   const checkout = new AdyenCheckout(configuration);

Text direction

The default text direction is left-to-right. Text direction is independent from the locale you set in the configuration object. So even if you set the locale to a right-to-left language, like Arabic, you still need to set the text direction.

To change the text direction to right-to-left, use the HTML dir attribute on the parent element for the checkout container.

You can also get the result of the payment session on your server.

1. Get the id from the /sessions response.
2. Get sessionResult from the onPaymentCompleted event.

3. Make a GET /sessions/{id}?sessionResult={sessionResult} request including the id and sessionResult. For example:

   Request for result of payment session

   curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

   Expand view

   Copy link to code block

   Copy code

   Copy code

   curl -X GET https://checkout-test.adyen.com/checkout/v70/sessions/CS12345678?sessionResult=SOME_DATA

   The response includes the result of the payment session (status). For example:

   Response with result of the payment session

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
      "id": "CS12345678",
      "status": "completed"
   }

   Possible statuses:

   status	Description
   completed	The shopper completed the payment. This means that the payment was authorized.
   paymentPending	The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.
   canceled	The shopper canceled the payment.
   expired	The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this sessionId.