PIpismo
BACS direct debit

Raise BACS Direct Debit indemnity claim [beta]

Create a BACS Direct Debit Indemnity Claim (DDIC).

A DDIC reclaims money that was incorrectly debited from a payer's account under the Direct Debit Guarantee. The claim is validated and persisted, then submitted asynchronously to the BACS scheme via Form3.

Notes:

  • The operation is idempotent via the Idempotency-key header.

  • The claim is persisted with status = CREATED and submitted asynchronously. Creation itself returns immediately.

  • Subsequent status transitions generate a BACS direct debit claim status changed event.

post/v1/payments/bacs/directdebit/claims

Request

  • Base URL
    https://sandbox.pismolabs.io/bacs
  • URL
    https://sandbox.pismolabs.io/bacs/v1/payments/bacs/directdebit/claims
  • 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

The six-digit Bacs Service User Number (SUN) of the institution raising the claim

referencestring required

Claim reference. Must begin with DDIC followed by 2-6 alphanumeric characters (maximum length 18).

BACS reserves the DDIC prefix for indemnity-claim references.

reason_code'1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' required

Direct Debit Indemnity Claim (DDIC) reason code. BACS DDIC scheme rules that indicate why the indemnity claim is being raised:

  • 1— The amount and/or date collected differs from the advance notice.

  • 2— No advance notice was received (or the payment was collected earlier than notified).

  • 3— The Direct Debit Instruction (DDI) is disputed / no valid mandate is held.

  • 4— The payer canceled the DDI directly with the service user.

  • 5— The account holder is deceased.

  • 6— The payer canceled the DDI with their bank.

  • 7— Claim raised at the service user's request.

  • 8— Service user name disputed / the payer does not recognise the collecting service user.

Conditional fields:

  • 3—processing_date is REQUIRED.

  • 7—contact_name and request_date are REQUIRED.

number_of_transactionsinteger

If passed, it must equal the number of disputed_transactions. Maximum 12.

processing_datestring date

Processing date.

REQUIRED when reason_code = 3. Do NOT pass otherwise.

Format = YYYY-MM-DD.

contact_namestring

Service user contact name.

REQUIRED if reason_code = 7. Do NOT pass otherwise.

Must NOT be all spaces.

request_datestring date

Service user request date. Format = YYYY-MM-DD.

REQUIRED when reason_code = 7. Do NOT pass otherwise.

reasonstring

Free-text reason for the claim

Example request

{
  "clearing_id": "123456",
  "reference": "DDIC0001AB",
  "reason_code": "1",
  "original_instruction": {
    "clearing_id": "123456",
    "reference": "MANDATE-REF-001"
  },
  "disputed_transactions": [
    {
      "amount": "125.00",
      "date": "2026-08-15"
    }
  ],
  "number_of_transactions": 1,
  "processing_date": "2026-08-20",
  "contact_name": "Jane Smith",
  "request_date": "2026-08-18",
  "reason": "Duplicate collection"
}

Response

Claim created

idstring

Pismo-assigned local claim ID

status'CREATED' | 'PROCESSING' | 'CONFIRMED' | 'FAILED'

DDIC claim / claim-reversal lifecycle status_reason:

  • CREATED—Claim persisted, pending submission to the scheme via Form3.

  • PROCESSING—Claim submitted and in flight through Form3 / the scheme.

  • CONFIRMED—Claim delivery confirmed by the scheme. Terminal state.

  • FAILED—Claim rejected or failed validation/submission. Terminal state.

Example response

{
  "id": "019e92ec-3362-7c54-9d17-89f5542a06e4",
  "status": "CREATED"
}

Changes

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