How to accept alternative payment methods without a redirect

This guide shows you how to accept MB WAY, SEPA Direct Debit and other alternative payment methods on your own checkout page, without a redirect. These methods collect a few details from the shopper, such as a phone number or an IBAN. You mount a form, pair it with a pay button, and handle the result. It assumes you have already initialized the SDK and hold a payrails client instance. If you haven’t, start with the quick start. The form renders inside a Payrails-hosted iframe, so the shopper’s details are never part of your page’s DOM. The fields come from the payment method’s configuration, so you don’t declare them yourself.

Supported payment methods

Payment method	Code	Shopper enters	Currency	Result type
MB WAY	`mbWay`	Phone number	EUR	Approve in app
SEPA Direct Debit	`sepaDirectDebit`	Name and IBAN	EUR	Pending

Pass the code as paymentMethodCode. The result type determines which events fire after the shopper clicks the pay button, as described in Handle the payment result.

Before you start

Use @payrails/web-sdk 6.6.0 or later.
Ask your Payrails account manager to enable the payment method for in-page collection. Until they do, payrails.apmForm() throws a PayrailsError because the session has no form for that method.
For SEPA Direct Debit, send the shopper’s IP address, user agent and email when you create the execution, in meta.clientContext.ipAddress, meta.clientContext.userAgent and meta.customer.email. Payrails rejects the payment without them.

1. Add containers to your page

<div id="apm-form"></div>
<div id="apm-button"></div>

2. Mount the form

const form = payrails.apmForm({ paymentMethodCode: "mbWay" });

form.on("ready", () => console.log("Form rendered"));
form.on("change", ({ isValid }) => console.log("Form valid:", isValid));

try {
  await form.mount("#apm-form");
} catch (error) {
  if (error?.context?.reason === "unrenderable-schema") {
    showOtherPaymentOptions();
  }
}

form.mount() returns a promise. It rejects when the selector doesn’t match an element, or when the SDK can’t draw the form. In the second case, the error’s context.reason is 'unrenderable-schema'. Use it to offer the shopper another way to pay.

3. Mount the pay button

const button = payrails.apmButton({
  form,
  translations: { label: "Pay with MB WAY" },
});

button.mount("#apm-button");

The button stays disabled until the form has loaded. A click validates the form first. If a field is invalid, the form shows the error next to the field, the button emits validate with isValid: false, and the SDK doesn’t submit the payment:

button.on("validate", ({ isValid }) => {
  if (!isValid) scrollToPaymentForm();
});

The cancelable buttonClicked and requestStart instance events run after the form validates, the same as for card payments. A check you already run there also covers these methods.

4. Handle the payment result

Outcomes are instance events, so subscribe on the payrails client:

payrails.on("success", (e) => showConfirmation(e.executionId));
payrails.on("pending", (e) => showOrderReceived(e.executionId));
payrails.on("failed", (e) => showError(e.data?.code));

Subscribe to all three for every method. Which one fires depends on the payment method and the provider your workflow routes it to. One listener fires for every payment method in the session. If your page mounts other payment elements too, filter with e.paymentMethodCode. Which events fire depends on the method’s result type in the supported payment methods table:

Result type	What the shopper sees after clicking	Events
Approve in app	A wait screen while they approve in another app	`success` or `failed`
Pending	Nothing more, the SDK submits the payment	`pending` or `failed`

Approve-in-app methods

The shopper approves the payment in another app, such as their MB WAY app. The SDK handles the wait for you: the form switches to a screen with the payment method’s logo and instructions, the SDK removes the button, and then waits for the shopper to approve. When they do, the wait screen goes away and success fires. Show your own confirmation.

Pending methods

The payment completes after checkout, so the SDK doesn’t have the result yet when the shopper clicks. Treat pending as “order placed” and rely on your webhook for the final status.

5. Handle a declined or expired approve-in-app payment

If the shopper declines in the app, or doesn’t approve in time, the wait screen switches back to the form. The form keeps the shopper’s details, and the button reappears. The SDK then fires sessionExpired, followed by failed with AUTHORIZATION_ERROR. Return fresh init options from sessionExpired so the shopper’s retry starts a new payment:

payrails.on("sessionExpired", async () => fetchNewInitResponse());

Sometimes the SDK can’t confirm the result, for example because the session expired during the wait. The same thing happens, but failed carries AUTHENTICATION_ERROR or UNKNOWN_ERROR. The shopper may still approve in their app afterwards, so check the payment’s status before you let them retry, or they could pay twice:

payrails.on("failed", async (e) => {
  const code = e.data?.code;
  if (code === "AUTHENTICATION_ERROR" || code === "UNKNOWN_ERROR") {
    await checkPaymentStatus(e.executionId);
  }
});

Your webhook or an execution lookup has the payment’s final status.

6. Customize the form and button

The form and the button each take their own appearance. Form rules cross into the iframe and apply to the .payrails-* classes, and rules under actionScreen style only the wait screen of an approve-in-app method:

const form = payrails.apmForm({
  paymentMethodCode: "mbWay",
  appearance: {
    rules: {
      ".payrails-input": { padding: "12px", borderRadius: "8px" },
      ".payrails-field--invalid .payrails-input": { borderColor: "#d33" },
    },
    actionScreen: {
      rules: { ".payrails-text": { textAlign: "center" } },
    },
  },
  translations: {
    errors: { required: "This field is required" },
  },
});

translations.errors replaces the form’s default error messages. The appearance reference lists every class.

Offer more than one method

Create a form and button pair per method, each in its own containers. Element ids default to one per payment method, so two methods on the same page don’t collide. Pass id only if you mount two forms for the same method.

const sepaForm = payrails.apmForm({ paymentMethodCode: "sepaDirectDebit" });
await sepaForm.mount("#sepa-form");
payrails.apmButton({ form: sepaForm }).mount("#sepa-button");

For every option and event, refer to the payrails reference and the events reference.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

How to accept alternative payment methods without a redirect

Supported payment methods

Before you start

1. Add containers to your page

2. Mount the form

3. Mount the pay button

4. Handle the payment result

Approve-in-app methods

Pending methods

5. Handle a declined or expired approve-in-app payment

6. Customize the form and button

Offer more than one method

​Supported payment methods

​Before you start

​1. Add containers to your page

​2. Mount the form

​3. Mount the pay button

​4. Handle the payment result

​Approve-in-app methods

​Pending methods

​5. Handle a declined or expired approve-in-app payment

​6. Customize the form and button

​Offer more than one method

Supported payment methods

Before you start

1. Add containers to your page

2. Mount the form

3. Mount the pay button

4. Handle the payment result

Approve-in-app methods

Pending methods

5. Handle a declined or expired approve-in-app payment

6. Customize the form and button

Offer more than one method