CHAPS Payments

This section describes the process of creating payments via the CHAPS (Clearing House Automated Payment System) for GBP transfers.

When to Use CHAPS

Mandatory: transfer amount > £1,000,000
Optional: amount ≤ £1,000,000 (by choice, alternative — FPS)
Maximum amount: £1,000,000,000

⚠️ CHAPS Restrictions:

Operating hours: 08:00–17:00 UK time, Mon-Fri, excluding bank holidays

Standing orders not available

Reference: maximum 35 characters

1. Calculate Price and Determine Payment Scheme

POST /api/core/public/customers/{customerId}/payments/calculate-price

Call this endpoint to get the payment cost and determine the applicable payment scheme.

Request:

{
  "debtorAccountId": "uuid",
  "payeeContactId": "uuid",
  "amount": {
    "currencyCode": "gbp",
    "value": 1500000.00
  },
  "paymentScheme": "chaps"
}

Field	Required	Description
`paymentScheme`	No	Pass `"chaps"` to explicitly select CHAPS. Applied automatically for amounts > £1M

Response:

{
  "intialAmount": 1500000.00,
  "totalPrice": 25.00,
  "totalAmount": 1500025.00,
  "purposeDiscriminator": "chaps"
}

Field	Description
`purposeDiscriminator`	Identifies the name of payment purposes collection: `chaps`, `fps`, `sepa`, `swift`, `digidoe`

💡 TIP: If purposeDiscriminator = "chaps", you must provide paymentPurposeId and paymentPurposeCategoryId when initiating the payment.

2. Get Purpose Categories / Codes Reference

GET /api/core/public/customers/{customerId}/payments/order-purposes?purposeDiscriminator=chaps

For CHAPS payments, specifying the purpose category and code is mandatory.

Response:

{
  "purposes": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "SALA",
      "description": "Salary Payment"
    },
    {
      "id": "7fa85f64-5717-4562-b3fc-2c963f66afa7",
      "code": "SUPP",
      "description": "Supplier Payment"
    }
  ],
  "purposeCategories": [
    {
      "id": "8fa85f64-5717-4562-b3fc-2c963f66afa8",
      "code": "WAGE",
      "description": "Wages",
      "purposeIds": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  ]
}

💡 TIP: Use purposeIds from the selected category to filter available Purpose Codes.

3. Initiate CHAPS Payment

POST /api/core/public/customers/{customerId}/payments/initiate

Request:

{
  "id": "uuid",
  "debtorAccountId": "uuid",
  "payeeContactId": "uuid",
  "amount": {
    "currencyCode": "gbp",
    "value": 1500000.00
  },
  "paymentScheme": "chaps",
  "paymentPurposeId": "uuid",
  "paymentPurposeCategoryId": "uuid",
  "reference": "Invoice #12345"
}

Field	Required	Description
`paymentScheme`	Yes (for CHAPS)	Pass `"chaps"`
`paymentPurposeId`	Yes (for CHAPS)	ID from purposes reference
`paymentPurposeCategoryId`	Yes (for CHAPS)	ID from purposeCategories reference
`reference`	No	Payment description, up to 35 characters for CHAPS

Error Handling

Error Code	Description	Recommendation
`FOR_GBP>1M_USE_CHAPS`	Amount > £1M without CHAPS specified	Pass `paymentScheme: "chaps"`
`400 Validation Error`	Required fields missing	Verify `paymentPurposeId` and `paymentPurposeCategoryId` are provided

Payments Outside Operating Hours

If a payment is initiated outside CHAPS operating hours (before 08:00, after 17:00 UK time, weekends, or bank holidays), it will be automatically scheduled for the next working day.

When to Use CHAPS​

1. Calculate Price and Determine Payment Scheme​

2. Get Purpose Categories / Codes Reference​

3. Initiate CHAPS Payment​

Error Handling​

Payments Outside Operating Hours​