--- updatedAt: 2026-08-13T15:08:37.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Amend BACS mandate [beta] Amend a BACS direct debit mandate. Registers a change to a mandate's debtor and/or beneficiary details, applied asynchronously through the BACS scheme. **Notes:** * The amend is persisted with `status` = `AMEND_PENDING`, and enqueued for the asynchronous submission worker, which submits it to Form3 through the PSP gateway. * Allowed only when the mandate is in `CREATED`, `SUBMITTED`, or `CONFIRMED`; any other state is rejected with a **409 Conflict** (`EBACS0103`). * `version` is a Form3 optimistic-concurrency passthrough that must equal the stored version; a mismatch is rejected with a **409 Conflict** (`EBACS0104`). This call does not increment this field. * This endpoint moves the mandate to `status` = `AMEND_PENDING` and generates a [BACS mandate status changed](https://developers.pismo.io/events/docs/bacs-mandate-status-change-1) event. Subsequent status transitions generate further events (for example `AMENDED`, `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 401 Unauthorized message\n", "required": true }, "mandateIdPath": { "name": "id", "in": "path", "description": "Mandate ID (the Form3-assigned ID returned at creation).", "required": true, "schema": { "type": "string", "maxLength": 36 } } }, "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" } } }, "mandateId": { "type": "string", "description": "Form3-assigned mandate ID", "example": "b254bb5e-6f1a-4c2b-9c1e-2f0a6d3e8c11" }, "mandateVersion": { "type": "integer", "description": "The mandate version. Unchanged by the amend mandate endpoint call (Form3 passthrough — not incremented).\n", "example": 2 }, "mandate.AdviceReason": { "type": "string", "description": "Why an amendment is advised to the originator. Mapped to the matching ADDACS advice code on the mandate submission raised for the amendment; scheme codes are not accepted here.\n * `advance_notice_disputed` - The payer disputes the advance notice of a collection. An advice on its own, with no accompanying change of details\n * `instruction_details_amended` - The payer's account details on the instruction have changed\n", "enum": [ "advance_notice_disputed", "instruction_details_amended" ], "example": "advance_notice_disputed" }, "mandate.AmendRequest": { "type": "object", "description": "Payload to amend an existing mandate. `version` is required for optimistic concurrency.", "required": [ "version" ], "properties": { "version": { "type": "integer", "description": "Caller's expected current mandate version. A Form3 optimistic-concurrency passthrough that must match the stored version. This call does not increment this field.\n", "example": 0 }, "debtor": { "$ref": "#/components/schemas/mandate.Debtor" }, "beneficiary": { "$ref": "#/components/schemas/mandate.Beneficiary" }, "advice_reason": { "$ref": "#/components/schemas/mandate.AdviceReason" } } }, "mandate.AmendResponse": { "type": "object", "description": "The amend endpoint returns this after the pending intent is persisted.", "properties": { "id": { "$ref": "#/components/schemas/mandateId" }, "status": { "$ref": "#/components/schemas/mandate.AmendStatus" }, "version": { "$ref": "#/components/schemas/mandateVersion" } } }, "mandate.AmendStatus": { "type": "string", "description": "Lifecycle status reachable when amending a mandate.\n * `AMEND_PENDING` - Amend intent accepted; pending submission to Form3 via the PSP gateway\n * `AMENDED` - Amend confirmed\n * `FAILED` - Amend processing failed. Terminal state\n", "enum": [ "AMEND_PENDING", "AMENDED", "FAILED" ], "example": "AMEND_PENDING" }, "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.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" } } }, "sortCode": { "type": "string", "pattern": "^[0-9]{6}$", "description": "UK sort code (6 digits).", "example": "200000" } } }, "paths": { "/v1/payments/bacs/directdebit/mandates/{id}": { "patch": { "summary": "Amend BACS mandate [beta]", "description": "Amend a BACS direct debit mandate.\n\nRegisters a change to a mandate's debtor and/or beneficiary details, applied asynchronously through the BACS scheme.\n\n**Notes:**\n\n * The amend is persisted with `status` = `AMEND_PENDING`, and enqueued for the asynchronous submission worker, which submits it to Form3 through the PSP gateway.\n\n * Allowed only when the mandate is in `CREATED`, `SUBMITTED`, or `CONFIRMED`; any other state is rejected with a **409 Conflict** (`EBACS0103`).\n\n * `version` is a Form3 optimistic-concurrency passthrough that must equal the stored version; a mismatch is rejected with a **409 Conflict** (`EBACS0104`). This call does not increment this field.\n\n * This endpoint moves the mandate to `status` = `AMEND_PENDING` and generates a [BACS mandate status changed](https://developers.pismo.io/events/docs/bacs-mandate-status-change-1) event. Subsequent status transitions generate further events (for example `AMENDED`, `FAILED`).\n", "operationId": "patch-amend-mandate", "tags": [ "BACS direct debit" ], "parameters": [ { "$ref": "#/components/parameters/authHeader" }, { "$ref": "#/components/parameters/mandateIdPath" } ], "requestBody": { "description": "Amend mandate request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate.AmendRequest" } } }, "required": true }, "responses": { "202": { "description": "Amend intent accepted and enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate.AmendResponse" } } } }, "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" } } } } } }, "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" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer.Error" }, "examples": { "EBACS0102": { "summary": "Mandate Not Found", "value": { "code": "EBACS0102", "message": "Mandate not found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer.Error" }, "examples": { "EBACS0103": { "summary": "Mandate Invalid State", "value": { "code": "EBACS0103", "message": "Mandate cannot perform the requested operation in its current status" } }, "EBACS0104": { "summary": "Mandate Version Conflict", "value": { "code": "EBACS0104", "message": "Mandate version does not match the current version" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer.Error" }, "examples": { "EBACS0003": { "summary": "Internal Error", "value": { "code": "EBACS0003", "message": "Internal error" } } } } } } } } } } } ```