PIpismo
BACS direct debit

Cancel BACS mandate [beta]

Cancel a BACS direct debit mandate.

Cancel of an existing mandate, applied asynchronously through the BACS scheme.

Notes:

  • The cancel is persisted with status = CANCEL_PENDING under the payer account, and enqueued for the asynchronous submission worker, which submits it to Form3 through the PSP gateway.

  • Allowed only when the mandate is in 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 it.

  • The optional status_reason records why the mandate is being cancelled; it is persisted on the mandate and forwarded on the generated event.

  • This endpoint moves the mandate to status = CANCEL_PENDING and generates a BACS mandate status changed event. Subsequent status transitions generate further events (for example CANCELLED, FAILED).

post/v1/payments/bacs/directdebit/mandates/{id}/cancel

Request

  • Base URL
    https://sandbox.pismolabs.io/bacs
  • URL
    https://sandbox.pismolabs.io/bacs/v1/payments/bacs/directdebit/mandates/{id}/cancel
  • 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.

status_reason'account_closed' | 'account_transferred_to_new_psp' | 'cancelled_by_originator' | 'cancelled_by_payer' | 'payer_deceased' | 'paying_bank_cancellation'

Reason code for the cancellation (mirrors Form3's mandate cancellation reasons). The client sends only the code; the human-readable description is derived server-side.

  • account_closed - Account closed
  • account_transferred_to_new_psp - Account transferred to a new PSP
  • cancelled_by_originator - Cancelled by originator
  • cancelled_by_payer - Cancelled by payer
  • payer_deceased - Payer deceased
  • paying_bank_cancellation - Paying bank cancellation

Example request

{
  "status_reason": "account_closed"
}

Response

Cancel intent accepted and enqueued

idstring

Form3-assigned mandate ID

status'CANCEL_PENDING' | 'CANCELLED' | 'FAILED'

Lifecycle status reachable when cancelling a mandate.

  • CANCEL_PENDING - Cancel intent accepted; pending submission to Form3 via the PSP gateway
  • CANCELLED - Mandate cancelled. Terminal state
  • FAILED - Cancel processing failed. Terminal state
versioninteger

Mandate version. This call does not change it (Form3 passthrough — not incremented).

Example response

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

Changes

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