Direct Debit runs on DDCMS — a separate API with its own base URL and credentials, distinct from the Advanced Payments API used by cards.
All 54 Direct Debit endpoints, grouped by area.
Return Endpoints
Set, retrieve and clear the webhook URLs that DDCMS posts return data to — one URL per entity type (customer, contract, payment, bulk payment, schedule).
DELETE/client/{clientCode}/BACS/{entity}/callbackClears the set callback URL for the given return endpoint#
description:
Clears the set callback URL for the specified entity.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
request body:
{
PageNumber
float (default 1)Page number for the pagination.
PageSize
float (default 100)Number of payment records to return per page.
ContractId
string (guid)Unique ID for a particular contract you want to list payments for.
CustomerId
string (guid)Unique ID for a particular customer you want to list payments for. Note: this will be ignored if ContractId is also provided.
IsCredit
booleanSet to true to only return credit payments. Set to false to only return debit payments.
IsScheduled
booleanSet to true to only return payments generated by DDCMS on a regular/fixed schedule. Set to false to only return ad-hoc payments.
Status
stringPossible values: Indemnity Claimed, Paid, Pending, Represented, Unpaid, withdrawnSet to only return payments with a particular status.
Type
stringPossible values: Credit, Final, First Time, Regular, RetrySet to only return payments of a particular type.
CollectionDateFrom
string (date-time)Earliest Due date to return payments for.
CollectionDateTo
string (date-time)Latest Due date to return payments for.
CreatedAfter
string (date-time)Earliest DateAdded date to return payments for.
CreatedBefore
string (date-time)Latest DateAdded date to return payments for.
}
Responses
200OK
response body:
{
Pagination {
Page
floatPage number for the pagination.
PageSize
floatNumber of payment records to return per page.
TotalPages
floatTotal number of pages returned by the search.
TotalRecords
floatTotal number of payment records returned by the search.
}
Data [ {
Amount
floatThe amount of the payment.
Comment
stringThe comment passed when the payment was added; a ReasonMessage may be appended to the end of this.
Date
string (date-time)The due date of the payment.
Id
string (guid)The GUID of the payment. We suggest that you save this so that you can easily change or query the payment in future. If you are using pushed return data, this will be included in any payload delivered concerning the payment.
IsAdhoc
booleanIf this is an adhoc payment, this will show as true, else if it is a scheduled payment, it will shows as false.
IsCredit
booleanIf the payment is a credit to the customer, this will show as true, else it will show as false.
ReasonCode
integer (min 0, max 8)The BACS reason code of the payment if the payment has been returned unpaid. The possible reasons are: - 0: Refer to payer. - 1: Instruction cancelled. - 2: Payer deceased. - 3: Account transferred. - 4: Advance notice disputed. - 5: No account/Wrong account type. - 6: No instruction. - 7: Amount differs. - 8: Amount not yet due. For further details on the meanings of these codes, and the associated action required, please see our separate booklet.
ReasonMessage
stringPlain text explanation of the ReasonCode.
Status
stringPossible values: Paid, Pending, Represented, Unpaid, Withdrawn, Indemnity ClaimedThe status of the payment. This can be: - Paid - We have received the payment from the customer (\\see below) - Pending – The payment has been queued to be sent to the bank for collection. - Represented – The payment has been returned by the bank unpaid, and the system has created a new transaction to try and collect the amount again. - Unpaid – The payment has been returned by the bank unpaid and will not be sent again to the bank for collection. - Withdrawn – The payment was at the point of being sent to the bank for collection, but was withdrawn by Access Paysuite at the last minute. The payment has not been collected. - Indemnity Claimed – The customer has approached their bank for a refund which is being/has been processed. \\ BACS works by exception; that is to say that payments are assumed to be paid unless we hear from the bank otherwise. As such, payments remain in the Pending state up until the point they are submitted to the bank for collection (3 – 4 working days before the collection date). Upon submission, the payment status changes to Paid although the actual status of the payment is not known until 1-2 working days after the due date. Because of this, we recommend that you do not update your system with the payment status until 2-3 working days after the Due Date. It is also important to note that BACS only works on banking days (Monday to Friday excluding bank and public holidays). For that reason, if a payment Due Date is on a weekend or a public holiday, the collection will take place on the next banking day. For example, a payment due on Saturday, 15th April 2017 will actually collect on Tuesday 18th April 2017 (the Monday being Easter Monday which is a bank holiday in the UK). Again, this needs to be factored in to when you check the status of payments; in the above example, it would be prudent to wait until late in the afternoon of 20th April 2017 or better 21st April 2017 to ensure that all unpaid messages have been received from the bank and processed.
Type
stringThe type of payment (BACS being a bank processed payment, Manual being something manually added via the UI.
403ForbiddenForbidden - This contract cannot be used in API. When contract is protected.
500Internal Server ErrorInternal Server Error - An unexpected error occurred while processing the request.
Customer Manipulation
Create and update customer records. A customer must exist before a Direct Debit contract can be created against them.
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.
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:
{
Customers [ {
Array of Customers matching the search criteria.
AddressDetail {
Address of the customer.
Line1
stringLine 1 of the customer's address.
Line2
stringLine 2 of the customer's address.
Line3
stringLine 3 of the customer's address.
Line4
stringLine 4 of the customer's address.
PostCode
stringThe customer's registered postcode.
}
BankDetail {
Details of the customer's bank account.
AccountHolderName
stringName on the account.
AccountNumber
stringThe eight-digit account number.
BankSortCode
stringThe six-digit bank sort code.
}
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.
Memos [ {
Memos for this customer. When calling GET /customer with includeMemos=false, this will be null.
At
string (date-time)Datetime for when the memo was added.
Body
stringHTML body of the memo.
ContractRef
stringDirect Debit reference for the contract the memo was assigned to.
Object providing useful metadata for clients calling an endpoint with pagination.
TotalPages
floatTotal count of pages.
TotalRecords
floatCount of records with current filter.
PageSize
floatNumber of records returned per page.
PageNumber
floatCurrent page.
}
}
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.
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.
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.
}
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.
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
}
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.
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
}
Customer Questions
Add custom data fields to your customer records and manage the answers supplied for each field.
DELETE/client/{clientCode}/customer/{customerId}/question/{questionId}/answerDeletes an existing customer answer#
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
Responses
200OK
response body:
{
Questions [ {
Array of Questions.
Id
string (guid)Unique ID for this question. We recommend you keep a record of this as it's required for adding answers.
Label
stringLabel for the question.
Type
stringPossible values: text, list, dateData type for answers to this question.
Options
arrayComma-separated list of possible answers for this question. Can only be used when type is list.
Tags
stringA custom tag that was assigned to this question. If the question was created from an eDD page, this will be populated with the end of the URL to the page. For example, if the question was added on https://secure.edirectdebit.co.uk/Example/DD-Signups, the Tags would be DD-Signups.
IsMandatory
booleanWhether or not an answer is required for this question.
} ]
}
Payment Dates
Look up the earliest permitted collection dates for new and existing customers, taking your SUN's configured delay periods into account.
GET/client/{clientCode}/paymentdateGets the earliest first and subsequent payment dates currently allowed#
description:
Gets the earliest first and subsequent payment dates currently allowed
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
Responses
200OK
response body:
{
NextFirstPaymentDate
string (date-time)The earliest contract start/first collection date currently allowed by your SUN.
NextSubsequentPaymentDate
string (date-time)The earliest adhoc payment date for active contracts after first collection currently allowed by your SUN.
}
Contract Querying and Creation
Retrieve and create Direct Debit contracts (schedules) for a customer. A contract links a customer to a payment schedule and triggers the DDI submission to BACS.
GET/client/{clientCode}/customer/{customerId}/contractQueries the database for a contract or set of contracts#
description:
Queries the database for a contract or set of contracts
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
customerId
string (guid)MandatoryThe GUID of the customer (if the customer already exists).
}
Responses
200OK
response body:
{
Contracts [ {
Array of contracts for the given customer.
Amount
floatIf the contract is for regular payments, then the regular payment amount is returned in this parameter.
AtTheEnd
stringPossible values: Expire, Switch to Further NoticeThis parameter decides what will happen when the contract ends.
Description
stringA description of the contract. This can include number of payments, payment amount, end date etc.
DirectDebitReference
stringThe bank reference for the contract.
Every
integerIf the contract is set to take regular payments, this parameter shows the frequency of payments generated (e.g. every 2 months, every 4 weeks etc).
ExtraInitialAmounts
floatIf there are extra charges to be collected with the first payment (e.g. a gym joining fee/registration fee) then these are shown separately with this parameter.
Id
string (guid)The DDCMS database GUID for this contract.
InitialAmount
floatIf this is a contract for regular payments and the first payment is different to the regular payments, then the first payment amount is passed with this parameter.
IsGiftAid
booleanWhether or not payments for the contract are subject to a gift aid claim.
NumberOfDebits
integerIf this is a “Take Certain Number of Debits” contract then the number of debits to be taken are returned in this parameter.
PaymentDayInMonth
stringPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, Last Day of the MonthIf the contract is for regular payments, then the day on which the first payment is taken is returned with this parameter.
PaymentMonthInYear
integer (min 1, max 12)If the contract is for regular payments then the month in which the first payment is taken is returned with this parameter.
ScheduleName
stringThe name of the schedule the contract was setup against.
Start
string (date-time)The start date of the contact.
Status
stringPossible values: Inactive, Expired, Cancelled, Pause, Suspended, Cancellation Pending, Active, Creation PendingThe current status of the contract.
StatusExplanation
stringProvides an explanation for the most recent status update for the contract.
TerminationType
stringPossible values: Take certain number of debits, Until further notice, End of exact dateHow this contract will end.
} ]
CustomerId
string (guid)Database GUID for the given customer.
}
POST/client/{clientCode}/customer/{customerId}/contractCreates a contract in the database#
description:
For ad-hoc contracts, you will only need to pass scheduleName, start, terminationType, atTheEnd and isGiftAid.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
customerId
string (guid)MandatoryThe GUID of the customer (if the customer already exists).
}
query parameters:
{
scheduleName
string (≤ 255 chars)MandatoryThe name of the schedule to be used when creating a contract. You must include either this or the scheduleId parameter.
scheduleId
string (guid)MandatoryThe database GUID to be used when creating a contract. You must include either this or the scheduleName parameter.
start
string (date-time)MandatoryThe start date of the contract. This must be at least 10 working days in the future, on a permitted date and not after the anticipated first payment date. If this is a regular schedule, use the same date as the first payment date. Only up to 364 days in advance. Format: YYYY-MM-DDT00:00:00.000
numberOfDebits
integer (min 0, max 999)If this is a “Take certain Number of Debits” contract then the number of debits to be taken should be passed using this parameter. This field is only mandatory if the termination type is “Take Certain Number of Debits”.
every
integerIf the contract is set to take regular payments, this parameter allows you to skip periods (e.g. every 2 months, every 4 weeks etc). This field is only mandatory if the contract is not an ad-hoc contract.
isGiftAid
booleanMandatoryPass true if the payments to be collected are to be subject to a gift aid claim, false if not (pass false if the client is not a charity).
initialAmount
float (decimal places ≤ 2)If this is a contract for regular payments and the first payment is different to the regular payments, then pass the first payment amount with this parameter. Do not pass this parameter with ad-hoc contracts, or where the first amount is the same as the regular amount.
extraInitialAmounts
float (decimal places ≤ 2)If there are extra charges to be collected with the first payment (e.g. a gym joining fee/registration fee) then these can be added separately with this parameter. Do not pass the parameter if there are no extra amounts, and this must not be used if the contract is an ad-hoc payment contract.
amount
float (decimal places ≤ 2)If the contract is for regular payments, then the regular payment amount should be passed using this parameter. Do not pass this parameter if the contract is an ad-hoc contract. This field is only mandatory if the contract is not an ad-hoc contract.
finalAmount
float (decimal places ≤ 2)If this is a contract for regular payments and the final payment is different to the regular payments, then pass the final payment amount with this parameter. Do not pass this parameter with ad-hoc contracts, or where the final amount is the same as the regular amount.
paymentMonthInYear
integer (min 1, max 12)If the contract is for regular payments then the month in which you wish the first payment should be passed with this parameter. This field is only mandatory if the contract is not an ad-hoc contract. This field is only mandatory if the contract is annual or monthly.
paymentDayInMonth
integerPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 98, 99If the contract is for regular payments, then the day on which you wish the first payment should be passed with this parameter. This field is only mandatory if the contract is not an ad-hoc contract. This field is only mandatory if the contract is annual or monthly. NOTE: You may only select: - days 1 to 28 - 98, which represents Last working day of the Month - 99, which represents Last day of the Month equal with value 99. You may not select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.
paymentDayInWeek
integer (min 1, max 5)1 -> Monday 2 -> Tuesday 3 -> Wednesday 4 -> Thursday 5 -> Friday If the contract is for regular payments and has a weekly frequency, pass the day of the week that you wish payments to be collected via this parameter. This field is only mandatory if the contract is not an ad-hoc contract. This field is only mandatory if the contract is weekly.
terminationType
stringMandatoryPossible values: Take certain number of debits, Until further notice, End on exact datePass the way in which the contract should end using this parameter. If the contract is ad-hoc, you must pass Until further notice.
atTheEnd
stringMandatoryPossible values: Expire, Switch to Further NoticeThis parameter decides what will happen when the contract ends. If you have selected a terminationType of Until Further Notice or the contract is an ad-hoc contract, you must pass Switch to Further Notice.
terminationDate
string (date-time)If the terminationType is End on Exact Date then the termination date should be passed using this. Format: YYYY-MM-DDT00:00:00.000
additionalReference
string (≤ 200 chars)If you wish to add an additional reference to the contract for you own use, this can be passed to using the additionalReference parameter.
customDirectDebitRef
string (≤ 18 chars)THIS PARAMETER SHOULD ONLY BE USED IF YOU HAVE BEEN INSTRUCTED TO DO SO If you have made arrangements with us to use a custom direct debit referencing scheme, pass the custom direct debit using this parameter. The field may only contain alphanumeric data (a-z, A-Z, 0-9) and certain special characters (whitespace, ampersand &, hyphen -, solidus / or full stop .).
}
request body:
{
ScheduleName
string
Start
string (date-time)
IsGiftAid
boolean
TerminationType
string
AtTheEnd
string
}
Responses
200OK
response body:
{
Id
stringThe GUID of the contract record. You must save this to your database as it will be needed should you wish to update the contract or create ad-hoc payments using the payments or bulk payments call.
Message
objectThis will be null.
directDebitRef
stringThis is the Direct Debit Reference that will be quoted to the customer’s bank when collecting funds. Some banks will show this reference on the customer’s statement, although this is not guaranteed.
}
400Bad RequestBad request - invalid schedule name
Contract Amendment
Amend the payment amount or collection date on a scheduled contract. Choose the endpoint that matches your contract's frequency (amount, monthly, weekly, or annual).
PATCH/client/{clientCode}/contract/{contractId}/amountChanging the Amount#
description:
Amends an existing contract amount in the database.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to amend.
}
query parameters:
{
monthDay
stringMandatoryPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, Last Day of the MonthThe new day of the month on which payments are to be taken. NOTE: You may not select days 29, 30 or 31 of the month; if you wish to select the last day of the month; pass the string Last day of the Month. Payments will be collected on the next available instance of the payment day, which will be a minimum of 5 working days in the future. Any payment already scheduled in the next 5 working days *will still be collected*.
month
integer (min 1, max 12)MandatoryThe new month in the year on which the payments are to be taken.
comment
string (≤ 255 chars)MandatoryA comment to explain the reason for the change of day.
nextPaymentPatchAmount
float (decimal places ≤ 2)If you wish to take the next payment to be a different amount (e.g. pro rata because the number of days between payments will deb different) then pass the amount using this parameter. Ensure that patchNextPayment is set to true if you are using this.
patchNextPayment
booleanMandatorySet to true if using nextPaymentPatchAmount or false if not.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the contract has been updated.
}
400Bad RequestBad request - invalid day
PATCH/client/{clientCode}/contract/{contractId}/monthlyChanging the Date (Monthly Schedules)#
description:
Amends an existing contract payment date in the database.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to amend.
}
query parameters:
{
monthDay
stringMandatoryPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, Last Day of the MonthThe new day of the month on which payments are to be taken. NOTE: You may not select days 29, 30 or 31 of the month; if you wish to select the last day of the month; pass the string Last day of the Month. Payments will be collected on the next available instance of the payment day, which will be a minimum of 5 working days in the future. Any payment already scheduled in the next 5 working days *will still be collected*.
comment
string (≤ 255 chars)MandatoryA comment to explain the reason for the change of day.
nextPaymentPatchAmount
float (decimal places ≤ 2)If you wish to take the next payment to be a different amount (e.g. pro rata because the number of days between payments will deb different) then pass the amount using this parameter. Ensure that patchNextPayment is set to true if you are using this.
patchNextPayment
booleanMandatorySet to true if using nextPaymentPatchAmount or false if not.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the contract has been updated.
}
400Bad RequestBad request - invalid day
PATCH/client/{clientCode}/contract/{contractId}/referenceChanging the Direct Debit Reference (for authorised users only)#
description:
In general, our software will allocate a unique direct debit reference for every contract created within the system. For own SUN and FM SUN clients that have made prior arrangements with us, it is possible to change a reference number after the contract has been set up. Please note that using this facility will incur extra charges as new instructions will need to be sent to the bank via BACS.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to amend.
}
query parameters:
{
newDDRef
string (≤ 18 chars)MandatoryIf you have made arrangements with us to use a custom direct debit referencing scheme, pass the new custom direct debit using this parameter. The field may only contain alphanumeric data (a-z, A-Z, 0-9) and certain special characters (hyphen - or solidus /).
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the contract has been updated.
}
403ForbiddenForbidden - account not authorised
404Not FoundContract not found
PATCH/client/{clientCode}/contract/{contractId}/weeklyChanging the Day (Weekly Schedules)#
description:
Amends an existing contract payment date in the database.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to amend.
}
query parameters:
{
day
float (min 1, max 5)MandatoryThe new day on which payments are to be taken. Must be passed as an integer: <ul> <li>1 = Monday</li> <li>2 = Tuesday</li> <li>3 = Wednesday</li> <li>4 = Thursday</li> <li>5 = Friday</li> </ul> Payments will be collected on the next available instance of the payment day, which will be a minimum of 5 working days in the future. Any payment already scheduled in the next 5 working days will still be collected.
comment
string (≤ 255 chars)MandatoryA comment to explain the reason for the change of day.
nextPaymentPatchAmount
float (decimal places ≤ 2)If you wish to take the next payment to be a different amount (e.g. pro rata because the number of days between payments will deb different) then pass the amount using this parameter. Ensure that patchNextPayment is set to true if you are using this.
patchNextPayment
booleanMandatorySet to true if using nextPaymentPatchAmount or false if not.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the contract has been updated.
}
400Bad RequestBad request - invalid day
Frequency Switching
Manage future scheduled contract versions — retrieve, create, edit or delete upcoming schedules without touching the current active schedule.
POST/client/{clientCode}/contract/{contractId}/cancelScheduleCancels the schedule of a contract#
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to amend.
futureScheduleId
string (guid)MandatoryThe StreamVersion (schedule) GUID that you wish to amend.
}
query parameters:
{
startDate
string (date-time)MandatoryEffective date of change.
scheduleId
string (guid)Schedule ID from available schedules.
scheduleName
stringSchedule name from available schedules.
every
integerIf the schedule is set to take regular payments, this parameter allows you to skip periods (e.g. every 2 months, every 4 weeks etc). This field is only mandatory if the schedule is not an ad-hoc schedule.
paymentDayInMonth
integerIf the schedule is for regular payments, then the day on which you wish the first payment should be passed with this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is annual or monthly. NOTE: You may only select: - days 1 to 28 - 98, which represents Last working day of the Month - 99, which represents Last day of the Month equal with value 99. You may not select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.
paymentDayInWeek
integer1 -> Monday 2 -> Tuesday 3 -> Wednesday 4 -> Thursday 5 -> Friday If the schedule is for regular payments and has a weekly frequency, pass the day of the week that you wish payments to be collected via this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is weekly.
paymentMonthInYear
integerIf the schedule is for regular payments then the month in which you wish the first payment should be passed with this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is annual or monthly.
initialDate
string (date-time)Different first payment date.
initialAmount
float (decimal)If this is a schedule for regular payments and the first payment is different to the regular payments, then pass the first payment amount with this parameter. Do not pass this parameter with ad-hoc schedule, or where the first amount is the same as the regular amount.
extraInitialAmounts
stringIf there are extra charges to be collected with the first payment (e.g. a gym joining fee/registration fee) then these can be added separately with this parameter. Do not pass the parameter if there are no extra amounts, and this must not be used if the schedule is an ad-hoc payment schedule.
amount
float (decimal)If the schedule is for regular payments, then the regular payment amount should be passed using this parameter. Do not pass this parameter if the schedule is an ad-hoc schedule. This field is only mandatory if the schedule is not an ad-hoc schedule.
finalAmount
float (decimal)If this is a schedule for regular payments and the final payment is different to the regular payments, then pass the final payment amount with this parameter. Do not pass this parameter with ad-hoc schedules, or where the final amount is the same as the regular amount.
terminationType
stringPossible values: Take certain number of debits, Until further notice, End on exact datePass the way in which the schedule should end using this parameter. If the schedule is ad-hoc, you must pass Until further notice.
terminationDate
string (date-time)If the terminationType is End on Exact Date then the termination date should be passed using this. Format: YYYY-MM-DDT00:00:00.000
numberOfPayments
integerIf this is a “Take certain Number of Debits” schedule then the number of debits to be taken should be passed using this parameter. This field is only mandatory if the termination type is “Take Certain Number of Debits”.
isGiftAid
booleanPass true if the payments to be collected are to be subject to a gift aid claim, false if not (pass false if the client is not a charity).
}
request body:
shared schema directDebit/future-schedule
{
StartDate
string (date-time)
ScheduleId
string
ScheduleName
string
Every
float
PaymentDayInMonth
float
PaymentDayInWeek
float
PaymentMonthInWeek
float
InitialDate
string (date-time)
InitialAmount
float
ExtraInitialAmounts
string
Amount
float
FinalAmount
float
TerminationType
string
TerminationDate
string (date-time)
NumberOfPayments
float
IsGiftAid
boolean
}
Responses
200OK
response body:
{
Message
stringMessage.
}
400Bad Request
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
500Internal Server Error
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
GET/client/{clientCode}/contract/{contractId}/futureSchedulesRetrieves all future schedules (stream versions) for a given contract and stream#
description:
Retrieves all future schedules (stream versions) for a given contract and stream
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to add a new future schedule to.
}
query parameters:
{
startDate
string (date-time)MandatoryEffective date of change.
scheduleId
string (guid)Schedule ID from available schedules.
scheduleName
stringSchedule name from available schedules.
every
integerIf the schedule is set to take regular payments, this parameter allows you to skip periods (e.g. every 2 months, every 4 weeks etc). This field is only mandatory if the schedule is not an ad-hoc schedule.
paymentDayInMonth
integerPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 98, 99If the schedule is for regular payments, then the day on which you wish the first payment should be passed with this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is annual or monthly. NOTE: You may only select: - days 1 to 28 - 98, which represents Last working day of the Month - 99, which represents Last day of the Month equal with value 99. You may not select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.
paymentDayInWeek
integer1 -> Monday 2 -> Tuesday 3 -> Wednesday 4 -> Thursday 5 -> Friday If the schedule is for regular payments and has a weekly frequency, pass the day of the week that you wish payments to be collected via this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is weekly.
paymentMonthInYear
integerIf the schedule is for regular payments then the month in which you wish the first payment should be passed with this parameter. This field is only mandatory if the schedule is not an ad-hoc schedule. This field is only mandatory if the schedule is annual or monthly.
initialDate
string (date-time)Different first payment date.
initialAmount
float (decimal)If this is a schedule for regular payments and the first payment is different to the regular payments, then pass the first payment amount with this parameter. Do not pass this parameter with ad-hoc schedules, or where the first amount is the same as the regular amount.
extraInitialAmounts
stringIf there are extra charges to be collected with the first payment (e.g. a gym joining fee/registration fee) then these can be added separately with this parameter. Do not pass the parameter if there are no extra amounts, and this must not be used if the schedule is an ad-hoc payment schedule.
amount
float (decimal)If the schedule is for regular payments, then the regular payment amount should be passed using this parameter. Do not pass this parameter if the schedule is an ad-hoc schedule. This field is only mandatory if the schedule is not an ad-hoc schedule.
finalAmount
float (decimal)If this is a schedule for regular payments and the final payment is different to the regular payments, then pass the final payment amount with this parameter. Do not pass this parameter with ad-hoc schedules, or where the final amount is the same as the regular amount.
terminationType
stringPossible values: Take certain number of debits, Until further notice, End on exact datePass the way in which the schedule should end using this parameter. If the schedule is ad-hoc, you must pass Until further notice.
terminationDate
string (date-time)If the terminationType is End on Exact Date then the termination date should be passed using this. Format: YYYY-MM-DDT00:00:00.000
numberOfPayments
integer (min 0, max 999)If this is a “Take certain Number of Debits” schedule then the number of debits to be taken should be passed using this parameter. This field is only mandatory if the termination type is “Take Certain Number of Debits”.
isGiftAid
booleanPass true if the payments to be collected are to be subject to a gift aid claim, false if not (pass false if the client is not a charity).
}
request body:
shared schema directDebit/future-schedule
{
StartDate
string (date-time)
ScheduleId
string
ScheduleName
string
Every
float
PaymentDayInMonth
float
PaymentDayInWeek
float
PaymentMonthInWeek
float
InitialDate
string (date-time)
InitialAmount
float
ExtraInitialAmounts
string
Amount
float
FinalAmount
float
TerminationType
string
TerminationDate
string (date-time)
NumberOfPayments
float
IsGiftAid
boolean
}
Responses
200OK
response body:
{
NewScheduleId
string (guid)New schedule ID.
}
400Bad Request
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
500Internal Server Error
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
POST/client/{clientCode}/contract/{contractId}/restartScheduleRestarts the schedule of a contract#
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to query.
}
query parameters:
{
versionId
string (guid)MandatoryThe StreamVersion (schedule) GUID that you wish to query.
}
Responses
200OK
response body:
{
StreamVersion {
Id
string (guid)The stream version identifier.
Status
stringStatus.
IsPatch
booleanIs patch.
StartDate
string (date-time)Start date.
Frequency
stringFrequency.
Every
integerEvery.
PaymentDayInWeek
integerPayment day in week.
PaymentDayInMonth
integerPayment day in month.
PaymentMonthInYear
integerPayment month in year.
InitialDate
string (date-time)Initial date.
InitialAmount
float (decimal)Initial amount.
RegistrationFee
float (decimal)Registration fee.
ExtraInitialAmounts
stringExtra initial amounts.
Amount
float (decimal)Amount.
FinalAmount
float (decimal)Final amount.
IsGiftAid
booleanIs gift aid.
TerminationType
stringTermination type.
TerminationDate
string (date-time)Termination date.
NumberOfDebits
integerNumber of debits.
}
SearchInput
objectSearch input.
TotalExpectedResults
integerTotal expected results.
}
400Bad Request
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
500Internal Server Error
response body:
shared schema directDebit/error
{
Message
stringHuman-readable description of the failure.
ErrorCode
integerNumeric DDCMS error code.
Detail
stringFurther detail about the failure, where available.
}
Cancelling the Direct Debit
Cancel the Direct Debit instruction on a contract. Future scheduled payments are still created in the system but are not sent to BACS, and ad-hoc payments are unaffected.
POST/client/{clientCode}/contract/{contractId}/cancelChanges the status of the Direct Debit to “Cancelled”#
description:
Future payments will be created within our system, but automatically marked as unpaid.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to cancel the direct debit on.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the contract has been cancelled.
}
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
Archiving a Contract
Permanently archive a contract: cancels the DDI, writes off outstanding arrears, cancels future scheduled payments and sets the status to 'Archived'. This action cannot be undone.
POST/client/{clientCode}/contract/{contractId}/archiveCancels the direct debit, writes off any outstanding arrears balance, cancels future payments and sets the contract status to “archived”#
description:
NOTE: It is not possible to “unarchive” a contract once the archive process has been initiated.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to reactivate.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the operation.
}
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
Restart a Contract
Restart an expired fixed-term contract by appending a new schedule to the end of the previous one, reusing the existing DDI at the bank.
POST/client/{clientCode}/contract/{contractId}/restartReactivates the Direct Debit if it is in the Expired state and payments have already come to an end#
description:
Reactivates the Direct Debit if it is in the Expired state and payments have already come to an end
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to restart.
}
query parameters:
{
paymentDayInMonth
integerPossible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 99If the contract is for regular payments, then the day on which you wish the first payment should be passed with this parameter. NOTE: *You may not* select days 29, 30 or 31 of the month; if you wish to select the last day of the month; pass the integer value 99 which represent Last day of the Month. This field is only mandatory if the contract is not an ad-hoc contract. This field is only mandatory if the contract is annual or monthly. You may only select days 1 to 28 or “Last day of the month” which is equal with value 99. Choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.
paymentMonthInYear
integer (min 1, max 12)If the contract is for regular payments then the month in which you wish the first payment should be passed with this parameter. This field is only mandatory if the contract is not an ad-hoc contract. This field is only mandatory if the contract is annual or monthly.
terminationType
stringMandatoryPossible values: Take certain number of debits, Until further notice, End on exact datePass the way in which the contract should end using this parameter. If the contract is ad-hoc, you must pass Until further notice.
numberOfDebits
integer (min 0, max 999)If this is a “Take certain Number of Debits” contract then the number of debits to be taken should be passed using this parameter. This field is only mandatory if the termination type is “Take Certain Number of Debits”.
initialAmount
float (decimal places ≤ 2)If this is a contract for regular payments and the first payment is different to the regular payments, then pass the first payment amount with this parameter. Do not pass this parameter with ad-hoc contracts, or where the first amount is the same as the regular amount.
amount
float (decimal places ≤ 2)If the contract is for regular payments, then the regular payment amount should be passed using this parameter. Do not pass this parameter if the contract is an ad-hoc contract. This field is only mandatory if the contract is not an ad-hoc contract.
finalAmount
float (decimal places ≤ 2)If this is a contract for regular payments and the final payment is different to the regular payments, then pass the final payment amount with this parameter. Do not pass this parameter with ad-hoc contracts, or where the final amount is the same as the regular amount.
atTheEnd
stringMandatoryPossible values: Expire, Switch to Further NoticeThis parameter decides what will happen when the contract ends. If you have selected a terminationType of Until Further Notice or the contract is an ad-hoc contract, you must pass Switch to Further Notice.
additionalReference
string (≤ 200 chars)If you wish to add an additional reference to the contract for you own use, this can be passed to using the additionalReference parameter.
}
request body:
{} — This call takes no request body — send an empty JSON object.
Responses
200OK
response body:
{
Message
stringConfirms the operation.
}
400Bad RequestBad request - invalid restart date
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
Patches
Apply temporary overrides to a scheduled contract: change the collection amount, freeze collection, or skip a payment for a defined date range.
DELETE/client/{clientCode}/contract/{contractId}/patch/{patchId}Deletes a patch#
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to query.
}
query parameters:
{
rows
integer (min 1, max 100)MandatoryThe number of payments (rows) you wish to be returned in the response. Note: Payments are always returned ordered by Date descending, i.e. the most recent payment will be the first item returned.
}
Responses
200OK
response body:
{
Payments [ {
Amount
floatThe amount of the payment.
Comment
stringThe comment passed when the payment was added; a ReasonMessage may be appended to the end of this.
Date
string (date-time)The due date of the payment.
Id
string (guid)The GUID of the payment. We suggest that you save this so that you can easily change or query the payment in future. If you are using pushed return data, this will be included in any payload delivered concerning the payment.
IsAdhoc
booleanIf this is an adhoc payment, this will show as true, else if it is a scheduled payment, it will shows as false.
IsCredit
booleanIf the payment is a credit to the customer, this will show as true, else it will show as false.
ReasonCode
integer (min 0, max 8)The BACS reason code of the payment if the payment has been returned unpaid. The possible reasons are: - 0: Refer to payer. - 1: Instruction cancelled. - 2: Payer deceased. - 3: Account transferred. - 4: Advance notice disputed. - 5: No account/Wrong account type. - 6: No instruction. - 7: Amount differs. - 8: Amount not yet due. For further details on the meanings of these codes, and the associated action required, please see our separate booklet.
ReasonMessage
stringPlain text explanation of the ReasonCode.
Status
stringPossible values: Paid, Pending, Represented, Unpaid, Withdrawn, Indemnity ClaimedThe status of the payment. This can be: - Paid - We have received the payment from the customer (\\see below) - Pending – The payment has been queued to be sent to the bank for collection. - Represented – The payment has been returned by the bank unpaid, and the system has created a new transaction to try and collect the amount again. - Unpaid – The payment has been returned by the bank unpaid and will not be sent again to the bank for collection. - Withdrawn – The payment was at the point of being sent to the bank for collection, but was withdrawn by Access Paysuite at the last minute. The payment has not been collected. - Indemnity Claimed – The customer has approached their bank for a refund which is being/has been processed. \\ BACS works by exception; that is to say that payments are assumed to be paid unless we hear from the bank otherwise. As such, payments remain in the Pending state up until the point they are submitted to the bank for collection (3 – 4 working days before the collection date). Upon submission, the payment status changes to Paid although the actual status of the payment is not known until 1-2 working days after the due date. Because of this, we recommend that you do not update your system with the payment status until 2-3 working days after the Due Date. It is also important to note that BACS only works on banking days (Monday to Friday excluding bank and public holidays). For that reason, if a payment Due Date is on a weekend or a public holiday, the collection will take place on the next banking day. For example, a payment due on Saturday, 15th April 2017 will actually collect on Tuesday 18th April 2017 (the Monday being Easter Monday which is a bank holiday in the UK). Again, this needs to be factored in to when you check the status of payments; in the above example, it would be prudent to wait until late in the afternoon of 20th April 2017 or better 21st April 2017 to ensure that all unpaid messages have been received from the bank and processed.
Type
stringThe type of payment (BACS being a bank processed payment, Manual being something manually added via the UI.
} ]
}
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
POST/client/{clientCode}/contract/{contractId}/paymentAdds a payment to the database to the contract specified in the URL#
description:
Adds a payment to the database to the contract specified in the URL
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract GUID that you wish to query.
}
query parameters:
{
amount
float (decimal places ≤ 2)The amount to be collected.
date
string (date-time)The date on which the payment should be collected. This must be at least 5 working days in the future, on a permitted date and not before the start date set when creating the contract. Format: YYYY-MM-DDT00:00:00.000
comment
string (≤ 255 chars)A comment relating to the payment (which can be recalled using the GET method).
isCredit
booleanIf you have an own SUN and you have agreed by prior arrangement with your account manager that you may issue credits, pass true with this parameter to issue a credit to the customer.
}
request body:
{
Amount
float
Comment
string
Date
string (date-time)
IsCredit
boolean
}
Responses
200OK
response body:
{
Amount
float (decimal places ≤ 2)The amount of the payment.
Contract
string (guid)The GUID of the contract to which the payment has been applied.
DueDate
string (date-time)The due date (date of collection) of the payment.
Error
stringIf any error occurs, a message will appear here.
Id
string (guid)The GUID of the payment. We suggest that you save this so that you can easily change or query the payment in future. If you are using pushed return data, this will be included in any payload delivered concerning the payment.
Message
stringIf any additional message from the system is generated, it will appear here (usually null).
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
request body:
{
Payments [ {
Array of payments to be inserted in bulk.
amount
float (decimal places ≤ 2)MandatoryThe amount to be collected.
comment
string (≤ 255 chars)A comment relating to the payment (which can be recalled using the GET method).
contract
string (guid)MandatoryThe contract GUID that you wish to collect a payment against.
date
string (date-time)MandatoryThe date on which the payment should be collected. This must be at least 5 working days in the future, on a permitted date and not before the start date set when creating the contract. Format: YYYY-MM-DDT00:00:00.000
isCredit
booleanIf you have an own SUN and you have agreed by prior arrangement with your account manager that you may issue credits, pass true with this parameter to issue a credit to the customer. If omitted, this will be a debit.
} ]
}
Responses
200OK
response body:
{
FailureCount
floatNumber of payment requests that failed to push to the queue.
Failures [ {
Array of payment requests that failed to push to the queue.
amount
float (decimal places ≤ 2)ReturnedThe amount to be collected.
comment
string (≤ 255 chars)A comment relating to the payment (which can be recalled using the GET method).
contract
string (guid)ReturnedThe contract GUID that you wish to collect a payment against.
date
string (date-time)ReturnedThe date on which the payment should be collected. This must be at least 5 working days in the future, on a permitted date and not before the start date set when creating the contract. Format: YYYY-MM-DDT00:00:00.000
isCredit
booleanIf you have an own SUN and you have agreed by prior arrangement with your account manager that you may issue credits, pass true with this parameter to issue a credit to the customer. If omitted, this will be a debit.
} ]
IsSuccessfull
booleanReturns true if all requests were successfully submitted to the queue for processing, otherwise false.
Duration
stringThe length of time it took to submit the payments.
Message
stringReturns All payments are in queue for process if Failures is empty, otherwise returns Not all payments are in queue, please resend failures at a later time.
}
400Bad RequestBad request - no payments in body
Payment Manipulation
Retrieve, amend or delete individual payments on a contract.
DELETE/client/{clientCode}/contract/{contractId}/payment/{paymentId}Deletes an existing payment from the database (providing it has not yet been submitted to BACS)#
description:
Deletes an existing payment from the database (providing it has not yet been submitted to BACS)
stringHuman-readable description of frequency and terms.
Frequency
stringPayment frequency (e.g. Annually, Monthly, Weekly).
Every
floatRepeat interval (e.g. every 1 month).
DaysOfMonth
stringComma-separated day-of-month values.
DayOfWeek
stringDay of week, or Free for customer choice.
StartType
stringWhen payments start (e.g. As soon as possible).
TerminationType
stringWhen payments end (e.g. Until further notice).
RegistrationCharge
floatOne-off registration charge amount.
IsNotScheduled
booleantrue if this is a non-scheduled (ad-hoc) service.
IsSuspended
booleantrue if the schedule is currently suspended.
}
}
}
DDCMS Direct File Import
Upload BACS payment files for processing through DDCMS Direct. Requires the DDCMS Direct feature to be enabled on your account.
POST/client/{clientCode}/ddcmsdirect/importImports a BACS payment file via the API for processing through DDCMS Direct#
description:
Imports a file into DDCMS Direct for processing through the existing approval workflows. The file undergoes initial structural validation based on the specified fileType. If validation passes, the file is stored and queued for further validation. Prerequisites:
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
request body:
{
file
string (binary upload)MandatoryThe file to be imported. Must be in one of the supported formats: BACS Standard 18, BACS Standard 18 Payment Lines, SmartDebit Direct CSV, or BACS Active (EaziPay).
fileType
stringMandatoryPossible values: bacs_standard_18, bacs_standard_18_payment_lines, smartdebit_direct_csv, bacs_active_eazipayThe file format type, which determines which structural validation rules are applied to the uploaded file. Must be one of the following values: - bacsstandard18 - BACS Standard 18 - bacsstandard18paymentlines - BACS Standard 18 Payment Lines - smartdebitdirectcsv - SmartDebit Direct CSV - bacsactiveeazipay - BACS Active (EaziPay)
}
Responses
200OK
response body:
{
status
stringReturns success when the file has been imported.
fileId
string (guid)The unique idenitifer assigned to the imported file. You should save this for future reference.
importedAt
string (date-time)The date/time at which the file was imported.
message
stringA human-readable message confirming the import.
fileStatus
stringThe current status of the file. Will be Queued for validation on a successful import.
nextSteps
stringGuidance on what to do next after a successful import.
}
400Bad Request
response body:
{
status
stringReturns error for parameter issues, or validation_failed for structural validation features.
message
stringA human-readable description of the error.
errors [ {
Only present when status is validation_failed. An array of structural validation errors found in the file.
category
stringThe category of the error (e.g. structuralvalidation, fileformat).
message
stringA human-readable description of the specific validation error.
} ]
errorType
stringOnly present when status is validation_failed. Returns structural.
supportedFileTypes
arrayOnly present when the error is caused by an invalid fileType value. Lists the supported file type keys.
}
403Forbidden
response body:
{
status
string
message
string
}
413Payload Too Large
response body:
{
status
string
message
string
maxFileSizeBytes
integerThe maximum file size allowed, in bytes (137000000).
}
500Internal Server Error
response body:
{
status
string
message
string
}
Configurable Represents
Retrieve and update your automatic re-presentation settings for failed payments, and manually trigger a re-presentation for a specific eligible payment.
POST/client/{clientCode}/contract/{contractId}/payment/{paymentId}/retryTriggers a re-presentation for a specific failed payment#
description:
Triggers a re-presentation for a specific failed payment. The payment must be eligible: within 1 calendar month of the original payment date, the Direct Debit Instruction must be active, and the payment must not already be in a Pending or Paid status.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
contractId
string (guid)MandatoryThe contract ID for the payment.
paymentId
string (guid)MandatoryThe payment ID to represent.
}
request body:
{
ProcessingDate
string (date-time)MandatoryThe date the re-presented payment should be collected. Must be a working day within 1 calendar month of the original payment date.
}
Responses
200OK
response body:
{
Message
stringConfirms the payment retry has been scheduled.
}
400Bad RequestBad Request - payment not eligible, processing date not a valid working day, date exceeds Bacs limit, or required fields missing.
401UnauthorizedUnauthorised - invalid or missing API key.
403ForbiddenForbidden - the payment belongs to a different client.
404Not FoundNot Found - payment or contract not found.
GET/client/{clientCode}/unpaidPaymentRetrySettingsReturns the current retry configuration for your client#
description:
Returns the current retry configuration for your client.
string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
request body:
{
AllowRetryFailedPayments
booleanMandatorySet to true to enable Configurable Represents, false to disable.
RetryPaymentsDelayDays
integerWorking days between a failed payment and re-presentation. Minimum = your look-forward days setting; maximum = 20. Required when AllowRetryFailedPayments is true.
FailedPaymentRetries
integerMaximum retry attempts. Range: 1-3. Required when AllowRetryFailedPayments is true.
}
Responses
200OK
response body:
{
AllowRetryFailedPayments
booleanWhether Configurable Represents is enabled for your organisation.
RetryPaymentsDelayDays
integerNumber of working days configured between a failed payment and its re-presentation.
FailedPaymentRetries
integerMaximum number of retry attempts configured (1-3).