---
updatedAt: 2026-08-06T16:59:56.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# List BACS direct debit mandates [beta]
List BACS direct debit mandates for an account.
This endpoint takes an account token - an access token encoded with a Pismo account ID. The account is parsed from the token.
# 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": {
"afterIdQuery": {
"name": "afterId",
"in": "query",
"description": "Pagination cursor. Pass this field as a query parameter to get the next page.",
"required": false,
"schema": {
"type": "string",
"maxLength": 2000
}
},
"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 401 Unauthorized message\n",
"required": true
},
"beginDateQuery": {
"name": "beginDate",
"in": "query",
"description": "Return records created on or after this date/time (RFC3339).",
"required": false,
"schema": {
"type": "string",
"maxLength": 40,
"example": "2026-08-01T00:00:00Z"
}
},
"endDateQuery": {
"name": "endDate",
"in": "query",
"description": "Return records created on or before this date/time (RFC3339).",
"required": false,
"schema": {
"type": "string",
"maxLength": 40,
"example": "2026-08-31T23:59:59Z"
}
},
"idQuery": {
"name": "id",
"in": "query",
"description": "Transaction or mandate ID filter",
"required": false,
"schema": {
"type": "string",
"maxLength": 36
}
},
"mandateSourceQuery": {
"name": "source",
"in": "query",
"description": "Mandate source filter:\n * `auddis` - Electronic\n * `non-electronic` - Paper
\nDefault is all.\n",
"required": false,
"schema": {
"type": "string",
"enum": [
"auddis",
"non-electronic"
]
},
"example": "auddis"
},
"mandateStatusQuery": {
"name": "status",
"in": "query",
"description": "Mandate status filter.",
"required": false,
"schema": {
"type": "string",
"enum": [
"CREATED",
"CANCELLED"
]
}
},
"pageSizeQuery": {
"name": "pageSize",
"in": "query",
"description": "Maximum number of items to return per page. Default is `10`.",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100,
"default": 10,
"example": 50
}
},
"reqTrackingIdHeader": {
"name": "x-cid",
"in": "header",
"schema": {
"type": "string"
},
"description": "Request tracking ID. If not provided, a random UUID is generated.\n",
"required": false
}
},
"schemas": {
"accountId": {
"type": "integer",
"description": "Account ID",
"example": 12345678
},
"afterId": {
"type": "string",
"description": "Pagination cursor to pass as query parameter to get the next page\n",
"example": "019e92ec-3362-7c54-9d17-89f5542a06e4"
},
"createdAtDateTime": {
"type": "string",
"format": "date-time",
"description": "Created at date-time. RFC 3339 format",
"example": "2026-08-05T10:15:00Z"
},
"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"
}
}
},
"externalId": {
"type": "string",
"description": "Form3-assigned mandate ID (omitted until submitted)\n",
"example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"form3SubmissionId": {
"type": "string",
"description": "Form 3 submission ID",
"example": "9f8c7d6e-5b4a-3c2d-1e0f-a1b2c3d4e5f6"
},
"listing.Mandate": {
"type": "object",
"description": "A BACS direct debit mandate record returned by the mandate list endpoint.",
"properties": {
"id": {
"$ref": "#/components/schemas/mandateId"
},
"external_id": {
"$ref": "#/components/schemas/externalId"
},
"org_id": {
"$ref": "#/components/schemas/orgId"
},
"account_id": {
"$ref": "#/components/schemas/accountId"
},
"role": {
"$ref": "#/components/schemas/role"
},
"source": {
"$ref": "#/components/schemas/mandateSource"
},
"status": {
"$ref": "#/components/schemas/mandate.status"
},
"reference": {
"$ref": "#/components/schemas/reference"
},
"form3_submission_id": {
"$ref": "#/components/schemas/form3SubmissionId"
},
"status_reason": {
"$ref": "#/components/schemas/listing.StatusReason"
},
"created_at": {
"$ref": "#/components/schemas/createdAtDateTime"
},
"updated_at": {
"$ref": "#/components/schemas/updatedAtDateTime"
}
}
},
"listing.MandateListResponse": {
"type": "object",
"description": "Paginated list of BACS direct debit mandates.",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/listing.Mandate"
}
},
"next_page": {
"$ref": "#/components/schemas/nextPage"
},
"after_id": {
"$ref": "#/components/schemas/afterId"
}
}
},
"listing.StatusReason": {
"type": "object",
"description": "Present on rejections or returns.",
"properties": {
"code": {
"$ref": "#/components/schemas/statusReasonCode"
},
"description": {
"type": "string",
"description": "Human-readable status reason.",
"example": "Mandate transferred to a new bank"
}
}
},
"mandateId": {
"type": "string",
"description": "Form3-assigned mandate ID",
"example": "b254bb5e-6f1a-4c2b-9c1e-2f0a6d3e8c11"
},
"nextPage": {
"type": "boolean",
"description": "Are there more results?",
"example": true
},
"orgId": {
"type": "string",
"description": "Organization/tenant ID",
"example": "TN-KGIOODJD...1000"
},
"mandate.status": {
"type": "string",
"description": "Mandate lifecycle status.\n * `CREATED` - Mandate persisted and imported into Form3; pending submission\n * `SUBMITTED` - Mandate submitted to the scheme\n * `CONFIRMED` - Mandate confirmed and active\n * `AMEND_PENDING` - Amend intent accepted; pending submission to Form3\n * `AMENDED` - Amend confirmed\n * `CANCEL_PENDING` - Cancel intent accepted; pending submission to Form3\n * `CANCELLED` - Mandate cancelled. Terminal state\n * `FAILED` - Mandate processing failed. Terminal state\n",
"enum": [
"CREATED",
"SUBMITTED",
"CONFIRMED",
"AMEND_PENDING",
"AMENDED",
"CANCEL_PENDING",
"CANCELLED",
"FAILED"
],
"example": "CREATED"
},
"reference": {
"type": "string",
"description": "Reference note",
"example": "Weekly money for Mom"
},
"role": {
"type": "string",
"description": "Transaction role",
"enum": [
"PAYER",
"PAYEE"
],
"example": "PAYER"
},
"mandateSource": {
"type": "string",
"description": "Distinguishes electronic (AUDDIS) from paper mandates, per Form3's mandate `source` field.\n * `auddis` - electronic mandate\n * `non-electronic` - paper mandate\n",
"enum": [
"auddis",
"non-electronic"
],
"example": "auddis"
},
"statusReasonCode": {
"type": "string",
"description": "Reason for the return:\n * `1` - Instruction cancelled by payer\n * `2` - Payer deceased\n * `3` - Account transferred to a new bank or building society\n * `5` - No account. Handled automatically by Form3 when using Bacs Mandate Management.\n * `6` - No instruction. Handled automatically by Form3 when using Bacs Mandate Management.\n * `B` - Account closed\n * `C` - Account transferred to a different branch of the bank/building society\n * `F` - Invalid account type\n * `G` - Bank will not accept direct debits on account\n * `H` - Instruction has expired. Handled automatically by Form3 when using Bacs Mandate Management.\n * `I` - Payer reference is not unique. Handled automatically by Form3 when using Bacs Mandate Management.\n * `K` - Instruction cancelled by paying bank.\n",
"enum": [
"1",
"2",
"3",
"5",
"6",
"B",
"C",
"F",
"G",
"H",
"I",
"K"
],
"example": "2"
},
"updatedAtDateTime": {
"type": "string",
"format": "date-time",
"description": "Updated at date-time. RFC 3339 format",
"example": "2026-08-05T10:15:00Z"
}
}
},
"paths": {
"/v1/payments/bacs/directdebit/mandates": {
"get": {
"summary": "List BACS direct debit mandates [beta]",
"description": "List BACS direct debit mandates for an account. \n\nThis endpoint takes an account token - an access token encoded with a Pismo account ID. The account is parsed from the token.\n",
"operationId": "get-bacs-mandate-list",
"tags": [
"BACS direct debit"
],
"parameters": [
{
"$ref": "#/components/parameters/authHeader"
},
{
"$ref": "#/components/parameters/reqTrackingIdHeader"
},
{
"$ref": "#/components/parameters/idQuery"
},
{
"$ref": "#/components/parameters/mandateStatusQuery"
},
{
"$ref": "#/components/parameters/mandateSourceQuery"
},
{
"$ref": "#/components/parameters/beginDateQuery"
},
{
"$ref": "#/components/parameters/endDateQuery"
},
{
"$ref": "#/components/parameters/afterIdQuery"
},
{
"$ref": "#/components/parameters/pageSizeQuery"
}
],
"responses": {
"200": {
"description": "Paginated list of direct debit mandates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/listing.MandateListResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EBACS0004": {
"summary": "Validation Error",
"value": {
"code": "EBACS0004",
"message": "Validation error"
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
}
}
```