Mandates (BACS)

Get BACS Creditor ProfileDeprecated

Role Requirements

tenant-mandate-read or tenant-admin

Description

Returns the details of a Bacs Creditor Profile. These include its Service User Number and the Organization Name.

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

Returns a creditor profile.

Example: fb39d6eb3ac44d6597f0f7221da5e663
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Responses
200

Returns a Bacs Creditor Profile.

401

Unauthorized

403

Forbidden

404
  • Not Found - Creditor Profile was not found.
get/v2/mandates/creditor-profiles/bacs/{creditorProfileRef}
Request samples
Response samples
application/json
{
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "profileName": "A_PROFILE_NAME_0",
  • "network": "SEPA",
  • "serviceUserNumber": "string",
  • "organizationName": "string",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}

Create BACS Creditor ProfileDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Create a Bacs Creditor Profile.

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The full details of the new Bacs Creditor-Profile.

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

profileName
required
string (ProfileNameV2) [ 1 .. 100 ] characters

A user-friendly name for the creditor profile that can easily be recognized.

serviceUserNumber
required
string = 6 characters ^[0-9]{6}$

The 6 digit Service User Number assigned to the entity within Bacs.

organizationName
required
string [ 1 .. 100 ] characters

The organization's name as it will appear on the debtor's bank account statement.

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

Creditor profile created.

400

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

  • The attribute CreditorProfileRef is required.
  • The attribute ProfileName is required.
  • The attribute ServiceUserNumber is required.
  • The attribute OrganizationName is required.
401

Unauthorized

403

Forbidden

post/v2/mandates/creditor-profiles/bacs
Request samples
application/json
{
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "profileName": "A_PROFILE_NAME_0",
  • "serviceUserNumber": "string",
  • "organizationName": "string",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Response samples
application/json

CreditorProfileRef was not specified.

{
  • "title": "BAD_REQUEST",
  • "detail": "See validation errors.",
  • "timestamp": "2021-01-30T08:30:00Z",
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "status": 400,
  • "traceId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "title": "REQUIRED_ATTRIBUTE",
      • "detail": "The attribute CreditorProfileRef is required",
      • "metadata": {
        • "PropertyName": "CreditorProfileRef",
        • "AttemptedValue": "null",
        • "ErrorMessage": "The attribute CreditorProfileRef is required"
        }
      }
    ]
}

Create BACS Mandate draftDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Create draft Bacs mandate.

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The details of the new draft Bacs mandate.

customerRef
string
creditorProfileRef
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 ..

