Mandates

Create and Register a mandate

Role Requirements

tenant-mandate-write or tenant-admin

Description

Create and register a mandate for any supported network.

Validation

Based on the mandateType selection, the validation of the payload in this endpoint changes with the following required fields:

  • BacsB2C: firstName, lastName, accountHolderName, accountNumber, sortCode
  • BacsB2B: companyName, accountHolderName, accountNumber, sortCode
  • SepaB2C: firstName, lastName, accountHolderName, iban
  • SepaB2B: companyName, accountHolderName, iban
  • BecsAuB2C: firstName, lastName, accountHolderName, accountNumber, bsbNumber
  • BecsAuB2B: companyName, accountHolderName, accountNumber, bsbNumber
  • BecsNzB2C: firstName, lastName, accountHolderName, accountNumber, bankName, signatoryName
  • BecsNzB2B: companyName, accountHolderName, accountNumber, bankName, signatoryName
  • AchB2C: firstName, lastName, email, phoneNumber, address, accountHolderName, accountNumber, routingNumber, accountType, authorizationSource, authorizationFrequency
  • AchB2B: companyName, email, phoneNumber, address, accountHolderName, accountNumber, routingNumber, accountType, authorizationSource, authorizationFrequency
Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id (lowercase and hyphenated).

Example: 1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id (lowercase and hyphenated).

Example: ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The details of the new mandate.

