---
updatedAt: 2026-08-13T15:08:37.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Create BACS mandate [beta]


Create a BACS direct debit mandate.

A BACS direct debit mandate captures a payer's authorisation, taken from a signed paper form, for a business to collect direct debit payments from their UK bank account through the BACS scheme.

**Notes:**

  * The operation is idempotent via the `Idempotency-key` header. Repeating the same key replays the original mandate; reusing the same `reference` with a different key is rejected with a **409 Conflict**.

  * Creation does not generate an event. Subsequent status transitions generate a [BACS mandate status changed](https://developers.pismo.io/events/docs/bacs-mandate-status-change-1) event (for example `SUBMITTED`, `CONFIRMED`, `FAILED`).


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Payment rails - BACS payments",
    "description": "BACS payments system API",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    },
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/bacs",
      "description": "Sandbox API server for testing."
    }
  ],
  "tags": [
    {
      "name": "BACS direct debit"
    }
  ],
  "components": {
    "parameters": {
      "authHeader": {
        "name": "Authorization",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "Account token - access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message\n",
        "required": true
      },
      "idempotencyKeyHeader": {
        "name": "Idempotency-key",
        "in": "header",
        "schema": {
          "type": "string",
          "maxLength": 32
        },
        "description": "A UUID (without hyphens) to ensure the operation remains idempotent, allowing for operation repetition without causing unintended effects or duplication. Identifies the transaction on future events.\n",
        "required": true
      }
    },
    "schemas": {
      "accountNumber": {
        "type": "string",
        "pattern": "^[0-9]{8}$",
        "description": "UK account number (8 digits)",
        "example": "87654321"
      },
      "beneficiaryName": {
        "type": "string",
        "maxLength": 18,
        "description": "Beneficiary name.",
        "example": "Mac Donalds"
      },
      "customer.DetailMessage": {
        "type": "object",
        "properties": {
          "external": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/customer.ExternalMessage"
            }
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/customer.ParameterMessage"
            }
          },
          "payload": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/customer.PayloadMessage"
            }
          }
        }
      },
      "customer.Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error's code.",
            "example": "EPT0001"
          },
          "details": {
            "$ref": "#/components/schemas/customer.DetailMessage"
          },
          "message": {
            "type": "string",
            "description": "Error's message.",
            "example": "User not found"
          }
        }
      },
      "customer.ExternalMessage": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Code",
            "example": "PBE315"
          },
          "message": {
            "type": "string",
            "description": "Message",
            "example": "Generic error"
          }
        }
      },
      "customer.ParameterMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field",
            "example": "Query parameter"
          },
          "message": {
            "type": "string",
            "description": "Message",
            "example": "Generic error"
          }
        }
      },
      "customer.PayloadMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field",
            "example": "Entity.field"
          },
          "message": {
            "type": "string",
            "description": "Message",
            "example": "Generic error"
          }
        }
      },
      "mandateClearingId": {
        "type": "string",
        "pattern": "^[0-9]{6}$",
        "description": "Six-digit clearing ID for the mandate",
        "example": "123456"
      },
      "mandateId": {
        "type": "string",
        "description": "Form3-assigned mandate ID",
        "example": "b254bb5e-6f1a-4c2b-9c1e-2f0a6d3e8c11"
      },
      "mandateReference": {
        "type": "string",
        "maxLength": 18,
        "description": "Mandate reference. Must be unique per organization and use the standard BACS reference character set.\n\nThe standard BACS reference character set is the restricted set of characters BACS permits in the text fields of a Standard 18 record — the format used for Direct Debit/Direct Credit instructions. It maps to the reference field on the mandate\nschemas.\n\nBACS Standard 18 (STD18) is a fixed-width, 80-to-106-character line-based file format used to submit Direct Credit and Direct Debit payment instructions in the UK. Files strictly follow a defined sequence starting with volume and header labels, proceeding to transaction records, and ending with trailer and total lines.\n\n**Permitted characters**:\n  - Uppercase letters A-Z (lowercase is not allowed — it gets force-uppercased)\n  - Digits 0-9\n  - Space\n  - These four specials only: - (hyphen), . (full stop), & (ampersand), / (solidus)\n\n**Reference-field rules on top of the character set**:\n  - 6-18 characters\n  - Must not begin with a space\n  - Must not be all the same character (e.g. all zeros)\n  - First 4 chars must not be DDIC (reserved for bank/indemnity-claim use)\n  - Should be unique per Direct Debit\n",
        "example": "MANDATE-REF-001"
      },
      "mandate.Beneficiary": {
        "type": "object",
        "description": "Beneficiary (creditor) details.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "$ref": "#/components/schemas/beneficiaryName"
          },
          "account_number": {
            "$ref": "#/components/schemas/accountNumber"
          },
          "sort_code": {
            "$ref": "#/components/schemas/sortCode"
          }
        }
      },
      "mandate.CreateRequest": {
        "type": "object",
        "description": "Payload to create a mandate",
        "required": [
          "debtor",
          "beneficiary",
          "clearing_id",
          "reference",
          "processing_date"
        ],
        "properties": {
          "debtor": {
            "$ref": "#/components/schemas/mandate.Debtor"
          },
          "beneficiary": {
            "$ref": "#/components/schemas/mandate.Beneficiary"
          },
          "clearing_id": {
            "$ref": "#/components/schemas/mandateClearingId"
          },
          "reference": {
            "$ref": "#/components/schemas/mandateReference"
          },
          "processing_date": {
            "$ref": "#/components/schemas/processingDate"
          }
        }
      },
      "mandate.CreateResponse": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/mandateId"
          },
          "status": {
            "$ref": "#/components/schemas/mandate.CreateStatus"
          }
        }
      },
      "mandate.CreateStatus": {
        "type": "string",
        "description": "Lifecycle status reachable for a created mandate.\n  * `CREATED` - Mandate persisted; pending submission to Form3 via the PSP gateway\n  * `SUBMITTED` - Mandate submitted to the scheme\n  * `CONFIRMED` - Mandate confirmed and active\n  * `FAILED` - Mandate processing failed. Terminal state\n",
        "enum": [
          "CREATED",
          "SUBMITTED",
          "CONFIRMED",
          "FAILED"
        ],
        "example": "CREATED"
      },
      "mandate.Debtor": {
        "type": "object",
        "description": "Debtor (payer) bank details captured from the signed mandate form.",
        "required": [
          "name",
          "account_number",
          "sort_code"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 18,
            "description": "Debtor account holder name",
            "example": "John Debtor"
          },
          "account_number": {
            "$ref": "#/components/schemas/accountNumber"
          },
          "sort_code": {
            "$ref": "#/components/schemas/sortCode"
          }
        }
      },
      "processingDate": {
        "type": "string",
        "description": "Processing date. Format = yyyy-mm-dd",
        "example": "2026-08-10"
      },
      "sortCode": {
        "type": "string",
        "pattern": "^[0-9]{6}$",
        "description": "UK sort code (6 digits).",
        "example": "200000"
      }
    }
  },
  "paths": {
    "/v1/payments/bacs/directdebit/paper-mandates": {
      "post": {
        "summary": "Create BACS mandate [beta]",
        "description": "\nCreate a BACS direct debit mandate.\n\nA BACS direct debit mandate captures a payer's authorisation, taken from a signed paper form, for a business to collect direct debit payments from their UK bank account through the BACS scheme.\n\n**Notes:**\n\n  * The operation is idempotent via the `Idempotency-key` header. Repeating the same key replays the original mandate; reusing the same `reference` with a different key is rejected with a **409 Conflict**.\n\n  * Creation does not generate an event. Subsequent status transitions generate a [BACS mandate status changed](https://developers.pismo.io/events/docs/bacs-mandate-status-change-1) event (for example `SUBMITTED`, `CONFIRMED`, `FAILED`).\n",
        "operationId": "post-create-mandate",
        "tags": [
          "BACS direct debit"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/authHeader"
          },
          {
            "$ref": "#/components/parameters/idempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "description": "Create mandate request body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/mandate.CreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Mandate created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/mandate.CreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0004": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "EBACS0004",
                      "message": "Validation error"
                    }
                  },
                  "EBACS0016": {
                    "summary": "Unmarshal Error",
                    "value": {
                      "code": "EBACS0016",
                      "message": "Unmarshal error"
                    }
                  },
                  "EBACS0047": {
                    "summary": "PSP Gateway API Bad Request",
                    "value": {
                      "code": "EBACS0047",
                      "message": "Invalid BACS Request. Check error details for more information."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0002": {
                    "summary": "Missing Tenant Header",
                    "value": {
                      "code": "EBACS0002",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  },
                  "EBACS0085": {
                    "summary": "Missing Account Id",
                    "value": {
                      "code": "EBACS0085",
                      "message": "Missing required account-id"
                    }
                  },
                  "EBACS0034": {
                    "summary": "Invalid Idempotency Key",
                    "value": {
                      "code": "EBACS0034",
                      "message": "Missing required header: 'x-idempotency-key'"
                    }
                  },
                  "EBACS0105": {
                    "summary": "BACS Mandates Not Enabled For Account",
                    "value": {
                      "code": "EBACS0105",
                      "message": "BACS mandates are not enabled for the account"
                    }
                  },
                  "EBACS0021": {
                    "summary": "Account Blocked Or Cancelled",
                    "value": {
                      "code": "EBACS0021",
                      "message": "Account blocked or cancelled"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0058": {
                    "summary": "Record Already Exists",
                    "value": {
                      "code": "EBACS0058",
                      "message": "Record already exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0023": {
                    "summary": "Transaction Database Error",
                    "value": {
                      "code": "EBACS0023",
                      "message": "Transaction database error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```