Mandates

Get Creditor Profiles (paged)

Role Requirements

tenant-mandate-read or tenant-admin

Description

Obtain a paginated list of Creditor Profiles, regardless of their associated network. Creditor Profile entities returned by this operation will only include common attributes and a link to their full details.

Securitybearer
Request
query Parameters
from
integer <int32>
Default: 0

The item from which to start (skip from-1 items) the search.

take
integer <int32> [ 1 .. 1000 ]
Default: 100

The maximum number of items to return from the search.

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

A successful response containing a paginated list of Creditor Profiles.

401

Unauthorized

403

Forbidden

get/v2/mandates/creditor-profiles
Request samples 
Response samples 
application/json
{
  • "currentPage": 0,
  • "pageCount": 0,
  • "pageSize": 0,
  • "rowCount": 0,
  • "totalCount": 0,
  • "results": [
    • {
      • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
      • "profileName": "A_PROFILE_NAME_0",
      • "network": "SEPA",
      • "metadata": {
        • "property1": "string",
        • "property2": "string"
        },
      • "status": "string",
      • "created": "string"
      }
    ]
}
Get Mandates (paged)
Role Requirements


tenant-mandate-read or tenant-admin


Description


Get mandates.


Securitybearer 
Request 
query Parameters
from
integer <int32> 
 Default:  0
The item from which to start (skip from-1 items) the search.


 
take
integer <int32>   [ 1 .. 1000 ] 
 Default:  100
The maximum number of items to return from the search.


 
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 collection of mandates.


401
Unauthorized


403
Forbidden


get/v2/mandates
Request samples 
Response samples 
application/json
{
  • "currentPage": 0,
  • "pageCount": 0,
  • "pageSize": 0,
  • "rowCount": 0,
  • "totalCount": 0,
  • "results": [
    • {
      • "mandateId": "d8c0e545-7d18-46b5-b807-aca31afc254f",
      • "mandateRef": "string",
      • "network": "SEPA",
      • "mandateType": "BacsB2C",
      • "customerRef": "string",
      • "status": "Draft",
      • "creditorProfileRef": "fb39d6eb3ac44d6597f0f7221da5e663",
      • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
      • "created": "2019-08-24T14:15:22Z",
      • "metadata": {
        • "property1": "string",
        • "property2": "string"
        }
      }
    ]
}
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 debtor fields:


    

  • BacsB2C: firstName, lastName, accountHolderName, accountNumber, sortCode
    • 

  • BacsB2B: companyName, accountHolderName, accountNumber, sortCode
    • 

  • SepaB2C: firstName, lastName, accountHolderName, iban
    • 

  • SepaB2B: companyName, accountHolderName, iban
    • 



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"  
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@gmail.com",
    • "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 draft
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
    • 



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",
    • "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"
    }
}
Copyright © Imburse AG 2018-2022. All right reserved.