Prerequisites

• Your Recurly site must be connected to Adyen, and the payment method(s) you intend to offer must be enabled in your Adyen merchant account.
• iDEAL|Wero and Sofort/Klarna Debit Risk require you to provide a returnURL.

Limitations

• Cash App doesn't return an action_result — you can ignore paymentMethod.handleAction for Cash App.

Definition

Key concepts

With one configuration object, recurly.AlternativePaymentMethods lets you:

• Render — Show a localized payment-method UI (PayPay, Boleto, iDEAL|Wero, Sofort/Klarna Debit Risk, or Cash App) inside any container.
• Tokenize — Collect the shopper's details client-side. No sensitive information hits your server.
• Emit — Generate a Recurly token you send to any V3 endpoint that accepts billing_info.
• Hand off / handle actions — Redirect or present an authentication step for iDEAL|Wero, Sofort/Klarna Debit Risk, and PayPay, or skip this entirely for Cash App.

Integration guide

Configure the component

Call recurly.AlternativePaymentMethods with a configuration object to start with any of these payment methods:

const paymentMethod = recurly.AlternativePaymentMethods({
  allowedPaymentMethods: [
    "paypay"
  ],
  blockedPaymentMethods: [],
  containerSelector: "#payment-methods-container",
  amount: 1000,
  currency: "JPY",
  countryCode: "JP",
  locale: "en-US",
  channel: "Web",
  adyen: {
    publicKey: 'adyen_public_key',
    env: "test",
    showPayButton: false,
    componentConfig: {}
  },
  returnURL: 'https://return-url.com/success',
});

See the SDK reference below for the full list of configuration options. Each payment method has its own required parameters:

PayPay wallet

Boleto

iDEAL

Sofort

Cash App

Render the payment method UI

After configuring your Recurly instance, call paymentMethod.start() to show the configured payment method(s) within the target element.

Call paymentMethod.destroy() to safely remove the rendered payment UI from the document. This is necessary if you want to re-render the component.

Generate a token

After the shopper fills in and confirms their details, call paymentMethod.submit() so the token event can be dispatched. You may optionally provide a specific customer billing address to this call.

paymentMethod.submit();

// You may wish to provide a specific customer billing address when calling `submit`.
paymentMethod.submit({
  billingAddress: {
    first_name: 'Ben',
    last_name: 'du Monde',
    address1: '1313 Main St.',
    address2: 'Unit 1',
    city: 'Hope',
    state: 'WA',
    postalCode: '98552',
    country: 'US'
  }
});

After submit is called, the token is emitted in the token event:

paymentMethod.on('token', function (token) {
  // token.id
});

Make a purchase

With the token, send a request to your server, which internally calls the Recurly API to make the purchase. The request must contain the fields previously filled in the element container. The response must then be handled to retrieve the action_result and pass it back to the browser — with the action result, paymentMethod.handleAction(action_result) can be called.

const form = document.querySelector('form')

fetch(form.action, {
  method: form.method,
  body: new FormData(form),
})
  .then(response => response.json())
  .then(data => {
    console.log({ data })
    if (data.error) {
      alert(data.error);
    } else if (data.action_result) {
      paymentMethod.handleAction(data.action_result)
    }
  })
  .catch(err => {
    console.error(err);
    notifyErrors([err]);
    });

SDK reference

recurly.AlternativePaymentMethods

Arguments

Returns

A new AlternativePaymentMethods instance.

alternativePaymentMethods.start

No arguments. Returns nothing.

alternativePaymentMethods.submit

Arguments

Returns

Nothing.

Events

error

Emitted when any error is encountered, whether during setup of the payment method flow or during customer interaction with the payment method interface.

token

Fired when the customer has completed the payment method flow. Recurly has received the payment details and generated this token to be used in the API.

Error handling and troubleshooting

Listen for the error event to catch problems during setup or while the shopper interacts with the payment method UI:

paymentMethod.on('error', function (err) {
  // err is a RecurlyError describing what went wrong
});

On the server side, check the purchase response for an error field before looking for action_result — see the fetch example in Make a purchase above.

Testing your integration

Use your Adyen test/sandbox merchant account and set adyen.env to "test" in the configuration object, as shown in the example above. Switch it to "live" only when you're ready for production traffic.

Each payment method has its own sandbox simulator in Adyen's test environment — consult Adyen's documentation for the specific method you're testing to trigger successful and failed payment scenarios.

What's next

• Full API reference — Complete endpoint documentation for all Recurly resources
• Recurly.js documentation — Set up and configure Recurly.js on your checkout page