Direct Debit

Contract Querying and Creation

A contract record represents the Direct Debit associated with a customer record. There are two forms of contract record:

  • Ad-hoc: This is where a Direct Debit is created at the bank for the customer, but no payments are requested unless you specifically input payments via the Payments or Bulk Payments API call.
  • Scheduled: In this mode, a schedule for payments is stated at the outset and the system will create the relevant payments in the database approximately five working days before the payments become due. Schedules can usually be weekly or monthly, however the frequencies available will be communicated to you when the API details are provided.

Customers can have multiple contracts attached to them in order that they may have multiple payment streams being collected simultaneously.

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

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 (if the customer already exists).
}

Responses

200OK
response body:
{
  • CustomerId
    string (guid)Database GUID for the given customer.
}
Example request
Endpoint
GET /client/{clientCode}/customer/{customerId}/contract
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/{customerId}/contract' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Contracts": [
    {
      "Amount": 1,
      "AtTheEnd": "Expire",
      "Description": "Collect an initial \u00a31.00 followed by 9 payments of\n\u00a31.00 on 15th of the month ending on 25th April 2017\n",
      "DirectDebitReference": "LUISCT-MT000325",
      "Every": 1,
      "ExtraInitialAmounts": "",
      "Id": "7aa8cef6-ec95-47a7-9ced-4aa0938559ab",
      "InitialAmount": 1,
      "IsGiftAid": true,
      "NumberOfDebits": 10,
      "PaymentDayInMonth": "15",
      "PaymentMonthInYear": 7,
      "ScheduleName": "DD Dates 1/15 - Fixed",
      "Start": "2016-07-15T00:00:00.000Z",
      "Status": "Active",
      "StatusExplanation": "N/A",
      "TerminationType": "Take certain number of debits"
    }
  ],
  "CustomerId": "19283a22-7442-4c92-b035-8fa7f5e6a9a0"
}
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.

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 (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
Example — query parameters
Endpoint
POST /client/{clientCode}/customer/{customerId}/contract
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/{customerId}/contract?scheduleName=adhoc_monthly_free&start=2019-08-01&isGiftAid=false&terminationType=Until further notice&atTheEnd=Switch to further notice' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "DirectDebitRef": "LUISCT-MT000341",
  "Id": "e39940cc-9917-4b9e-8da4-5da4866862f1"
}
HTTP/1.1 400 Bad Request

{
  "Message": "{scheduleName} is not given to any schedule of any service as a name\n"
}
Example — request body
Endpoint
POST /client/{clientCode}/customer/{customerId}/contract
Request body
{
  "ScheduleName": "adhoc_monthly_free",
  "Start": "2019-08-01T00:00:00.000",
  "IsGiftAid": false,
  "TerminationType": "Until further notice",
  "AtTheEnd": "Switch to further notice"
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/{customerId}/contract' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"ScheduleName":"adhoc_monthly_free","Start":"2019-08-01T00:00:00.000","IsGiftAid":false,"TerminationType":"Until further notice","AtTheEnd":"Switch to further notice"}'
Response
HTTP/1.1 200 OK

{
  "DirectDebitRef": "LUISCT-MT000341",
  "Id": "e39940cc-9917-4b9e-8da4-5da4866862f1"
}
HTTP/1.1 400 Bad Request

{
  "Message": "{scheduleName} is not given to any schedule of any service as a name\n"
}

Contract statuses

Upon creation, a Contract Status will read “Active”. While a newly created contract is awaiting its first collection, it is inadvisable to attempt to make changes to the contract or to push ad-hoc payments to the contract as payments may be missed or marked unpaid without an attempt to collect being made. We recommend allowing the lead times that apply to your configuration to elapse before making changes to the contract or pushing ad-hoc payments into the system.

StatusDescription
ActiveThe contract is active and will either produce payments, if it is a scheduled contract, or accept ad-hoc payments, if it is an ad-hoc contract.
InactiveThe contract has been cancelled and is no longer active. It cannot produce or accept payments, scheduled or otherwise.

For more information on a contract's status, the StatusExplanation field can provide a more detailed explanation. This field is free text and we recommend that it is stored and displayed to the end user as necessary.

Timeframes

You should also be aware that you must allow a minimum number of clear working days between setting up a contract and collecting the first payment, and a minimum number of clear working days between pushing a second or subsequent ad-hoc payment and its collection date on an active contract. The number of days required is configured per client and is not the same for all clients, so you should refer to the lead times that apply to your own configuration.

A working day means a banking day in the United Kingdom — Monday to Friday, excluding public and bank holidays. A list of bank holidays is at https://www.gov.uk/bank-holidays, and a date checker is provided at https://www.accesspaysuite.com/date.

While the above timeframes are the minimum required, we strongly recommend building a day or two of contingency into your processes so that you have time to rectify any problems encountered. We are unable under any circumstances to accept instructions for payments or new contracts after the appropriate cut off dates.