Direct Debit

Client Info

Retrieve configuration info about your DDCMS client.

GET/client/{clientCode}/infoRetrieve configuration info about your DDCMS client#

description:

Retrieve configuration info about your DDCMS client.

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.

}

Responses

200OK

response body:

{

CustomerEmailMandatory
booleanWhether or not the email parameter is required when adding new customer records.

}

Example request

Endpoint

GET /client/{clientCode}/info

cURL

curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/info' \
  -H 'apiKey: {apiKey}'

Response

HTTP/1.1 200 OK

{
  "CustomerEmailMandatory": true
}

POST/client/{clientCode}/paymentsList all payments registered against your DDCMS client#

description:

List all payments registered against your DDCMS client.

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.

}

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.
} ]

}

400Bad RequestBad Request — invalid status/type value, or pageSize exceeds configured maximum.

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.

Example request

Endpoint

POST /client/{clientCode}/payments

Request body

{
  "PageNumber": 1,
  "PageSize": 100,
  "ContractId": "00000000-0000-0000-0000-000000000000",
  "CustomerId": "00000000-0000-0000-0000-000000000000",
  "IsCredit": false,
  "IsScheduled": false,
  "Status": "Indemnity Claimed",
  "Type": "Credit",
  "CollectionDateFrom": "YYYY-MM-DDT00:00:00.000Z",
  "CollectionDateTo": "YYYY-MM-DDT00:00:00.000Z",
  "CreatedAfter": "YYYY-MM-DDT00:00:00.000Z",
  "CreatedBefore": "YYYY-MM-DDT00:00:00.000Z"
}

cURL

curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/payments' \
  -H 'apiKey: {apiKey}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"PageNumber":1,"PageSize":100,"ContractId":"00000000-0000-0000-0000-000000000000","CustomerId":"00000000-0000-0000-0000-000000000000","IsCredit":false,"IsScheduled":false}'

Response

HTTP/1.1 200 OK

{
  "Pagination": {
    "Page": 1,
    "PageSize": 100,
    "TotalPages": 5,
    "TotalRecords": 499
  },
  "Data": [
    {
      "Id": "c36ce83c-0064-4c1e-a157-cd4c70decf47",
      "Amount": 9.99,
      "Comment": "Monthly payment",
      "Date": "2019-08-01T00:00:00.000Z",
      "IsAdhoc": false,
      "IsCredit": false,
      "ReasonCode": null,
      "ReasonMessage": null,
      "Status": "Paid",
      "Type": "Regular"
    }
  ]
}

HTTP/1.1 400 Bad Request

{
  "ErrorCode": 3,
  "Detail": "Invalid status value",
  "Message": "Validation error"
}

HTTP/1.1 403 Forbidden

{
  "ErrorCode": 0,
  "Detail": null,
  "Message": "This contract cannot be used in API."
}

HTTP/1.1 500 Internal Server Error

{
  "Message": "An unexpected error occurred while processing the request."
}