# Bacs Direct Debit for Payment Setup API

Bacs Direct Debit is available in GBP for customers with a UK bank account.

To accept Bacs Direct Debit payments, you must:

1. Create a payment setup.
2. Update the payment setup with the payment details.
3. Verify payment authorization.
4. Confirm the payment.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> The Payment Setup API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests.

> **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/payments/setups`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "GBP",
  "amount": 4599,
  "reference": "ORDER_01234",
  "description": "Bacs Direct Debit payment",
  "payment_type": "regular",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier
- `amount` – The payment amount, with a minimum value of 1
- `currency` – The payment currency. Bacs Direct Debit only supports `GBP`
- `payment_type` – Set to `Regular` or `Recurring`
- `billing.address.country` – Your customer's two-letter ISO 3166-1 alpha-2 billing country code

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 4599,
  "currency": "GBP",
  "payment_type": "regular",
  "reference": "ORDER_01234",
  "description": "Bacs Direct Debit payment",
  "payment_methods": {
    "bacs": {
      "status": "pending",
      "flags": []
    }
  },
  "available_payment_methods": [
    "bacs"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `payment_methods` object, which contains the payment methods enabled on your account.

For Bacs Direct Debit, `payment_methods` contains the following fields:

- `status` – The [status of the payment method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md#Payment_method_status).
- `flags` – An array of error codes or indicators that highlight missing or invalid information.

---

## Update the payment setup

When the customer selects Bacs Direct Debit as the payment method on the checkout page, collect their account holder and bank account details, and call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint to submit them.

Checkout.com uses these details to validate your customer's bank account and create the Direct Debit mandate. None of the following fields are required by the schema, but we recommend you provide them, because we cannot create the mandate without them.

> **Information**
>
> A Bacs mandate typically becomes active within five business days of creation. You cannot collect a payment against the mandate during this period.

Additionally, provide the following fields:

| Field | Description |
| --- | --- |
| `payment_methods.bacs.account_holder`<br>`object` | Details of your customer, the bank account holder. |
| `payment_methods.bacs.account_holder.type`<br>`string` | Supported values:<br><br>- `individual`<br><br>- `corporate` |
| `payment_methods.bacs.account_holder.first_name`<br>`string` | The account holder's first name, for individual account holders. <br><br>Max length: 50 characters |
| `payment_methods.bacs.account_holder.last_name`<br>`string` | The account holder's last name, for individual account holders. <br><br>Max length: 50 characters |
| `payment_methods.bacs.account_holder.company_name`<br>`string` | The account holder's legal registered company name, for corporate account holders. <br><br>Max length: 50 characters |
| `payment_methods.bacs.account_holder.email`<br>`string` | The account holder's email address. <br><br>Max length: 255 characters |
| `payment_methods.bacs.account_number`<br>`string` | Your customer's UK bank account number. <br><br>Format: 8 digits <br><br>This field is write-only. It does not appear in the response. |
| `payment_methods.bacs.bank_code`<br>`string` | Your customer's UK bank sort code. <br><br>Format: 6 digits <br><br>This field is write-only. It does not appear in the response. |
| `payment_methods.bacs.country`<br>`string` | The two-letter ISO 3166-1 alpha-2 country code of the bank account. This can differ from `billing.address.country`. <br><br>Min length: 2 characters <br><br>Max length: 2 characters |
| `payment_methods.bacs.currency`<br>`string` | The three-letter ISO 4217 currency code of the account holder's bank account. This can differ from the payment `currency`. <br><br>Min length: 3 characters <br><br>Max length: 3 characters |
| `payment_methods.bacs.allow_partial_match`<br>`boolean` | Set to `true` to bypass a partial name-match warning and create the mandate anyway. <br><br>Default: `false` |

When you submit these details, we validate the `account_holder` name you provide against the bank account details in `account_number` and `bank_code`:

- Match – We create the mandate, and the payment method status changes to `ready`.
- Partial match – We add a warning flag to `payment_methods.bacs.flags`. Set `allow_partial_match` to `true` and resubmit the request to bypass the warning and create the mandate anyway.
- No match – We add an error flag to `payment_methods.bacs.flags`, and we cannot create the mandate for this bank account.

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "GBP",
  "amount": 4599,
  "reference": "ORDER_01234",
  "description": "Bacs Direct Debit payment",
  "payment_type": "regular",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "bacs": {
      "initialization": "enabled",
      "account_holder": {
        "type": "individual",
        "first_name": "Toby",
        "last_name": "Arden",
        "email": "toby.arden@example.com"
      },
      "account_number": "31392621",
      "bank_code": "609242",
      "country": "GB",
      "currency": "GBP",
      "allow_partial_match": true
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 4599,
  "currency": "GBP",
  "payment_type": "regular",
  "reference": "ORDER_01234",
  "description": "Bacs Direct Debit payment",
  "payment_methods": {
    "bacs": {
      "status": "pending",
      "flags": [],
      "instrument_id": "src_wkq7552u245upl5h75x24554xy"
    }
  },
  "available_payment_methods": [
    "bacs"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `pending` status. After the payment details have been successfully validated, the payment method status updates to `ready`.

Subscribe to the [Payment method ready](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_method_ready.md) webhook to get a notification when the payment is ready for confirmation.

The response also returns `payment_methods.bacs.instrument_id`, the ID of the Bacs instrument created for this payment.

---

## Verify payment authorization

If the update response does not immediately return a `ready` status, call the [Get a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/getAPaymentSetup) endpoint, setting the `id` of the payment setup as the `id` path parameter, to check the status before confirming.

**Production**

`GET` `https://{prefix}.api.checkout.com/payments/setups/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}`

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 4599,
  "currency": "GBP",
  "payment_type": "regular",
  "reference": "ORDER_01234",
  "description": "Bacs Direct Debit payment",
  "payment_methods": {
    "bacs": {
      "status": "ready",
      "flags": [],
      "instrument_id": "src_wkq7552u245upl5h75x24554xy"
    }
  },
  "available_payment_methods": [
    "bacs"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

---

## Confirm the payment

When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `bacs` as the `{payment_method_name}` path parameter.

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/bacs`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/bacs`

Unlike some other payment methods, confirming a Bacs Direct Debit payment does not mean it's immediately settled. Bacs Direct Debit runs on a three-day clearing cycle, so the payment starts with a `Pending` status and later changes to `Captured` or `Returned`. [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) to receive the final result.

If the mandate fails or a payment is returned after capture, Checkout.com reports this through the `payment_methods.bacs.flags` mechanism and standard payment webhooks. For more information, see [Payment returns and chargebacks](https://www.checkout.com/docs/payments/add-payment-methods/bacs.md#Payment_returns_and_chargebacks).