customerRef
required
string (CustomerRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$

The client defined unique Customer Reference.

creditorProfileRef
required
string (CreditorProfileRefV2) [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$

Unique reference identifier for the creditor profile. It accepts alphanumeric characters (a to z or digits), as well as the symbols -, _ and ..

mandateType
required
string (MandateType)

The network the mandate is to be registered to, including B2C or B2B flows.

Enum: "BacsB2C" "BacsB2B" "SepaB2B" "SepaB2C" "BecsAuB2C" "BecsAuB2B" "BecsNzB2C" "BecsNzB2B" "AchB2C" "AchB2B"
agreementType
string (AgreementTypeMandate)
Default: "Reuse"

Agreement type associated to the mandate financial instrument.

Enum: "SingleUse" "Reuse"
authorizationSource
string (MandateAuthorizationSource)

Required for ACH only

The authorization code indicates how the mandate was authorized.

This defaults to PPD for B2C and CCD for B2B

Credit direction only supports PPD and CCD

Enum: "CCD" "PPD" "TEL" "WEB"
authorizationFrequency
string (AuthorizationFrequency)

Required for ACH only

The authorization frequency indicates how often the mandate is authorized.

If set to Other, the authorizationFrequencyOtherWording field must be provided.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "EverySixMonths" "Annually" "EveryTwoYears" "Other"
authorizationFrequencyOtherWording
string (AuthorizationFrequencyOtherWording) <= 100 characters ^([a-z0-9 ,()'\-&/]+)$

Required for ACH only

This is the wording displayed to the customer on the ACH Authorization screen during checkout flow, when the authorization frequency is set to Other.

It will be displayed within the following sentence: "To be collected [authorizationFrequencyOtherWording]."

If authorizationFrequency set to Other, then this field is required.

Value must be a string with a minimum length of 1 and a maximum length of 100 characters, and can contain only the following characters: lowercase letters, numbers, space, comma, parentheses, single quote, hyphen, ampersand, forward slash.

required
object (DebtorDetailsRequestV2)

Debtor details

object or null (MetadataV2)

A collection of key-value pairs defined by the client. This object is subject to the following limits:

  • Maximum of 15 keys.
  • Keys have a maximum length of 64 characters.
  • Values have a maximum length of 256 characters.
Responses
201

Mandate created and registered.

400

Bad Request - Validation error response, containing errors such as:

  • The attribute Debtor.Address.Postcode is invalid. Maximum length is 8.
  • The attribute Debtor.Address.City is invalid. Maximum length is 100.
  • The attribute Debtor.AccountNumber is invalid. Length must be 8.
  • The attribute Debtor.AccountNumber is invalid. Format must match "^(?!(?:0{8}))(?:\d{8})$".
  • The attribute Debtor.SortCode is invalid. Length must be 6.
  • The attribute Debtor.SortCode is invalid. Format must match "^(?!(?:0{6}))(?:\d{6})$".
401

Unauthorized

403

Forbidden

post/v2/mandates
Request samples
application/json

B2C flow for the Bacs network

Required Debtor properties: firstName, lastName, accountHolderName, accountNumber, sortCode

{
  • "customerRef": "customer1",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "mandateType": "BacsB2C",
  • "agreementType": "Reuse",
  • "debtor": {
    • "firstName": "John",
    • "lastName": "Smith",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "language": "en",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "postcode": "AB12 3CD",
      • "city": "London"
      },
    • "accountHolderName": "MR J SMITH",
    • "accountNumber": "12345674",
    • "sortCode": "400515"
    }
}
Response samples
application/json
{
  • "financialInstrumentId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}

Cancel active Mandate

Role Requirements

tenant-mandate-write or tenant-admin

Description

Cancel mandate.

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> = 36 characters

The system's unique identifier for the mandate (lowercase and hyphenated).

Example: 719d246a-7c03-4a47-9dc5-924a0df12889
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id (lowercase and hyphenated).

Example: 1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id (lowercase and hyphenated).

Example: ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The details of the cancellation.

reason
string

The reason for the cancellation of the mandate.

Responses
204

Cancelled.

401

Unauthorized.

403

Forbidden.

404
  • Not Found - Mandate '00000000-0000-0000-0000-000000000000' was not found.
post/v2/mandates/{mandateId}/cancel
Request samples
application/json
{
  • "reason": "Service subscription cancelled."
}
Response samples
application/json

Mandate was not found.

{
  • "title": "NOT_FOUND",
  • "detail": "See validation errors.",
  • "timestamp": "2021-01-30T08:30:00Z",
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "status": 404,
  • "traceId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "title": "MANDATE_NOT_FOUND",
      • "detail": "Mandate '00000000-0000-0000-0000-000000000000' was not found."
      }
    ]
}

Amend an active Mandate

Role Requirements

tenant-mandate-write or tenant-admin

Description

Amend an existing active mandate.

Please note that the type of the mandate cannot be changed. For example, a mandate cannot be changed from B2C to B2B.

Validation

Based on the mandateType of the mandate, the validation of the payload in this endpoint changes with the following required debtor fields:

  • BacsB2C: firstName, lastName, accountHolderName, accountNumber, sortCode
  • BacsB2B: companyName, accountHolderName, accountNumber, sortCode
  • SepaB2C: firstName, lastName, accountHolderName, iban
  • SepaB2B: companyName, accountHolderName, iban
  • BecsAuB2C: firstName, lastName, accountHolderName, accountNumber, bsbNumber
  • BecsAuB2B: companyName, accountHolderName, accountNumber, bsbNumber
  • BecsNzB2C: firstName, lastName, accountHolderName, accountNumber, bankName, signatoryName
  • BecsNzB2B: companyName, accountHolderName, accountNumber, bankName, signatoryName
  • AchB2C: firstName, lastName, email, phoneNumber, address, accountHolderName, accountNumber, routingNumber, accountType
  • AchB2B: companyName, email, phoneNumber, address, accountHolderName, accountNumber, routingNumber, accountType
Securitybearer
Request
path Parameters
mandateId
required
string <uuid> = 36 characters

The system's unique identifier for the mandate (lowercase and hyphenated).

Example: 719d246a-7c03-4a47-9dc5-924a0df12889
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id (lowercase and hyphenated).

Example: 1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id (lowercase and hyphenated).

Example: ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The amended mandate details.

required
object (DebtorDetailsRequestV2)

Debtor details

Responses
202

Amending mandate.

400

Bad Request - Validation error response, containing errors such as:

  • Mandate is not in state Active, and cannot be amended.
  • The attribute Debtor.FirstName is required.
  • The attribute Debtor.LastName is required.
  • The attribute Debtor.Address.StreetAddress is required.
  • The attribute Debtor.Address.Postcode is required.
  • The attribute Debtor.Address.Postcode is invalid. Maximum length is 8.
  • The attribute Debtor.Address.City is required.
  • The attribute Debtor.Address.City is invalid. Maximum length is 100.
  • The attribute Debtor.Address.Country is invalid. Maximum length is 100.
  • The attribute Debtor.AccountNumber is required.
  • The attribute Debtor.SortCode is required.
  • The attribute Debtor.AccountNumber is invalid. Length must be 8.
  • The attribute Debtor.SortCode is invalid. Length must be 6.
  • The attribute Debtor.AccountNumber is invalid. Format must match "^(?!(?:0{8}))(?:\d{8})$".
  • The attribute Debtor.SortCode is invalid. Format must match "^(?!(?:0{6}))(?:\d{6})$".
401

Unauthorized

403

Forbidden

404
  • Not Found - Mandate '00000000-0000-0000-0000-000000000000' was not found.
put/v2/mandates/{mandateId}/amend
Request samples
application/json

What a typical request looks like for a Bacs B2C mandate amendment

Required Debtor properties: firstName, lastName, accountHolderName, accountNumber, sortCode

{
  • "debtor": {
    • "firstName": "Joe",
    • "lastName": "Bloggs",
    • "email": "joe.bloggs@gmail.com",
    • "language": "en",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "postcode": "AB12 3CD",
      • "city": "London"
      },
    • "accountHolderName": "JOE BLOGGS",
    • "accountNumber": "12345674",
    • "sortCode": "400515"
    }
}
Response samples
application/json
{
  • "financialInstrumentId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}

Get Mandate

Role Requirements

tenant-mandate-read or tenant-admin

Description

Get a mandate

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> = 36 characters

The system's unique identifier for the mandate (lowercase and hyphenated).

Example: 719d246a-7c03-4a47-9dc5-924a0df12889
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id (lowercase and hyphenated).

Example: 1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id (lowercase and hyphenated).

Example: ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string

Correlation Id for the request.

Responses
200

Returns a mandate.

401

Unauthorized

403

Forbidden

404
  • Not Found - Mandate '00000000-0000-0000-0000-000000000000' was not found.
get/v2/mandates/{mandateId}
Request samples 
Response samples 
application/json
{
  • "mandateId": "42bd41f5-2d37-4ebc-8e48-a5fdd309f578",
  • "mandateRef": "AYJ3BR4H67",
  • "network": "Bacs",
  • "mandateType": "BacsB2C",
  • "agreementType": "Reuse",
  • "customerRef": "customer1",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "financialInstrumentId": "aab0c9b1-5448-453a-bcf4-35c56508ce4a",
  • "created": "2025-02-28T13:45:59.871Z",
  • "debtor": {
    • "firstName": "John",
    • "lastName": "Smith",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "language": "en",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "postcode": "AB12 3CD",
      • "city": "London"
      },
    • "accountHolderName": "MR J SMITH",
    • "accountNumber": "12345674",
    • "sortCode": "400515"
    }
}
Copyright 2025 Duck Creek Technologies. All Rights Reserved.