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> [ 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 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 (AuthorizationSource)

Required for ACH only

The authorization code indicates how the mandate was authorized.

This defaults to WEB for CustomerType B2C and 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.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "Annually" "EveryTwoYears"
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": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
  • "verificationCheck": {
    • "status": "VERIFIED",
    • "reason": "Verification Successful"
    }
}

Register Mandate draftDeprecated

Role Requirements

tenant-mandate-write or tenant-admin

Description

Register a draft mandate for use.

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
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.
post/v2/mandates/{mandateId}/register
Request samples 
Response samples 
application/json
{
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "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>  (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 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>  (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 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": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "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>  (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/{mandateId}
Request samples 
Response samples 
application/json
{
  • "mandateId": "42bd41f5-2d37-4ebc-8e48-a5fdd309f578",
  • "mandateRef": "AYJ3BR4H67",
  • "network": "Bacs",
  • "mandateType": "BacsB2C",
  • "customerRef": "customer1",
  • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
  • "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 2024 Duck Creek Technologies. All Rights Reserved.