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
  • AchB2B: companyName, email, phoneNumber, address, accountHolderName, accountNumber, routingNumber, accountType, authorizationSource
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"
authorizationSource
string (AuthorizationSource)

Required for ACH only

The authorization code indicates how the mandate was authorized.

Enum: "CCD" "PPD" "TEL" "WEB"
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",
  • "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
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.
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.