Direct Debit

Return Endpoints

Return data is passed to endpoints of your choice by setting the URL that data should be posted to using the API. Data is returned to three separate endpoints based on the entity described, as explained in the table below. Each callback can be set to pass data to the same endpoint. You should contact us to advise whether you require return information in XML or JSON format; the default is JSON.

EntityPayload
bulkpaymentNotification of success/failure to process a bulk payment request - see 'Bulk Adding Payments' section for more info.
customerNotification of customer changes due to BACS notifications
contractNotification of contract changes due to BACS notifications
paymentNotification of payment status (Unpaid/Indemnity Claimed) changes due to BACS notifications
scheduleNotification of change, addition or deletion of a contract schedule

Setting these URLs is what makes the payloads on Return Payloads arrive.

DELETE/client/{clientCode}/BACS/{entity}/callbackClears the set callback URL for the given return endpoint#
description:

Clears the set callback URL for the specified entity.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-entity
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • entity
    stringMandatoryPossible values: bulkpayment, customer, contract, payment, scheduleThe entity for which to receive callback BACS messages.
}

Responses

200OK
response body:
{
  • Message
    stringConfirms the callback URL has been cleared.
}
Example request
Endpoint
DELETE /client/{clientCode}/BACS/{entity}/callback
cURL
curl -L -g -X DELETE 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/BACS/contract/callback' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Callback URL cleared."
}
GET/client/{clientCode}/BACS/{entity}/callbackGet the callback URL for the given return endpoint#
description:

Returns the assigned callback URL for the specified entity.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-entity
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • entity
    stringMandatoryPossible values: bulkpayment, customer, contract, payment, scheduleThe entity for which to receive callback BACS messages.
}

Responses

200OK
response body:
{
  • Message
    stringThe currently assigned callback URL.
}
401UnauthorizedUnauthorised - API not enabled or API key incorrect
404Not FoundNot found - Client code incorrect
405Method Not AllowedAPI key not provided
Example request
Endpoint
GET /client/{clientCode}/BACS/{entity}/callback
cURL
curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/BACS/contract/callback' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "https://my.website.com/webhook"
}
HTTP/1.1 401 Unauthorized

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

{
  "ErrorCode": 7,
  "Message": "API not enabled"
}
HTTP/1.1 405 Method Not Allowed

{
  "Message": "The requested resource does not support http method 'POST'."
}
POST/client/{clientCode}/BACS/{entity}/callbackSets the callback URL for the given return endpoint#
description:

Sets the callback URL for the specified entity.

authorization:ApiKeyAuth
content-type: application/json
path parameters:
shared schema directDebit/path/client-entity
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
  • entity
    stringMandatoryPossible values: bulkpayment, customer, contract, payment, scheduleThe entity for which to receive callback BACS messages.
}
query parameters:
{
  • url
    string (url)MandatoryNew value for the callback URL.
}
request body:

{} — This call takes no request body — send an empty JSON object.

Responses

200OK
response body:
{
  • Message
    stringConfirms the callback URL has been assigned.
}
Example request
Endpoint
POST /client/{clientCode}/BACS/{entity}/callback
Request body
{}
cURL
curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/BACS/contract/callback?url=https://my.website.com/webhook' -H 'apiKey: {apiKey}'
Response
HTTP/1.1 200 OK

{
  "Message": "Callback URL assigned."
}