Direct Debit

Adding/Querying Payments

Lodge ad-hoc payments against a contract, and query the payments already held against it.

GET/client/{clientCode}/contract/{contractId}/paymentQueries the database and returns details of payments related to the specified contract#
description:

Queries the database and returns details of payments related to the specified contract

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 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:
{
}
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
Example request
Endpoint
GET /client/{clientCode}/contract/{contractId}/payment
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Payments": [
    {
      "Amount": 15.99,
      "Comment": "This is a test",
      "Date": "2017-05-15T00:00:00.000Z",
      "Id": "36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b",
      "IsAdhoc": true,
      "IsCredit": false,
      "ReasonCode": 0,
      "Status": "Pending",
      "Type": "BACS"
    }
  ]
}
HTTP/1.1 403 Forbidden

{
  "Message": "Contract cannot be accessed"
}
HTTP/1.1 404 Not Found

{
  "Message": "Contract 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

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 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).
}
400Bad RequestBad request - invalid payment amount
403ForbiddenForbidden - contract is protected
404Not FoundContract not found
Example — query parameters
Endpoint
POST /client/{clientCode}/contract/{contractId}/payment
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment?amount=10.00&date=2019-08-01&comment=A comment' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Amount": 15.99,
  "Contract": "b3c17b6f-9ad2-4fa3-9a33-8a8f6813ab1f",
  "DueDate": "2017-05-15T00:00:00.000Z",
  "Id": "1b2ac277-5f1f-424a-b55f-323d5bcef8f6"
}
HTTP/1.1 400 Bad Request

{
  "Message": "Amount must be greater than zero"
}
HTTP/1.1 403 Forbidden

{
  "Message": "Contract cannot be accessed"
}
HTTP/1.1 404 Not Found

{
  "Message": "Contract not found"
}
Example — request body
Endpoint
POST /client/{clientCode}/contract/{contractId}/payment
Request body
{
  "Amount": 10.0,
  "Comment": "A comment.",
  "Date": "2019-08-01T00:00:00.000",
  "IsCredit": false
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Amount":10.0,"Comment":"A comment.","Date":"2019-08-01T00:00:00.000","IsCredit":false}'
Response
HTTP/1.1 200 OK

{
  "Amount": 15.99,
  "Contract": "b3c17b6f-9ad2-4fa3-9a33-8a8f6813ab1f",
  "DueDate": "2017-05-15T00:00:00.000Z",
  "Id": "1b2ac277-5f1f-424a-b55f-323d5bcef8f6"
}
HTTP/1.1 400 Bad Request

{
  "Message": "Amount must be greater than zero"
}
HTTP/1.1 403 Forbidden

{
  "Message": "Contract cannot be accessed"
}
HTTP/1.1 404 Not Found

{
  "Message": "Contract not found"
}