object (BacsDebtorDetailsDraftRequestV2)
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 draft created.

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/bacs
Request samples
application/json
{
  • "customerRef": "string",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Response samples
application/json
{
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f"
}

Update and register BACS Mandate draftDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Update and register a draft Bacs mandate.

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> (MandateIdV2) [ 1 .. 50 ] characters

The system's unique identifier for the mandate.

Example: d8c0e545-7d18-46b5-b807-aca31afc254f
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The full details of the updated draft Bacs mandate.

customerRef
required
string [ 1 .. 50 ] characters
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 ..

required
object (BacsDebtorDetailsRequestV2)
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 draft updated.

Registering mandate.

400

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

  • The attribute MandateId is required.
  • Mandate is not in state Draft, and cannot be edited.
  • The attribute CustomerRef is required.
  • The attribute CreditorProfileRef is required.
  • 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/bacs/{mandateId}/register
Request samples
application/json
{
  • "customerRef": "string",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "state": "Kent",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Response samples
application/json
{
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}

Create and register BACS MandateDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Create and register a new draft Bacs mandate in a single step, without the need for a pre-existing Bacs Mandate in DRAFT status.

Upon a success message, the resulting Bacs Mandate will be put into a PROCESSING status.

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The full details of the new Bacs mandate.

customerRef
required
string [ 1 .. 50 ] characters
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 ..

required
object (BacsDebtorDetailsRequestV2)
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 draft created.

400

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

  • The attribute CustomerRef is required.
  • The attribute CreditorProfileRef is required.
  • 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

post/v2/mandates/bacs/register
Request samples
application/json
{
  • "customerRef": "string",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "state": "Kent",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Response samples
application/json
{
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}

Get BACS MandateDeprecated

Role Requirements

tenant-mandate-read or tenant-admin

Description

Get Bacs mandate.

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> (MandateIdV2) [ 1 .. 50 ] characters

The system's unique identifier for the mandate.

Example: d8c0e545-7d18-46b5-b807-aca31afc254f
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

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/bacs/{mandateId}
Request samples
Response samples
application/json
{
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "mandateRef": "string",
  • "network": "SEPA",
  • "mandateType": "BacsB2C",
  • "customerRef": "string",
  • "status": "Draft",
  • "inactiveReason": {
    • "reasonCode": "DebtorCancelled",
    • "description": "The mandate was cancelled at a bank branch."
    },
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "created": "2019-08-24T14:15:22Z",
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "companyName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "language": "en",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    },
  • "documentType": "Paper",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}

Update BACS Mandate draftDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Update draft Bacs mandate.

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> (MandateIdV2) [ 1 .. 50 ] characters

The system's unique identifier for the mandate.

Example: d8c0e545-7d18-46b5-b807-aca31afc254f
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The details of the updated draft Bacs mandate.

customerRef
string
creditorProfileRef
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 ..

object (BacsDebtorDetailsDraftRequestV2)
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
204

Mandate draft updated successfully.

400

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

  • The attribute MandateId is required.
  • Mandate is not in state Draft, and cannot be edited.
  • 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

404
  • Not Found - Mandate '00000000-0000-0000-0000-000000000000' was not found.
put/v2/mandates/bacs/{mandateId}
Request samples
application/json
{
  • "customerRef": "string",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Response samples
application/json

Account number was not the correct length.

{
  • "title": "BAD_REQUEST",
  • "detail": "See validation errors.",
  • "timestamp": "2021-01-30T08:30:00Z",
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "status": 400,
  • "traceId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "title": "INVALID_ATTRIBUTE",
      • "detail": "The attribute Debtor.AccountNumber is invalid. Length must be 8.",
      • "metadata": {
        • "PropertyName": "Debtor.AccountNumber",
        • "AttemptedValue": "123",
        • "ErrorMessage": "The attribute Debtor.AccountNumber is invalid. Length must be 8."
        }
      }
    ]
}

Update BACS MandateDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Amend a Bacs mandate.

Securitybearer
Request
path Parameters
mandateId
required
string <uuid> (MandateIdV2) [ 1 .. 50 ] characters

The system's unique identifier for the mandate.

Example: d8c0e545-7d18-46b5-b807-aca31afc254f
header Parameters
x-account-id
required
string <uuid> [ 1 .. 50 ] characters

The Account Id.

x-tenant-id
required
string <uuid> (TenantIdV2) [ 1 .. 50 ] characters

The Tenant Id.

x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

The amended Bacs mandate details.

required
object (BacsDebtorDetailsRequestV2)
Responses
201

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.
post/v2/mandates/bacs/{mandateId}/amend
Request samples
application/json
{
  • "debtor": {
    • "firstName": "string",
    • "lastName": "string",
    • "email": "JohnDangerSmith@imbursepayments.com",
    • "address": {
      • "houseNumberOrName": "123A",
      • "streetAddress": "Upper Great Street",
      • "extendedAddress": "string",
      • "postcode": "AB12 3CD",
      • "city": "London",
      • "state": "Kent",
      • "country": "GB"
      },
    • "accountNumber": "12345678",
    • "sortCode": "123456",
    • "bankAccountName": "BANK/JSMITH1234.32"
    }
}
Response samples
application/json
{
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}
Copyright 2024 Duck Creek Technologies. All Rights Reserved.