Direct Debit

Patches

On regularly scheduled contracts, patches can be used to make temporary changes to the payments generated, or stop them from generated. Patches can not be applied to ad-hoc contracts. We offer four different types of patches:

  • Change amount
  • Freeze collect (leave contract as is)
  • Give notice (terminate contract)
  • Skip collection

Please note that for Give notice (terminate contract) patches, we allow GET, PATCH and DELETE requests for, but we do not allow to be created via the API. To add a give notice patch, you must do this via the admin UI.

POST/client/{clientCode}/contract/{contractId}/patch/changeamountAdds a patch to change payment amount for a contract#
description:

Adds a patch to change payment amount for a 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 on which to add the patch.
}
query parameters:
{
  • from
    string (date-time)MandatoryStart date of the patch.
  • to
    string (date-time)MandatoryEnd date of the patch.
  • amount
    float (decimal)MandatorySets the contract's effective amount during the patch period.
  • comment
    stringMandatoryComment for the patch.
}
request body:
{
  • Comment
    string
  • From
    string (date-time)
  • To
    string (date-time)
  • Amount
    float
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the patch has been added.
}
400Bad RequestBad Request - Overlapping patches
404Not FoundContract not found
Example — query parameters
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/changeamount
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/changeamount?from=2021-12-05T00%3A00%3A00&to=2021-12-15T00%3A00%3A00&amount=9.99&comment=Price+increase' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
Example — request body
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/changeamount
Request body
{
  "Comment": "Price increase",
  "From": "2021-12-05T00:00:00",
  "To": "2021-12-15T00:00:00",
  "Amount": 9.99
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/changeamount' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Comment":"Price increase","From":"2021-12-05T00:00:00","To":"2021-12-15T00:00:00","Amount":9.99}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
POST/client/{clientCode}/contract/{contractId}/patch/skipAdds a patch to skip collections for a contract#
description:

Adds a patch to skip collections for a 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 on which to add the patch.
}
query parameters:
shared schema directDebit/patch-window
{
  • Comment
    string
  • From
    string (date-time)
  • To
    string (date-time)
}
request body:
shared schema directDebit/patch-window
{
  • Comment
    string
  • From
    string (date-time)
  • To
    string (date-time)
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the patch has been added.
}
400Bad RequestBad Request - Overlapping patches
404Not FoundContract not found
Example — query parameters
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/skip
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/skip?from=2021-12-05T00%3A00%3A00&to=2021-12-15T00%3A00%3A00&comment=Payment+pause' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
Example — request body
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/skip
Request body
{
  "Comment": "Payment pause",
  "From": "2021-12-05T00:00:00",
  "To": "2021-12-15T00:00:00"
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/skip' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Comment":"Payment pause","From":"2021-12-05T00:00:00","To":"2021-12-15T00:00:00"}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
POST/client/{clientCode}/contract/{contractId}/patch/freezeAdds a patch to freeze collections for a contract#
description:

Adds a patch to freeze collections for a 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 on which to add the patch.
}
query parameters:
shared schema directDebit/patch-window
{
  • Comment
    string
  • From
    string (date-time)
  • To
    string (date-time)
}
request body:
shared schema directDebit/patch-window
{
  • Comment
    string
  • From
    string (date-time)
  • To
    string (date-time)
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the patch has been added.
}
400Bad RequestBad Request - Overlapping patches
404Not FoundContract not found
Example — query parameters
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/freeze
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/freeze?from=2021-12-05T00%3A00%3A00&to=2021-12-15T00%3A00%3A00&comment=Payment+freeze' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
Example — request body
Endpoint
POST /client/{clientCode}/contract/{contractId}/patch/freeze
Request body
{
  "Comment": "Payment freeze",
  "From": "2021-12-05T00:00:00",
  "To": "2021-12-15T00:00:00"
}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/freeze' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"Comment":"Payment freeze","From":"2021-12-05T00:00:00","To":"2021-12-15T00:00:00"}'
Response
HTTP/1.1 200 OK

{
  "Message": "New Patch added to contract"
}
HTTP/1.1 400 Bad Request

{
  "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.",
  "ErrorCode": 3,
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
GET/client/{clientCode}/contract/{contractId}/patchesReturns all patches applied to a given contract#
description:

Returns all patches applied to a given 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 on which the patches have been applied to.
}

Responses

