Direct Debit

Customer Manipulation

A customer record captures the personal and banking details of the person or organisation that you wish to collect funds from. A customer record needs to be created before a Direct Debit (contract) record can be created to collect payments. There can be multiple Direct Debits (contracts) attached to a customer record.

Important: you are required to perform a modulus check on bank account numbers and sort codes before they are passed to the API. We can offer a bank checking API on a pay-per-use basis — please contact our sales team for details on pricing. Failure to modulus check data is likely to cause problems in processing your payments.
GET/client/{clientCode}/customerQueries the database for a set of customers#
description:

NOTE: The response from a GET method includes an IsArchived flag. On a newly created customer, this will show as true which is normal. The record will automatically change to false when an associated live Direct Debit (contract) is attached to it.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
query parameters:
{
  • pageSize
    floatThe number of customer records to return per page. If this parameter is omitted or 0 is passed in, no pagination will be used.
  • pageNumber
    floatThe current page of results you wish to view.
  • includePagingDetail
    booleanDefault is false. If true, adds extra JSON metadata in the response to help callers using pagination.
  • includeMemos
    booleanDefault is true. If true, includes an array of Memos for each customer record returned. If false, Memos will return null for every customer.
  • email
    string (≤ 255 chars)The customer’s contact email address.
  • title
    string (≤ 10 chars)The customer’s title (Mr/Mrs/Ms/Miss/Mx etc).
  • from
    string (date-time)The date/time from which you want to find new customers added. Format: YYYY-MM-DDT00:00:00.000
  • to
    string (date-time)The date/time to which you want to find new customers added. Format: YYYY-MM-DDT00:00:00.000
  • dateOfBirth
    string (date-time)The customer’s date of birth. Format: YYYY-MM-DDT00:00:00.000
  • customerRef
    string (≤ 255 chars)A unique reference number allocated by the client for this customer.
  • firstName
    string (≤ 255 chars)The customer's first name.
  • surname
    string (≤ 255 chars)The customer's surname.
  • companyName
    string (≤ 255 chars)The company name of the customer (if applicable).
  • postCode
    string (≤ 8 chars)The customer's Post Code.
  • accountNumber
    string (8 chars, digits 0-9 only)The customer's bank account number. This must be eight numerical characters with all leading zeros left intact. Examples include: 01065284, 00000000, 26280464. Any non-numerical characters must be removed before passing the data to the API.
  • bankSortCode
    string (6 chars, digits 0-9 only)The customer's bank sort code. This must be six numerical characters with all leading zeros left intact. Examples include: 089286 100000 600000, 230580. In the United Kingdom it is sometimes customary to insert dashes/hyphens between groups of two characters (e.g. 08-92-86, 23-05-80). Any hyphens, dashes or non-numerical characters must be removed before being passed to the API.
  • accountHolderName
    string (≤ 18 chars)The name of the customer's bank account. This must be a maximum of eighteen alphanumeric characters [0-9a-zA-Z ]. A space is also allowed. Any special characters or punctuation such as ampersands, apostrophes, hyphens, slashes, backslashes, commas, full stops etc. must be removed before passing to the API.
  • homePhoneNumber
    string (≤ 20 chars)The customer's home telephone number.
  • workPhoneNumber
    string (≤ 18 chars)The customer's work telephone number.
  • mobilePhoneNumber
    string (≤ 18 chars)The customer's mobile telephone number.
}

Responses

200OK
response body:
{
}
Example request
Endpoint
GET /client/{clientCode}/customer
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "AddressDetail": {
    "Line1": "1 Tebbit Mews",
    "Line2": "Winchcombe Street",
    "Line3": "Cheltenham",
    "PostCode": "A1 1AA"
  },
  "BankDetail": {
    "AccountHolderName": "Access Paysuite",
    "AccountNumber": "01065285",
    "BankSortCode": "309906"
  },
  "CompanyName": "Access Paysuite",
  "CustomerRef": "AE102890",
  "DateAdded\"": "2017-04-12T13:22:48.800Z",
  "DateOfBirth": "2017-01-01T00:00:00.000Z",
  "Email": "[email protected]",
  "FirstName": "Matthew",
  "HomePhoneNumber": "01234567890",
  "Id": "c36ce83c-0064-4c1e-a157-cd4c70decf47",
  "IsArchived": true,
  "Memos": [],
  "Surname": "Harris",
  "Title": "Mr"
}
POST/client/{clientCode}/customerCreates a customer in the database#
description:

