# Bacs Direct Debit for web

Accept Bacs Direct Debit payments on your website with [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website.md), our pre-built, customizable payment user interface.

Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

Set up your client-side and server-side configuration to integrate with Checkout.com's payment gateway and enable payments on your website.

Bacs Direct Debit works differently from most payment methods in Flow. It does not take an immediate payment. Instead, it sets up a Direct Debit mandate, and you confirm the payment setup server-side after the mandate's five-day activation period passes.

---

## How it works

1. The customer lands on the checkout page.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client-side to mount Flow.
4. Flow displays the Bacs Direct Debit payment method to the customer.
5. The customer chooses an individual or corporate account, enters their name or company name, email, sort code, and account number, and accepts the Direct Debit agreement.
6. When the customer confirms, Flow creates a payment setup against the payment session and calls your `onMandateCreated` callback with the setup ID.
7. You store the setup ID against your order.
8. After the five-day mandate activation period, you call the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint.

---

## Before you start

Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com.

Create a [public key and a secret key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md) from the [Dashboard](https://dashboard.checkout.com), with the following key scopes:

- Public key – `payment-sessions:pay` and `vault-tokenization`
- Secret key – `payment-sessions`

To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

To enable Bacs Direct Debit on your account, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

### Content Security Policy

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:

```
connect-src, https://*.checkout.com
frame-src, https://*.checkout.com
script-src, https://*.checkout.com
img-src, https://*.checkout.com
```

---

## Step 1: Create a new Payment Session `Server side`

When the customer is ready to pay, you must send a server-side request to securely create a `PaymentSession` object. The `PaymentSession` contains the information required to handle all steps of the payment flow.

In your request:

- Set `billing.address.country` to `GB`
- Set `currency` to `GBP`
- Set `payment_type` to `Regular` or `Recurring`
- Provide `amount`
- Provide the `customer.email` or `customer.id`
- Provide `items[]`
- For each `item` in `items[]`, provide the:
  - `name`
  - `quantity`
  - `reference`
  - `unit_price`

> **Information**
>
> For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payment-sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions`

### Request example

```json
{
  "amount": 1000,
  "currency": "GBP",
  "reference": "ORDER_01234",
  "display_name": "Online shop",
  "payment_type": "Regular",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Hannah Bret",
    "email": "hannah.bret@example.com"
  },
  "items": [
    {
      "reference": "0001",
      "name": "Monthly subscription",
      "quantity": 1,
      "unit_price": 1000
    }
  ],
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsIm...",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}
```

---

## Step 2: Initialize and mount Flow `Client side`

You can install the `@checkout.com/checkout-web-components` package via npm:

```bash
npm install @checkout.com/checkout-web-components --save
```

Alternatively, you can load the package directly via a script:

```html
<script src="https://checkout-web-components.checkout.com/index.js" />
```

> **Note**
>
> To remain PCI compliant, only load the script directly from `https://checkout-web-components.checkout.com`. Do not download or host the script yourself, or include it in a bundle.

The client side initializes an instance of `CheckoutWebComponents` with configuration information and the payment session data retrieved in step 1.

```javascript
// Insert your public key here
const publicKey = '{YOUR_PUBLIC_KEY}';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',
});
```

### Configuration options

The standard `CheckoutWebComponents` configuration options apply: `appearance`, `componentOptions`, `environment`, `locale`, `paymentSession`, `publicKey`, and `translations`. For more information, see the [Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md).

Use `CheckoutWebComponents` to create a `bacs` object.

```javascript
const bacsComponent = checkout.create('bacs');
```

Mount Flow to the website using the `mount()` method. The method takes an [Element selector](https://developer.mozilla.org/en-US/docs/Web/API/Element) or an [Element](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors) as an argument.

```javascript
if (await bacsComponent.isAvailable()) {
  bacsComponent.mount('#bacs-container');
}
```

> **Note**
>
> Bacs Direct Debit requires a payment session. Unlike some other payment methods, you cannot use it in a session-less integration.

> **Note**
>
> Embedding Flow within an iframe or onto a Shadow DOM is not supported.

---

## Step 3: Handle the mandate response `Client side`

Bacs Direct Debit sets up a mandate rather than taking an immediate payment. Flow does not call the pay endpoint for Bacs. Instead, it creates a payment setup on the payment session.

This means Flow does not raise `onPaymentCompleted` for Bacs Direct Debit. You must handle the `onMandateCreated` callback to know that the Bacs setup completed successfully.

### onMandateCreated

Flow raises `onMandateCreated` after it successfully creates the Direct Debit setup. It receives two arguments:

- `_self` – The Bacs component instance, the same value passed to the other Flow callbacks.
- `mandateContext` – The payment setup response. Contains the payment method type and the setup ID.

The `mandateContext` argument has the following shape:

```json
{
  "type": "bacs",
  "context_data": {
    "setup_id": "set_trelajtf9beufhpqy6mkkzf4ze"
  }
}
```

You can set `onMandateCreated` on the Flow component, in which case it applies to the Bacs Direct Debit payment method inside Flow:

```javascript
const flowComponent = checkout.create('flow', {
  onMandateCreated: (_self, mandateContext) => {
    const setupId = mandateContext.context_data.setup_id;

    // Store the setup ID against your order, then redirect the customer
    window.location.href = `/confirmation?setup=${setupId}`;
  },
  onError: (_self, error) => {
    console.error('Bacs setup failed', error);
  },
});

flowComponent.mount('#flow-container');
```

You can also set it directly on the Bacs component:

```javascript
const bacsComponent = checkout.create('bacs', {
  onMandateCreated: (_self, mandateContext) => {
    console.log('Mandate created', mandateContext.context_data.setup_id);
  },
});
```

> **Note**
>
> After Flow creates the mandate, it moves the pay button into its success state and locks the form so the customer cannot resubmit. Perform your redirect to the confirmation page from inside `onMandateCreated`.

### Handle errors

If the setup fails, Flow calls `onError` instead of `onMandateCreated`. The most common validation error codes for Bacs Direct Debit are:

- `modulus_error` – The sort code and account number combination failed the modulus check.
- `verification_error` – We could not verify the bank details.
- `invalid_data` – The submitted data was invalid.

---

## Step 4: Confirm the payment setup `Server side`

The `onMandateCreated` callback is not the end of the flow. Creating the mandate does not collect the payment.

After the five-day mandate activation period, take the setup ID you stored in step 3 and call the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint.

If you do not confirm the payment setup, we never take the payment.

---

## Test the integration

To check the status of a payment:

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Payments_ > _Processing_ > _All payments_.
3. Select the test payment to view its details.

---

## Next steps

**[Customize your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md)**

Learn how to customize your Flow integration.

**[Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference.md)**

See the configuration options and error handling steps for Flow.