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",
  • "agreementType": "SingleUse",
  • "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.