Creates a customer record — the personal and banking details of the person or organisation you will collect from. A customer must exist before a contract can be created against it.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
query parameters:
{
  • email
    string (≤ 255 chars)The customer’s contact email address. By default this field is required, but this can be disabled at your request. The CustomerEmailMandatory field in the Client Info response shows whether this field is mandatory.
  • title
    string (≤ 10 chars)MandatoryThe customer’s title (Mr/Mrs/Ms/Miss/Mx etc).
  • dateOfBirth
    string (date-time)The customer’s date of birth. Format: YYYY-MM-DDT00:00:00.000
  • customerRef
    string (≤ 255 chars)MandatoryA unique reference number allocated by the client for this customer.
  • firstName
    string (≤ 255 chars)The customer's first name.
  • surname
    string (≤ 255 chars)MandatoryThe customer's surname.
  • companyName
    string (≤ 255 chars)The company name of the customer (if applicable).
  • postCode
    string (≤ 8 chars)MandatoryThe customer's Post Code.
  • accountNumber
    string (8 chars, digits 0-9 only)MandatoryThe customer's bank account number. This must be eight numerical characters with all leading zeros left intact. Examples include: 01065284, 00000000, 26280464. Any non-numerical characters must be removed before passing the data to the API.
  • bankSortCode
    string (6 chars, digits 0-9 only)MandatoryThe customer's bank sort code. This must be six numerical characters with all leading zeros left intact. Examples include: 089286 100000 600000, 230580. In the United Kingdom it is sometimes customary to insert dashes/hyphens between groups of two characters (e.g. 08-92-86, 23-05-80). Any hyphens, dashes or non-numerical characters must be removed before being passed to the API.
  • accountHolderName
    string (≤ 18 chars)MandatoryThe name of the customer's bank account. This must be a maximum of eighteen alphanumeric characters [0-9a-zA-Z ]. A space is also allowed. Any special characters or punctuation such as ampersands, apostrophes, hyphens, slashes, backslashes, commas, full stops etc. must be removed before passing to the API.
  • homePhoneNumber
    string (≤ 20 chars)The customer's home telephone number.
  • workPhoneNumber
    string (≤ 18 chars)The customer's work telephone number.
  • mobilePhoneNumber
    string (≤ 18 chars)The customer's mobile telephone number.
  • line1
    string (≤ 50 chars)MandatoryLine one of the customer's postal address.
  • line2
    string (≤ 30 chars)MandatoryLine two of the customer's postal address.
  • line3
    string (≤ 30 chars)Line three of the customer's postal address.
  • line4
    string (≤ 30 chars)Line four of the customer's postal address.
  • initials
    string (≤ 5 chars)If the customer has provided any middle initials, they can be added in this field.
  • customerLocale
    string (≤ 5 chars)Possible values: en-GB, cy-GBSet the language of communications sent to this customer to English (en-GB) or Welsh (cy-GB). If omitted, this defaults to English. If Welsh support is not enabled for your organisation, submitting cy-GB returns a 400 error with the message: "Welsh language not enabled for this client".
}
request body:
{
  • Email
    string
  • Title
    string
  • CustomerRef
    string
  • FirstName
    string
  • Surname
    string
  • Line1
    string
  • Line2
    string
  • PostCode
    string
  • AccountNumber
    string
  • BankSortCode
    string
  • AccountHolderName
    string
}

Responses

