PIpismo
BACS direct debit

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 event (for example SUBMITTED, CONFIRMED, FAILED).

post/v1/payments/bacs/directdebit/paper-mandates

Request

  • Base URL
    https://sandbox.pismolabs.io/bacs
  • URL
    https://sandbox.pismolabs.io/bacs/v1/payments/bacs/directdebit/paper-mandates
  • Auth
    none declared. Required headers: Authorization, Idempotency-key

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

Idempotency-keystring required

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.

Request body

clearing_idstring required

Six-digit clearing ID for the mandate

referencestring required

Mandate reference. Must be unique per organization and use the standard BACS reference character set.

The 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 schemas.

BACS 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.

Permitted characters:

  • Uppercase letters A-Z (lowercase is not allowed — it gets force-uppercased)
  • Digits 0-9
  • Space
  • These four specials only: - (hyphen), . (full stop), & (ampersand), / (solidus)

Reference-field rules on top of the character set:

  • 6-18 characters
  • Must not begin with a space
  • Must not be all the same character (e.g. all zeros)
  • First 4 chars must not be DDIC (reserved for bank/indemnity-claim use)
  • Should be unique per Direct Debit
processing_datestring required

Processing date. Format = yyyy-mm-dd

Example request

{
  "debtor": {
    "name": "John Debtor",
    "account_number": "87654321",
    "sort_code": "200000"
  },
  "beneficiary": {
    "name": "Mac Donalds",
    "account_number": "87654321",
    "sort_code": "200000"
  },
  "clearing_id": "123456",
  "reference": "MANDATE-REF-001",
  "processing_date": "2026-08-10"
}

Response

Mandate created

idstring

Form3-assigned mandate ID

status'CREATED' | 'SUBMITTED' | 'CONFIRMED' | 'FAILED'

Lifecycle status reachable for a created mandate.

  • CREATED - Mandate persisted; pending submission to Form3 via the PSP gateway
  • SUBMITTED - Mandate submitted to the scheme
  • CONFIRMED - Mandate confirmed and active
  • FAILED - Mandate processing failed. Terminal state

Example response

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

Changes

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