Third-party checkout guide: Adyen Web Components

Learn how to connect an Adyen Web Components (Advanced Flow) integration to Recurly using Recurly.js and the V3 API.

This guide walks you through connecting your Adyen Web Components integration to Recurly using the V3 API and Recurly.js. You'll configure Adyen's Web Components, tokenize payments with Recurly.js, and make purchase requests against the Recurly API.

1Definition 2Key concepts 3Integration guide 4Error handling 5Webhooks 6Testing 7What's next

Prerequisites

A working Adyen Web Components implementation using the Advanced Flow (Cards, Cash App Pay, Google Pay, Apple Pay, ACH, SEPA, BACS, iDEAL, and Bancontact). You don't need to send state data to Adyen.
Recurly.js loaded on your page and initialized per the Recurly.js documentation.
Access to your Recurly V3 API credentials and a Recurly site configured to accept payments.

Limitations

100% coupons and account credits aren't supported. Since communication with the gateway is required during initial setup, offer a free trial instead to avoid future payment failures.
Adyen's Sessions flow isn't supported — only the Advanced Flow.

ImportantYou must follow the Adyen setup guide, including the webhooks configuration in Adyen. Without proper webhooks configuration, recurring token usage and async status updates won't function correctly.

Definition

Adyen Web Components let you build a custom checkout UI while Adyen collects and tokenizes payment details client-side. This guide covers connecting that Advanced Flow integration to Recurly using Recurly.js and the V3 API.

Key concepts

Supported payment methods

Cards — Visa, Mastercard, Discover, Diners, JCB, UnionPay, American Express, Cartes Bancaires, and Bancontact (requires SEPA for renewals)

Wallets — Apple Pay, Google Pay, Cash App Pay, and PayPay

Direct debit — ACH, SEPA, BACS, and iDEAL (requires SEPA for renewals)

Integration guide

ImportantDon't write code to create, update, or otherwise process transactions or tokens with Adyen directly. You only create the state data, then pass it to Recurly using the steps below.

Build your Adyen components and Recurly.js integration

Follow Adyen's Advanced Flow docs to render Web Components for each payment method you support.

Cards: Card Web Component (Bancontact card component)
Cash App Pay: Cash App Pay Component
Google Pay: Google Pay Component (Express checkout)
Apple Pay: Apple Pay Component (Express checkout)
ACH: ACH Direct Debit Component
SEPA: SEPA Direct Debit Component
BACS: BACS Direct Debit
iDEAL: iDEAL Web Component
PayPay wallet: Adyen PayPay Web Component

Before rendering, fetch your supported methods via Adyen's API and pass the paymentMethodsResponse into the Components configuration. Only include methods your Recurly site supports.

"paymentMethodsResponse": {
  "paymentMethods": [
    {
      "brands": [
        "amex",
        "cup",
        "diners",
        "discover",
        "mc",
        "visa"
      ],
      "name": "Cards",
      "type": "scheme"
    }
  ]
}

Tokenize Adyen components with Recurly.js

Use an onSubmit handler in your checkout to generate a Recurly.js token from the component state, then send it to your server to complete the purchase via Recurly's API.

const onSubmit = async (state, component, actions) => {
  try {
    let payload = {
      type: 'adyen_component_state',
      adyen_component_state_context: state
    };

    recurly.token(payload, (error, token) => {
      if (error) {
        actions.reject();
        return;
      }
      // Send token.nonce to your backend to create a purchase via Recurly API
      actions.resolve();
    });
  } catch (error) {
    actions.reject();
  }
};

const adyenCheckout = await AdyenWeb.AdyenCheckout({
  onSubmit
});

Configure Adyen component best practices

Set the following options for reliable tokenization and renewals.

Option	Recommended setting	Notes
`storePaymentMethod`	`true`	Required for tokenization. If omitted or `false`, no vault token is issued and renewals fail with `no_billing_information` errors.
`enableStoreDetails`	omit	Avoid using — allows the user to opt out of vaulting tokens, which can break renewals with `no_billing_information` errors.
`hideCVC`	conditional	Set to `true` unless your Adyen setup explicitly supports CVC bypass on return customers.
`maskSecurityCode`	`true`	Masking the CVV field enhances security and user trust.
`hasHolderName`	omit	Not supported — use Recurly.js name elements instead.
`billingAddressRequired`	omit	Not supported — use Recurly.js address elements if you need AVS.
`addressSearchDebounceMs`	omit	Not supported — Recurly doesn't process Adyen address search elements.
`installmentOptions`	omit	Recurly doesn't support Adyen installment features.
`showInstallmentAmounts`	omit	Recurly doesn't display installment breakdowns — handle this in your own UI if needed.

For full Adyen Advanced Flow guidance, see the Advanced flow integration guide.

Create a purchase via the Recurly API

Once you have a valid Recurly.js token from the component data, call the Purchase endpoint. For example, to subscribe to a plan:

POST https://v3.recurly.com/purchases
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
	"currency": "USD",
  "account": {
	"code": "GoldCard",
	"email":"[email protected]",
  "billing_info": {
  "token_id":"kejCaCCHNIH5bDZx47f7Xw" // Adyen Component State Recurly.js Token
		}
	},
	"gateway_code":"1234567890", // Adyen Gateway Account code
	"subscriptions": [{
		"plan_code": "goldplan", // Plan ID for Subscription
	}]
}

Handle the purchase response

Check the response to confirm the purchase succeeded or handle any follow-up action.

On success, Recurly returns an InvoiceCollection containing any charge or credit invoices created.
On error, inspect the response code and message for validation or gateway issues, and surface them to the user.
For PayPay specifically, inspect the response and handle the action_result by following the standard Recurly.js alternative payment method flow.

Webhooks

Adyen returns recurring token usage and async status updates to Recurly through webhooks, as configured in the Adyen setup guide.

What's next

Full API reference — Complete endpoint documentation for all Recurly resources
Subscription management — Update, cancel, or migrate subscriptions after the initial purchase

Updated 2 days ago

Did this page help you?