200OK
response body:
{
  • Id
    stringThe GUID of the customer record. You must save this to your database as it will be needed should you wish to update the customer record or create a Direct Debit (Contract).
  • customerRef
    stringThe customer reference that you passed via the API into the system.
}
400Bad Request
response body:
{
  • Message
    stringIf there are any problems with the record, these will be shown in the message field.
}
Example — query parameters
Endpoint
POST /client/{clientCode}/customer
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/[email protected]&title=Mr&customerRef=999999&firstName=John&surname=Doe&line1=1 Tebbit Mews&postCode=GL52 2NF&accountNumber=12345678&bankSortCode=123456&accountHolderName=Mr John Doe' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "CustomerRef": "AE102888",
  "Id": "12f5734a-bfc3-45f2-9edd-44d4a05cf751"
}
HTTP/1.1 400 Bad Request

{
  "ErrorCode": 2,
  "Message": "Customer email is mandatory for this client"
}
Example — request body
Endpoint
POST /client/{clientCode}/customer
Request body
{
  "Email": "[email protected]",
  "Title": "Mr",
  "CustomerRef": "999999",
  "FirstName": "John",
  "Surname": "Doe",
  "Line1": "1 Tebbit Mews",
  "Line2": "Winchcombe Street",
  "PostCode": "GL52 2NF",
  "AccountNumber": "12345678",
  "BankSortCode": "123456",
  "AccountHolderName": "Mr John Doe"
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Email":"[email protected]","Title":"Mr","CustomerRef":"999999","FirstName":"John","Surname":"Doe","Line1":"1 Tebbit Mews","Line2":"Winchcombe Street","PostCode":"GL52 2NF","AccountNumber":"12345678","BankSortCode":"123456","AccountHolderName":"Mr John Doe"}'
Response
HTTP/1.1 200 OK

{
  "CustomerRef": "AE102888",
  "Id": "12f5734a-bfc3-45f2-9edd-44d4a05cf751"
}
HTTP/1.1 400 Bad Request

{
  "ErrorCode": 2,
  "Message": "Customer email is mandatory for this client"
}
GET/client/{clientCode}/customer/{customerId}Queries the database for a single customer by ID#
description:

NOTE: The response from a GET method includes an IsArchived flag. On a newly created customer, this will show as true which is normal. The record will automatically change to false when an associated live Direct Debit (contract) is attached to it.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-customer
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • customerId
    string (guid)MandatoryThe GUID of the customer.
}

Responses

200OK
response body:
{
  • CompanyName
    stringThe customer's registered company.
  • CustomerRef
    stringThe unique customer reference.
  • DateAdded
    string (date-time)Datetime for when this customer was created in the database.
  • DateOfBirth
    string (date-time)The customer's date of birth.
  • Email
    string (email)The customer's email address.
  • FirstName
    stringFirst name of the customer.
  • HomePhoneNumber
    stringThe customer's home phone number.
  • Id
    string (guid)The GUID for this customer object.
  • IsArchived
    booleanReturns true if all of the customer's contracts are archived, otherwise false.
  • MobilePhoneNumber
    stringThe customer's mobile phone number.
  • Surname
    stringLast name of the customer.
  • Title
    stringPossible values: Mrs, Mr, Miss, Ms, Dr, Sir, Lord, Lady, Prof., Rev., Master, MxThe customer's preferred title.
  • WorkPhoneNumber
    stringThe customer's work phone number.
}
404Not FoundCustomer not found
Example request
Endpoint
GET /client/{clientCode}/customer/{customerId}
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/c36ce83c-0064-4c1e-a157-cd4c70decf47' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "AddressDetail": {
    "Line1": "1 Tebbit Mews",
    "Line2": "Winchcombe Street",
    "Line3": "Cheltenham",
    "PostCode": "A1 1AA"
  },
  "BankDetail": {
    "AccountHolderName": "Access Paysuite",
    "AccountNumber": "01065285",
    "BankSortCode": "309906"
  },
  "CompanyName": "Access Paysuite",
  "CustomerRef": "AE102890",
  "DateAdded\"": "2017-04-12T13:22:48.800Z",
  "DateOfBirth": "2017-01-01T00:00:00.000Z",
  "Email": "[email protected]",
  "FirstName": "Matthew",
  "HomePhoneNumber": "01234567890",
  "Id": "c36ce83c-0064-4c1e-a157-cd4c70decf47",
  "IsArchived": true,
  "Memos": [],
  "Surname": "Harris",
  "Title": "Mr"
}
HTTP/1.1 404 Not Found

