Direct Debit

Contract Amendment

Changing the payment amount or date on a scheduled contract can be achieved by using one of the following calls. You will need to select the correct call for the type of contract that you are amending. For example, changing the date on a monthly contract will need a monthly call. We have only shown the responses from one of the calls as all of the calls respond in the same manner. One example of an error is shown, however you should be prepared to accept different errors and handle them as exceptions during the testing stage.

PATCH/client/{clientCode}/contract/{contractId}/amountChanging the Amount#
description:

Amends an existing contract amount in the database.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • contractId
    string (guid)MandatoryThe contract GUID that you wish to amend.
}
query parameters:
{
  • amount
    float (decimal places ≤ 2)MandatoryThe new amount to be taken.
  • comment
    string (≤ 255 chars)MandatoryA comment to explain the reason for the change of amount.
}
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
Example request
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/amount
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/amount?amount=9.99&comment=Change contract amount' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Contract updated"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "Amount should be different than old contract amount",
  "ErrorCode": 3,
  "Message": "Validation error"
}
PATCH/client/{clientCode}/contract/{contractId}/annualChanging the Date (Annual Schedules)#
description:

Amends an existing contract payment date in the database.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract
{
  • clientCode
    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
Example request
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/annual
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/annual?monthDay=15&month=1&comment=Change day&patchNextPayment=false' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Contract updated"
}
HTTP/1.1 400 Bad Request

{
  "Message": "Month day is invalid for this contract"
}
PATCH/client/{clientCode}/contract/{contractId}/monthlyChanging the Date (Monthly Schedules)#
description:

Amends an existing contract payment date in the database.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract
{
  • clientCode
    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
Example request
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/monthly
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/monthly?monthDay=15&comment=Change day&patchNextPayment=false' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Contract updated"
}
HTTP/1.1 400 Bad Request

{
  "Message": "Month day is invalid for this contract"
}
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.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract
{
  • clientCode
    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
Example request
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/reference
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/reference?newDDRef=TEST-MT012345' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Contract reference updated"
}
HTTP/1.1 403 Forbidden

{
  "Message": "API not enabled"
}
HTTP/1.1 404 Not Found

{
  "Message": "Contract not found"
}
PATCH/client/{clientCode}/contract/{contractId}/weeklyChanging the Day (Weekly Schedules)#
description:

Amends an existing contract payment date in the database.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract
{
  • clientCode
    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
Example request
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/weekly
Request body
{}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/weekly?day=5&comment=Change to Friday&patchNextPayment=false' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Contract updated"
}
HTTP/1.1 400 Bad Request

{
  "Message": "Day is invalid for this contract"
}