200OK
response body:
{
}
404Not FoundContract not found
Example request
Endpoint
GET /client/{clientCode}/contract/{contractId}/patches
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patches' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Patches": [
    {
      "Id": "bd686494-2b90-47b4-95f9-e88568aeb49f",
      "DateAdded": "2021-11-25T14:32:49",
      "Type": "Change amount",
      "DateFrom": "2021-12-15T00:00:00",
      "DateTo": "2021-12-25T00:00:00",
      "Amount": 11,
      "Comment": "Price increase"
    },
    {
      "Id": "769f959c-57b2-4c7e-82c5-8179b9094c7e",
      "DateAdded": "2021-11-25T14:34:14",
      "Type": "Skip collection (adjusts contract)",
      "DateFrom": "2021-12-25T00:00:00",
      "DateTo": "2022-01-05T00:00:00",
      "Amount": null,
      "Comment": "Payment pause"
    },
    {
      "Id": "a4642e6c-75c3-4439-9474-c073925eb47c",
      "DateAdded": "2021-11-25T14:38:08",
      "Type": "Freeze collect (leave contract as is)",
      "DateFrom": "2022-01-10T00:00:00",
      "DateTo": "2022-01-15T00:00:00",
      "Amount": null,
      "Comment": "Payment pause 2"
    }
  ]
}
HTTP/1.1 404 Not Found

{
  "error": "The requested resource is not found"
}
GET/client/{clientCode}/contract/{contractId}/patch/{patchId}Gets details of a specific patch#
description:

Gets details of a specific patch

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract-patch
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • contractId
    string (guid)MandatoryThe contract GUID on which the patch has been applied to.
  • patchId
    string (guid)MandatoryThe patch GUID.
}

Responses

200OK
response body:
{
  • Amount
    float (decimal)If type is Change amount, defines the effective contract amount during this patch.
  • Comment
    stringA user-defined comment for this patch.
  • DateAdded
    string (date-time)Date-time this patch was added in the system.
  • DateFrom
    string (date-time)Start date for the patch.
  • DateTo
    string (date-time)End date for the patch.
  • Id
    string (guid)The GUID for this patch object.
  • Type
    stringPossible values: Change amount, Freeze collect (leave contract as is), Skip collection (adjusts contract)Type of patch.
}
404Not FoundContract/patch not found
Example request
Endpoint
GET /client/{clientCode}/contract/{contractId}/patch/{patchId}
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/{patchId}' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Id": "bd686494-2b90-47b4-95f9-e88568aeb49f",
  "DateAdded": "2021-11-25T14:32:49",
  "Type": "Change amount",
  "DateFrom": "2021-12-15T00:00:00",
  "DateTo": "2021-12-25T00:00:00",
  "Amount": 11,
  "Comment": "Price increase"
}
HTTP/1.1 404 Not Found

{
  "ErrorCode": 0,
  "Detail": null,
  "Message": "Patch not found"
}
PATCH/client/{clientCode}/contract/{contractId}/patch/{patchId}Updates the end date of a patch#
description:

Updates the end date of a patch

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract-patch
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • contractId
    string (guid)MandatoryThe contract GUID on which the patch has been applied to.
  • patchId
    string (guid)MandatoryThe patch GUID.
}
query parameters:
{
  • to
    string (date-time)MandatoryThe new end date to set for this patch.
  • comment
    stringMandatoryA comment for this update.
}
request body:
{
  • To
    string (date-time)
  • Comment
    string
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the patch has been updated.
}
400Bad RequestBad Request - Invalid To date
404Not FoundContract/patch not found
Example — query parameters
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/patch/{patchId}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/{patchId}?to=2021-12-25T00%3A00%3A00&comment=Extended+patch' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

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

{
  "ErrorCode": 3,
  "Detail": "To date should be greater than From Date. Please check patch dates",
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "ErrorCode": 0,
  "Detail": null,
  "Message": "Patch not found"
}
Example — request body
Endpoint
PATCH /client/{clientCode}/contract/{contractId}/patch/{patchId}
Request body
{
  "To": "2021-12-15T00:00:00.000",
  "Comment": "Extend patch"
}
cURL
curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/{patchId}' \
  -H 'Content-Type: application/json' \
  -H 'apiKey: {apiKey}' \
  -d '{"To":"2021-12-15T00:00:00.000","Comment":"Extend patch"}'
Response
HTTP/1.1 200 OK

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

{
  "ErrorCode": 3,
  "Detail": "To date should be greater than From Date. Please check patch dates",
  "Message": "Validation error"
}
HTTP/1.1 404 Not Found

{
  "ErrorCode": 0,
  "Detail": null,
  "Message": "Patch not found"
}
DELETE/client/{clientCode}/contract/{contractId}/patch/{patchId}Deletes a patch#
description:

Deletes a patch

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-contract-patch
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • contractId
    string (guid)MandatoryThe contract GUID on which the patch has been applied to.
  • patchId
    string (guid)MandatoryThe patch GUID.
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the patch has been deleted.
}
404Not FoundContract/patch not found
Example request
Endpoint
DELETE /client/{clientCode}/contract/{contractId}/patch/{patchId}
cURL
curl -L -g -X DELETE 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/patch/{patchId}' \
  -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Patch deleted"
}
HTTP/1.1 404 Not Found

{
  "ErrorCode": 0,
  "Detail": null,
  "Message": "Patch not found"
}