Direct Debit
Return Payloads
If you have provided us with a return endpoint using the Return Endpoint call, data
will be posted back to you either in XML or JSON as required. The default is JSON – if
you need XML return information, please let us know.
We also have the option for you to set custom headers that'll be sent for every notification from DDCMS to your endpoints - please raise a support case if this is something you require, telling us the header name and value to send.
Object Change Return Information
Example JSON Payload
This is for an ADDACS change – where a customer has cancelled their Direct Debit with the bank.
{
"NewStatus": "Cancelled",
"Id": "ac190e35-2fa7-162c-8505-18702c186a43",
"ChangeDate": "2017-05-09T10:20:10",
"Entity": "contract",
"ChangeType": "BACS",
"Source": "ADDACS",
"ReportCode": "1",
"ReportMessage": "Contract Cancelled because of ADDACS code 1 (Instruction Cancelled)",
"Comment": "Auto-updated by BACS file"
}
Example XML Payload
This is for an ARUDD change when a customer’s payment has been returned unpaid by the bank.
<root>
<NewStatus>Unpaid</NewStatus>
<Id>f6dc0f34-1a71-4493-a0af-2f0993f36dc5</Id>
<ChangeDate>2017-05-09T12:17:50</ChangeDate>
<Entity>payment</Entity>
<ChangeType>BACS</ChangeType>
<Source>ARUDD</Source>
<ReportCode>0</ReportCode>
<ReportMessage>The payment marked as 'Unpaid' because of ARUDD code 0 (Refer to Payer)</ReportMessage>
<Comment>Auto-updated by BACS file</Comment>
</root>
Output Parameters
| Parameter | Description |
|---|---|
| AccountName | If the Entity type is customer, the customers name as it appears on their bank account. |
| AccountNumber | If the Entity type is customer, the customers bank account number. |
| SortCode | If the Entity type is customer, the bank sort code of the customer. |
| NewStatus | This is the new status of the object. For payments, this can be: Represented Pending Paid Unpaid Withdrawn Indemnity Claimed For contracts: Expired Cancelled Pause Suspended Cancellation Pending Active Creation Pending |
| Id | The GUID of the object being reported on. |
| ChangeDate | The date/time that the change took place. |
| Entity | The entity type: either payment, contract or customer. |
| ChangeType | BACS or Manual depending on how the change came about. |
| Source | ADDACS, ARUDD, DDIC or Manual depending on the source if the change. |
| ReportCode | If the change came from a BACS report (ADDACS, ARUDD or DDIC) the reason code will appear in this field. It will be null in the case of a manual change. |
| ReportMessage | Plain text explanation of the change. We recommend this is logged at your end for reference. |
| Comment | If any comment was input by a user during a manual change, it will appear here. |
Object Change Report Codes
The following is a list of all potential BACS Report codes we can send to your webhooks. For more information please see our Guide to BACS Reporting and Transaction Codes
| Source | Entity | ReportCode | ReportMessage |
|---|---|---|---|
| AUDDIS | Contract | 1 | Instruction Cancelled by Payer |
| AUDDIS | Contract | 2 | Payer Deceased |
| AUDDIS | Contract | 3 | Account Transferred to a new Bank or Building Society |
| AUDDIS | Contract | 5 | No Account |
| AUDDIS | — | 6 | No Instruction |
| AUDDIS | Contract | B | Account Closed |
| AUDDIS | Customer | C | Account Transferred to a Different Branch of Bank/Building Society |
| AUDDIS | Contract | F | Invalid Account Type |
| AUDDIS | Contract | G | Bank will not accept Direct Debits on Account |
| AUDDIS | Contract | H | Instruction has Expired |
| AUDDIS | Contract | I | Payer Reference is not Unique |
| AUDDIS | Contract | K | Instruction Cancelled by Paying Back |
| ADDACS | Contract | 0 | Instruction Cancelled - Refer to Payer |
| ADDACS | Contract | 1 | Instruction Cancelled |
| ADDACS | Contract | 2 | Payer Deceased |
| ADDACS | Customer | 3 | Account transferred to new Bank or Building Society |
| ADDACS | Contract | B | Account Closed |
| ADDACS | Customer | C | Account transferred to a different branch of Bank or Building Society |
| ADDACS | Contract | D | Advance Notice Disputed |
| ADDACS | Customer | E | Instruction Amended |
| ADDACS | Contract | R | Instruction Reinstated |
| ARUDD | Payment | 0 | Refer to Payer |
| ARUDD | Payment | 1 | Instruction Cancelled |
| ARUDD | Payment | 2 | Payer Deceased |
| ARUDD | Payment | 3 | Account Transferred |
| ARUDD | Payment | 4 | Advance Notice Disputed |
| ARUDD | Payment | 5 | No Account |
| ARUDD | Payment | 6 | No Instruction |
| ARUDD | Payment | 7 | Amount Differs |
| ARUDD | Payment | 8 | Amount Not Yet Due |
| ARUDD | Payment | 9 | Presentation Overdue |
| ARUDD | Payment | A | Service User Differs |
| ARUDD | Payment | B | Account Closed |
| DDIC | Contract | 1 | The amount and/or date of the Direct Debit differs from the Advance Notice |
| DDIC | Contract | 2 | No advance notice was received by the payer or the amount quoted is disputed by the payer |
| DDIC | Contract | 3 | DDI cancellation by the paying bank |
| DDIC | Contract | 4 | Payer has cancelled the DDI direct with the Service User |
| DDIC | Contract | 5 | Payer disputes having given authority |
| DDIC | Contract | 6 | Signature on DDI is fraudulent or not in accordance with the account authorised signature(s) held by the paying bank |
| DDIC | Contract | 7 | An indemnity claim has been raised at the Service User's request |
| DDIC | Contract | 8 | Payer does not recognise Service User collecting Direct Debit |
New Payment Generated Notification Information
This notification is submitted to your payments webhook whenever DDCMS generates a new payment on either a fixed or rolling regular schedule. This does NOT send information on payments submitted on an adhoc schedule.
Currently the callback URL for these notifications cannot be changed via the API - if you wish to setup or amend the callback for New Payment Generated notifications, please raise a support case.
Example JSON Payload
{
"CustomerId": "8e8880dc-d36a-500e-9757-dcdab7418f8a",
"CustomerRef": null,
"ContractId": "bca883a2-e939-44ff-b3f0-9823°00dd388",
"DirectDebitRef": "ABC-XY009999",
"DateAdded": "2021-02-19T11:22:26.7662254+00:00",
"DateDue": "2021-03-01T00:00:00",
"Amount": 49.7,
"Comments": null,
"Id": "59cde7d8-1a81-4da3-b04f-10e71020ed74",
"Entity": "payment",
"CreateType": "BACS",
"Source": null,
"Status": "Pending"
}
New eDD Signup Notification Information
This notification is submitted when a contract is created from a payer completing registration on an Access Payments eDD page linked to your DDCMS client account.
This does NOT send information on contracts added via the POST /contract endpoint, or added manually in the DDCMS portal. This is ONLY for contracts added via eDD.
Currently the callback URL for these notifications cannot be changed via the API - if you wish to setup or amend the callback for New eDD Signups, please raise a support case.
{
"CustomerId": "e4e9bdad-4370-4072-ad4f-77454a42d839",
"AdditionalRef": "My Additional Ref",
"DirectDebitReference": "ABC-XY123456",
"ScheduleName": "Monthly",
"Description": "Monthly > Every 1 month > Day chosen by customer starting on any month (customer's choice) > Until further notice > Switch to further notice",
"PaymentMonthInYear": 4,
"PaymentDayInMonth": 15,
"PaymentDayInWeek": null,
"Start": "2023-04-15T00:00:00",
"TerminationDate": null,
"TerminationType": "Until further notice",
"NumberOfDebits": null,
"InitialAmount": null,
"ExtraInitialAmounts": "",
"Amount": 15,
"FinalAmount": null,
"Every": 1,
"IsGiftAid": true,
"AtTheEnd": "Switch to further notice",
"Status": "Creation Pending",
"StatusExplanation": "",
"Id": "6062addf-768c-40d6-af08-e8e4e32d7c80",
"Entity": "contract",
"CreateType": "API",
"Source": null
}
Bulk Payment Insert Return Information
This is what the API returns from a bulk payment insert - see the Bulk Adding Payments section for more info.
Example XML Payload - Successful Insert
<root>
<Contract>07024c7a-c31c-46c1-8e0e-8fcff640b35c</Contract>
<Amount>15.99</Amount>
<DueDate>2017-06-01T00:00:00</DueDate>
<Id>1522c59f-87dc-4b31-9931-a6083776f670</Id>
<Error />
<Comment>Successful Payment Example</Comment>
<IsCredit>false</IsCredit>
<Message />
</root>
Example XML Payload - Error
<root>
<Contract>07024c7a-c31c-46c1-8e0e-8fcff640b35c</Contract>
<Amount>15.99</Amount>
<DueDate>2017-06-01T00:00:00</DueDate>
<Id>00000000-0000-0000-0000-000000000000</Id>
<Error>Contract not found - Invalid Contract Id</Error>
<Comment>Failed Payment Example</Comment>
<IsCredit>false</IsCredit>
<Message />
</root>
Example JSON Payload - Successful Insert
{
"Contract":"07024c7a-c31c-46c1-8e0e-8fcff640b35c",
"Amount":15.99,
"DueDate":"2017-06-01T00:00:00",
"Id":"23bc8558-51cd-4c4e-b223-260010c69d38",
"Error": null,
"Comment": "Successful Payment Example",
"IsCredit": false,
"Message": null
}
Example JSON Payload - Error
{
"Contract":"07024c7a-c31c-46c1-8e0e-8fcff640b35c",
"Amount":15.99,
"DueDate":"2017-06-01T00:00:00",
"Id": "00000000-0000-0000-0000-000000000000",
"Error": "Contract not found - Invalid Contract Id",
"Comment": "Failed Payment Example",
"IsCredit": false,
"Message": null
}
Output Parameters
| Parameter | Description |
|---|---|
| Contract | The Contract GUID that the payment has been added to. |
| Amount | The amount of the payment. |
| DueDate | The due date of the payment. |
| Id | The payment GUID that you should keep a record of. If the request fails, this will be 00000000-0000-0000-0000-000000000000 |
| Error | Any validation errors will appear here. |
| Comment | The custom comment passed in for this payment request. |
| IsCredit | Whether the payment is a credit (True) or debit (False) collection. |
| Message | Any validation messages or warnings will appear here. |
Schedule Change Return Information
The payload is sent to the configured 'Schedule Change' callback URL when a schedule's settings are changed, a new schedule is created or a schedule is completely deleted.
Example JSON Payload
{
"Entity": "schedule",
"Id": "94821c14-8ba3-483f-a9db-02af004d9938",
"Schedule": {
"ScheduleId": "94821c14-8ba3-483f-a9db-02af004d9938",
"Name": "yyy",
"Description": "Weekly > Every 1 week > Week day chosen by customer starting on any month (customer's choice) > First , then on a regular basis",
"AllowDifferentFirstPayment": false,
"AllowDifferentLastPayment": false,
"AllowFreeMonthDaySelection": true,
"AllowFreeMonthSelection": true,
"AllowFreeWeekDaySelection": true,
"Amount": null,
"AtTheEnd": "Expire",
"DayOfWeek": "Free",
"DaysOfMonth": "Free",
"Every": 1,
"ExpectedNumberOfPayments": null,
"ExtraInitialPayments": "",
"FinalAmount": null,
"Frequency": "Weekly",
"InitialAmount": null,
"IsExpiryDateReached": false,
"IsNotScheduled": false,
"IsSuspended": false,
"MonthOfYear": "Free",
"RegistrationCharge": 0.0,
"Start": null,
"StartType": "As soon as possible",
"TerminationDate": null,
"TerminationType": "Until further notice"
},
"ParentService": {
"Title": "Default Service",
"RefProtocol": "Auto-number",
"RefPrefix": "DEF",
"RefFrom": null,
"RefTo": null,
"Schedules": null
},
"ParentClient": {
"Id": "da550c70-b879-4e89-b918-00f8ecb4d703",
"Name": "The Waffle Factory",
"ClientPrefix": "WF"
},
"ChangeDate": "2021-08-12T08:04:38",
"OperationTypeVal": 1,
"OperationType": "Create"
}
Output Parameters
| Parameter | Description |
|---|---|
| Entity | Returns 'schedule'. |
| Id | The schedule's database GUID. |
| Schedule | Details of the affected schedule - see the Obtaining Available Schedules section for more info. |
| Parent Service | Details of the service which the schedule belongs to - see the Obtaining Available Schedules section for more info. |
| Parent Client | Details of the client account the schedule belongs to. Id - GUID of the client account. Name - The client's name Client Prefix - The client code used for API operations. |
| Change Date | Date-time for when the action took place. |
| Operation Type Val | Integer value for the OperationType enum. |
| Operation Type | Action performed on the schedule - can be Create, Update or Delete. |