---
updatedAt: 2026-10-07T16:46:14.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# 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](https://developers.pismo.io/events/docs/bacs-direct-debit-claim-status-change-1) event.

For more information, refer to the [BACS Direct Debut indemity claims](doc:bacs-direct-debit-indemity-claims) guide.


# 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 <b>401 Unauthorized</b> message\n",
        "required": true
      },
      "idempotencyKeyHeader": {
        "name": "Idempotency-key",
        "in": "header",
        "schema": {
          "type": "string",
          "maxLength": 32
        },
        "description": "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.\n",
        "required": true
      }
    },
    "schemas": {
      "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"
          }
        }
      },
      "mandateClearingId": {
        "type": "string",
        "pattern": "^[0-9]{6}$",
        "description": "Six-digit clearing ID for the mandate",
        "example": "123456"
      },
      "claim.id": {
        "type": "string",
        "description": "Pismo-assigned local claim ID",
        "example": "019e92ec-3362-7c54-9d17-89f5542a06e4"
      },
      "claim.reference": {
        "type": "string",
        "maxLength": 18,
        "pattern": "^DDIC[A-Za-z0-9]{2,14}$",
        "description": "Claim reference. Must begin with `DDIC` followed by 2-6 alphanumeric characters (maximum length 18). \n\nBACS reserves the `DDIC` prefix for indemnity-claim references.\n",
        "example": "DDIC0001AB"
      },
      "claim.reasonCode": {
        "type": "string",
        "description": "Direct Debit Indemnity Claim (DDIC) reason code. BACS DDIC scheme rules that indicate why the indemnity claim is being raised:\n\n  * `1`— The amount and/or date collected differs from the advance notice.\n\n  * `2`— No advance notice was received (or the payment was collected earlier than notified).\n\n  * `3`— The Direct Debit Instruction (DDI) is disputed / no valid mandate is held.\n\n  * `4`— The payer canceled the DDI directly with the service user.\n\n  * `5`— The account holder is deceased.\n\n  * `6`— The payer canceled the DDI with their bank.\n\n  * `7`— Claim raised at the service user's request.\n\n  * `8`— Service user name disputed / the payer does not recognise the collecting service user.\n\nConditional fields:\n\n  * `3`—`processing_date` is **REQUIRED**.\n\n  * `7`—`contact_name` and `request_date` are **REQUIRED**.\n",
        "enum": [
          "1",
          "2",
          "3",
          "4",
          "5",
          "6",
          "7",
          "8"
        ],
        "example": "1"
      },
      "claim.status": {
        "type": "string",
        "description": "DDIC claim / claim-reversal lifecycle status_reason:\n\n  * `CREATED`—Claim persisted, pending submission to the scheme via Form3.\n\n  * `PROCESSING`—Claim submitted and in flight through Form3 / the scheme.\n\n  * `CONFIRMED`—Claim delivery confirmed by the scheme. Terminal state.\n\n  * `FAILED`—Claim rejected or failed validation/submission. Terminal state.\n",
        "enum": [
          "CREATED",
          "PROCESSING",
          "CONFIRMED",
          "FAILED"
        ],
        "example": "CREATED"
      },
      "claim.OriginalInstruction": {
        "type": "object",
        "description": "Original Direct Debit Instruction (DDI) the claim relates to",
        "required": [
          "clearing_id",
          "reference"
        ],
        "properties": {
          "clearing_id": {
            "$ref": "#/components/schemas/mandateClearingId"
          },
          "reference": {
            "type": "string",
            "maxLength": 18,
            "description": "Original Direct Debit Instruction reference",
            "example": "MANDATE-REF-001"
          }
        }
      },
      "claim.DisputedTransaction": {
        "type": "object",
        "description": "Single disputed Direct Debit collection included in the claim",
        "required": [
          "amount",
          "date"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "maxLength": 20,
            "description": "Disputed transaction amount",
            "example": "125.00"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Disputed transaction date. Format = YYYY-MM-DD.",
            "example": "2026-08-15"
          }
        }
      },
      "claim.CreateRequest": {
        "type": "object",
        "description": "Payload to create a DDIC claim",
        "required": [
          "clearing_id",
          "reference",
          "reason_code",
          "original_instruction",
          "disputed_transactions"
        ],
        "properties": {
          "clearing_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/mandateClearingId"
              },
              {
                "description": "The six-digit BACS Service User Number (SUN) of the institution raising the claim"
              }
            ]
          },
          "reference": {
            "$ref": "#/components/schemas/claim.reference"
          },
          "reason_code": {
            "$ref": "#/components/schemas/claim.reasonCode"
          },
          "original_instruction": {
            "$ref": "#/components/schemas/claim.OriginalInstruction"
          },
          "disputed_transactions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "$ref": "#/components/schemas/claim.DisputedTransaction"
            }
          },
          "number_of_transactions": {
            "type": "integer",
            "format": "int32",
            "maximum": 12,
            "description": "If passed, it **must** equal the number of `disputed_transactions`. Maximum 12.\n",
            "example": 1
          },
          "processing_date": {
            "type": "string",
            "format": "date",
            "description": "Processing date.\n\n**REQUIRED** when `reason_code` = `3`. Do **NOT** pass otherwise. \n\nFormat = YYYY-MM-DD.\n",
            "example": "2026-08-20"
          },
          "contact_name": {
            "type": "string",
            "maxLength": 51,
            "description": "Service user contact name. \n\n**REQUIRED** if `reason_code` = `7`. Do **NOT** pass otherwise. \n\nMust **NOT** be all spaces.\n",
            "example": "Jane Smith"
          },
          "request_date": {
            "type": "string",
            "format": "date",
            "description": "Service user request date. Format = YYYY-MM-DD.\n\n**REQUIRED** when `reason_code` = `7`. Do **NOT** pass otherwise. \n",
            "example": "2026-08-18"
          },
          "reason": {
            "type": "string",
            "maxLength": 255,
            "description": "Free-text reason for the claim",
            "example": "Duplicate collection"
          }
        }
      },
      "claim.CreateResponse": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/claim.id"
          },
          "status": {
            "$ref": "#/components/schemas/claim.status"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/payments/bacs/directdebit/claims": {
      "post": {
        "summary": "Raise BACS Direct Debit indemnity claim [beta]",
        "description": "\nCreate a BACS Direct Debit Indemnity Claim (DDIC).\n\nA 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.\n\n**Notes:**\n\n  * The operation is idempotent via the `Idempotency-key` header. \n\n  * The claim is persisted with `status` = `CREATED` and submitted asynchronously. Creation itself returns immediately. \n  \n  * Subsequent status transitions generate a [BACS direct debit claim status changed](https://developers.pismo.io/events/docs/bacs-direct-debit-claim-status-change-1) event.\n\nFor more information, refer to the [BACS Direct Debut indemity claims](doc:bacs-direct-debit-indemity-claims) guide.\n",
        "operationId": "post-create-claim",
        "tags": [
          "BACS direct debit"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/authHeader"
          },
          {
            "$ref": "#/components/parameters/idempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "description": "Raise claim request body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/claim.CreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Claim created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/claim.CreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0004": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "EBACS0004",
                      "message": "Validation 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"
                    }
                  },
                  "EBACS0086": {
                    "summary": "Missing Idempotency Key",
                    "value": {
                      "code": "EBACS0086",
                      "message": "Missing required header: 'Idempotency-Key'"
                    }
                  },
                  "EBACS0021": {
                    "summary": "Account Blocked Or Cancelled",
                    "value": {
                      "code": "EBACS0021",
                      "message": "Account blocked or cancelled"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0058": {
                    "summary": "Record Already Exists",
                    "value": {
                      "code": "EBACS0058",
                      "message": "Record already exists"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```