{
  "Message": "API not enabled"
}
PATCH/client/{clientCode}/customer/{customerId}Updates (or partially updates) an existing customer in the database#
description:

Updates, or partially updates, an existing customer record. Send only the fields you want to change.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-customer
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • customerId
    string (guid)MandatoryThe GUID of the customer.
}
query parameters:
{
  • email
    string (≤ 255 chars)The customer’s contact email address.
  • title
    string (≤ 10 chars)The customer’s title (Mr/Mrs/Ms/Miss/Mx etc).
  • dateOfBirth
    string (date-time)The customer’s date of birth. Format: YYYY-MM-DDT00:00:00.000
  • customerRef
    string (≤ 255 chars)A unique reference number allocated by the client for this customer.
  • firstName
    string (≤ 255 chars)The customer's first name.
  • surname
    string (≤ 255 chars)The customer's surname.
  • companyName
    string (≤ 255 chars)The company name of the customer (if applicable).
  • postCode
    string (≤ 8 chars)The customer's Post Code.
  • accountNumber
    string (8 chars, digits 0-9 only)The customer's bank account number. This must be eight numerical characters with all leading zeros left intact. Examples include: 01065284, 00000000, 26280464. Any non-numerical characters must be removed before passing the data to the API.
  • bankSortCode
    string (6 chars, digits 0-9 only)The customer's bank sort code. This must be six numerical characters with all leading zeros left intact. Examples include: 089286 100000 600000, 230580. In the United Kingdom it is sometimes customary to insert dashes/hyphens between groups of two characters (e.g. 08-92-86, 23-05-80). Any hyphens, dashes or non-numerical characters must be removed before being passed to the API.
  • accountHolderName
    string (≤ 18 chars)The name of the customer's bank account. This must be a maximum of eighteen alphanumeric characters [0-9a-zA-Z ]. A space is also allowed. Any special characters or punctuation such as ampersands, apostrophes, hyphens, slashes, backslashes, commas, full stops etc. must be removed before passing to the API.
  • homePhoneNumber
    string (≤ 20 chars)The customer's home telephone number.
  • workPhoneNumber
    string (≤ 18 chars)The customer's work telephone number.
  • mobilePhoneNumber
    string (≤ 18 chars)The customer's mobile telephone number.
  • line1
    string (≤ 50 chars)Line one of the customer's postal address.
  • line2
    string (≤ 30 chars)Line two of the customer's postal address.
  • line3
    string (≤ 30 chars)Line three of the customer's postal address.
  • line4
    string (≤ 30 chars)Line four of the customer's postal address.
  • initials
    string (≤ 5 chars)If the customer has provided any middle initials, they can be added in this field.
  • customerLocale
    string (≤ 5 chars)Possible values: en-GB, cy-GBSet the language of communications sent to this customer to English (en-GB) or Welsh (cy-GB). If omitted, this defaults to English. If Welsh support is not enabled for your organisation, submitting cy-GB returns a 400 error with the message: "Welsh language not enabled for this client".
}
request body:

{} — This call takes no request body — send an empty JSON object.

Responses

200OK
response body:
{
  • Message
    string
}
Example request
Endpoint
PATCH /client/{clientCode}/customer/{customerId}
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/[email protected]' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Customer updated"
}
PATCH/client/{clientCode}/customer/{customerId}/editUpdates an existing customer using a JSON request body#
description:

