Overview

This guide walks you through how to connect your Adyen Web Components integration correctly to Recurly via the V3 API and Recurly.js. You’ll learn how to configure Adyen’s Web Components, tokenize payments with Recurly.js, and make purchase requests against the Recurly API.

Prerequisites & limitations

• 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 do not need to send the State Data to Adyen.

• You have followed the Adyen setup guide including applicable Webhooks configuration at Adyen. Without proper webhooks configuration, certain behaviors such as Recurring Token usage and Async Status updates will not function properly.

• Recurly.js loaded on your page and initialized per our Recurly.js documentation.

• Access to your Recurly V3 API credentials and a Recurly site configured to accept payments.

• Not supported:

  • 100% Coupons and Account Credits: Since communication with the gateway is required during initial setup, it is recommended to offer free trials in these instances to avoid future payment failures. 100% Coupons/Credits are not supported.
  • Adyen Sessions flow.

• Supported payment methods:

  • Cards: Visa, MasterCard, Discover, Diners, JCB/I, Union Pay, American Express, Cartes Bancaires, Bancontact (requires SEPA for renewals)
  • Wallets: Apple Pay, Google Pay, Cash App Pay
  • Direct Debit: ACH, SEPA, BACS, iDeal (requires SEPA for renewals)

Step 1: Build your Adyen components + Recurly.js integration

Follow Adyen’s Advanced Flow docs to render Web Components for each method:

• Cards: Card Web Component | Adyen Docs

  • Bancontact (card only): Bancontact Card Component

• Cash App Pay: Cash App Pay Component | Adyen Docs

• Google Pay: Google Pay Component | Adyen Docs

  • Express Checkout: Google Pay express checkout | Adyen Docs

• Apple Pay: Apple Pay Component | Adyen Docs

  • Express Checkout: Apple Pay express checkout | Adyen Docs

• ACH: ACH Direct Debit Component | Adyen Docs

• SEPA: SEPA Direct Debit Component | Adyen Docs

• BACS: BACS Direct Debit | Adyen Docs

• iDeal: iDeal Web Component | Adyen Docs

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

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

Step 2: Tokenize Adyen components with Recurly.js

Use an onSubmit handler in your Checkout to generate a Recurly.js token from the component state. Send this token 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
});

Step 3: Configure Adyen component best practices

Ensure the following options are set for reliable tokenization with Adyen and renewals:

For full Adyen advanced flow guidance, see:

• Advanced flow integration guide | Adyen Docs

Step 4: Create a purchase via the Recurly V3 API

Once you have a valid R.js token using components data, invoke the V3 API’s purchase endpoint. For example, to subscribe 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
	}]
}

Step 5: Handle the purchase response

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

Next steps

After completing an initial purchase, explore our Subscription Management guide to learn how to update, cancel, or migrate subscriptions:

• Subscription Management