PIpismo
BACS direct debit

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 event. Subsequent status transitions generate further events (for example AMENDED, FAILED).

patch/v1/payments/bacs/directdebit/mandates/{id}

Request

  • Base URL
    https://sandbox.pismolabs.io/bacs
  • URL
    https://sandbox.pismolabs.io/bacs/v1/payments/bacs/directdebit/mandates/{id}
  • Auth
    none declared. Required headers: Authorization

Path parameters

idstring required

Mandate ID (the Form3-assigned ID returned at creation).

Headers

Authorizationstring required

Account token - access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message

Request body

versioninteger required

Caller's expected current mandate version. A Form3 optimistic-concurrency passthrough that must match the stored version. This call does not increment this field.

advice_reason'advance_notice_disputed' | 'instruction_details_amended'

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.

  • advance_notice_disputed - The payer disputes the advance notice of a collection. An advice on its own, with no accompanying change of details
  • instruction_details_amended - The payer's account details on the instruction have changed

Example request

{
  "debtor": {
    "name": "John Debtor",
    "account_number": "87654321",
    "sort_code": "200000"
  },
  "beneficiary": {
    "name": "Mac Donalds",
    "account_number": "87654321",
    "sort_code": "200000"
  },
  "advice_reason": "advance_notice_disputed"
}

Response

Amend intent accepted and enqueued

idstring

Form3-assigned mandate ID

status'AMEND_PENDING' | 'AMENDED' | 'FAILED'

Lifecycle status reachable when amending a mandate.

  • AMEND_PENDING - Amend intent accepted; pending submission to Form3 via the PSP gateway
  • AMENDED - Amend confirmed
  • FAILED - Amend processing failed. Terminal state
versioninteger

The mandate version. Unchanged by the amend mandate endpoint call (Form3 passthrough — not incremented).

Example response

{
  "id": "b254bb5e-6f1a-4c2b-9c1e-2f0a6d3e8c11",
  "status": "AMEND_PENDING",
  "version": 2
}

Changes

No recorded changes to this operation across all 1 revision of this API.