Updates, or partially updates, an existing customer record by sending a JSON body. Send only the fields you want to change.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-customer
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • customerId
    string (guid)MandatoryThe GUID of the customer.
}
request body:
{
  • Email
    string (≤ 255 chars)The customer's contact email address.
  • Title
    string (≤ 10 chars)The customer's title (Mr/Mrs/Ms/Miss/Mx etc).
  • DateOfBirth
    string (date-time)The customer's date of birth. Format: YYYY-MM-DDT00:00:00.000
  • CustomerRef
    string (≤ 255 chars)A unique reference number allocated by the client for this customer.
  • FirstName
    string (≤ 255 chars)The customer's first name.
  • Surname
    string (≤ 255 chars)The customer's surname.
  • CompanyName
    string (≤ 255 chars)The company name of the customer (if applicable).
  • PostCode
    string (≤ 8 chars)The customer's Post Code.
  • AccountNumber
    string (8 chars, digits 0-9 only)The customer's bank account number. This must be eight numerical characters with all leading zeros left intact. Examples include: 01065284, 00000000, 26280464. Any non-numerical characters must be removed before passing the data to the API.
  • BankSortCode
    string (6 chars, digits 0-9 only)The customer's bank sort code. This must be six numerical characters with all leading zeros left intact. Examples include: 089286 100000 600000, 230580. In the United Kingdom it is sometimes customary to insert dashes/hyphens between groups of two characters (e.g. 08-92-86, 23-05-80). Any hyphens, dashes or non-numerical characters must be removed before being passed to the API.
  • AccountHolderName
    string (≤ 18 chars)The name of the customer's bank account. This must be a maximum of eighteen alphanumeric characters [0-9a-zA-Z ]. A space is also allowed. Any special characters or punctuation such as ampersands, apostrophes, hyphens, slashes, backslashes, commas, full stops etc. must be removed before passing to the API.
  • HomePhoneNumber
    string (≤ 20 chars)The customer's home telephone number.
  • WorkPhoneNumber
    string (≤ 18 chars)The customer's work telephone number.
  • MobilePhoneNumber
    string (≤ 18 chars)The customer's mobile telephone number.
  • Line1
    string (≤ 50 chars)Line one of the customer's postal address.
  • Line2
    string (≤ 30 chars)Line two of the customer's postal address.
  • Line3
    string (≤ 30 chars)Line three of the customer's postal address.
  • Line4
    string (≤ 30 chars)Line four of the customer's postal address.
  • Initials
    string (≤ 5 chars)If the customer has provided any middle initials, they can be added in this field.
  • CustomerLocale
    string (≤ 5 chars)Possible values: en-GB, cy-GBSet the language of communications sent to this customer to English (en-GB) or Welsh (cy-GB). If omitted, this defaults to English. If Welsh support is not enabled for your organisation, submitting cy-GB returns a 400 error with the message: "Welsh language not enabled for this client".
}

Responses

200OK
response body:
{
  • Message
    string
}
Example request
Endpoint
PATCH /client/{clientCode}/customer/{customerId}/edit
Request body
{
  "Email": "[email protected]",
  "FirstName": "John",
  "Surname": "Doe"
}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/dfca6da1-2490-4607-a256-c5799d2584e9/edit' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Email":"[email protected]","FirstName":"John","Surname":"Doe"}'
Response
HTTP/1.1 200 OK

{
  "Message": "Customer updated"
}

Error handling

Errors are presented back in the JSON or XML response in human readable form. Two are common enough to design for.

ErrorExplanationResolution
There is an existing Customer with the same Client and Customer ref in the database already.The customer reference must be unique; a customer with the customerRef you passed already exists.Check the customer does not already exist; if not, use another unique customerRef.
Invalid Postcode. The postcode must have 5, 6 or 7 characters only.The postcode supplied is not in a correct UK format.UK postcodes are formed as A99 9AA, AA99 9AA or AA9A 9AA, where A is a capital letter [A-Z] and 9 is a number [0-9].