{ "swagger": "2.0", "info": { "description": "**NOTICE:** The hosts for the API are now located at `ddcms.accesspaysuite.com` and `playpen.accesspaysuite.com`, instead of `ecm3.eazycollect.co.uk` and `playpen.eazycollect.co.uk` respectively.\n\nWhile the old URLs will continue to work as normal, and although there's no plans currently to disable these URLs, we would strongly recommend you update your integration to call the new URLs.\n\n**NOTICE:** The URL hosting this documentation has now been updated to https://api-docs-ddcms-v3.accesspaysuite.com\n\nWe strongly encourage all of our customers to actively change to using this new link. Connections to the current site https://eazycollectservices.github.io/EazyCollectAPIv3/ will automatically redirect to https://api-docs-ddcms-v3.accesspaysuite.com. However, we only intend to maintain this automatic redirect across a transitional period, so please ensure you update your bookmarks and links as soon as possible.\n## About Access Paysuite\nAccess PaySuite is a leading provider of payment solutions to mid-sized UK organisations. Part of The Access Group, it combines payments expertise with unparalleled SaaS experience to help customers across commercial and not for profit sectors improve their payment solutions, providing organisations with the freedom to accelerate their innovation and growth. For more information about Access PaySuite, visit www.accesspaysuite.com\n\nOur Collection Services are based around our Direct Debit and Credit Management System\n(DDCMS) application which manages the Direct Debit process from beginning to end and is connected\nto a robust and powerful BACS submission engine. The system also provides a range of\nmanagement information via the easy to use secure web interface.\n\n## API Technical Details\n\nThe API is REST based and communication is conducted over a regular\nHTTPS connection. It accepts input in the `x-www-form-urlencoded` format\nwith output being provided in either JSON or XML format as required.\n\nThe output is selected using the `Accept` header including either\n`application/json` or `application/xml`. The API key should be also be\nspecified in the request using the `apiKey` header.\n\nOur API uses four different HTTP methods to indicate the different\noperations being undertaken on the data being manipulated. These are:\n\n|**Method** | **Operation**\n| -------------- | --------------\n| **HTTP GET** | Request for information from the server. The server will respond with the data requested.\n| **HTTP POST** | Request to create a record on the server. The POST request must be accompanied by the relevant data in the body or query string as dictated by the specification below.\n| **HTTP PATCH** | Request to amend (or partially amend) the record on the server.\n| **HTTP DELETE**| A request to remove a record from the server (only available on the client return data endpoint call).\n\n### Example Headers for JSON Mode:\n\n```\nGET https://ddcms.accesspaysuite.com/api/v3/client/LUISCT/BACS/customer/callback\n\nAccept: application/json\napiKey: xAQdXTPtZPG3QqsUJw73wx1o\nContent-Type: application/json\n```\n\n## The Direct Debit Process\n\nThroughout the development of our API we have sought to simplify the\nDirect Debit process as much as possible, however due to the technical\nnature of Direct Debits it is helpful to understand the general data\nflow and the reasons for certain time delays. For additional\ninformation about the time delays required when setting up new Direct\nDebit contracts or ad-hoc collections, please see \"*A note on Working Days*\".\n\n1. After creating a ‘Customer’ record on our system, you will need to\nassign a ‘schedule’ to them. The schedule can take a number of forms:\n - A schedule that can collect ad-hoc payments as and when you\n request them via the API. There will usually be date\n restrictions in place.\n - A schedule where you ask us to collect regular amounts on\n regular dates in a month, or days in a week as per your requirements.\n - A schedule where a pre-determined amount is taken on regular\n dates in a month, or days in a week as per your instructions.\n - A schedule where the collection amounts and or dates are fixed.\n\n Access Paysuite creates the schedules as part of the set-up process and\n the available schedules can be listed by using the ‘schedules’ call.\n\n2. As soon as a schedule is applied to a customer record, we send an\ninstruction to BACS to create the Direct Debit instruction. The date\nfor the first payment required should be set at least your SUN's\nconfigured *First Payment Delay* after the schedule creation date.\n\n3. Ad-hoc payments need to be lodged onto *DDCMS*\nat least your SUN's configured *Subsequent Payment Delay* before the\ncollection date.\n\n4. Around three working days before the collection date, we submit the\npayments to BACS for collection. Payments cannot be changed after\nsubmission has occurred.\n\n5. The final status of the payment records can be enquired upon 3\nworking days following the collection date. Where a payment\ncollection date falls on a weekend or a non UK banking day, the\ncollection date is automatically moved to the next working day, and\nthe developer will need to take this into account. (e.g.: A payment\nscheduled on Saturday, 1st June 2013 will be collected on Monday\n3rd June 2013. Payment statuses will be available from Thursday\n6th June 2013.)\n\n## A note on Working Days\n\nRegarding these time delays, you will see mention of two particular delays\nthat need to be considered, particularly when adding new Direct Debit\ncontracts or ad-hoc payments:\n- **First Payment Delay:** Default is **10 working days** but can be as low\n as **5**.\n- **Subsequent Payment Delay:** Default is **5 working days** but can be as\n low as **3**.\n\nIf you wish to lower these delays whilst testing the API in our playpen,\nplease raise a support case. Requests to lower delays on a live account\nshould be raised with your Customer Success Manager or sales contact. Note\nthat it may not be possible for us to change your account's configured\ndelays.\n\nWe ask that our clients that their First Payment Delay is the **absolute\nminimum** between creating a customer and contract and collecting the first\npayment. Payments for existing contracts must be submitted and confirmed\nby 12pm the Subsequent Payment Delay before the collection date for existing\ncustomers with an active Direct Debit.\n\nWe strongly recommend that customers are created and payments uploaded\n1 -2 days in advance of these cut off times as these deadlines leave\n**no** contingency to problem solve any issues that arise which could\nlead to payments being missed.\n\n**It is important to note** that if a collection date falls on a weekend\nor a bank holiday, then the delay rules start from the following working day;\nso for a Saturday or a Sunday, the number of working days to delay should be\ncounted back from the next non-UK bank holiday Monday.\n\n**For example:**\n\nAssuming **First Payment Delay** = **10 working days** and **Subsequent Payment Delay** = **5 working days**\n\nFor payments due on Saturday 19/04/2025\n- Payments for existing customers would need to be submitted and\n confirmed by 12pm on Monday 14/04/2025.\n- New customers would need to be confirmed by 12pm on Monday 07/04/2025.\n\n**Note:** 18/04/2025 (Good Friday) and 21/04/2025 (Easter Monday) are Bank\nHolidays in the UK and do not count as banking days.\n\nTo view the deadlines for lodging collections for new and existing customers\nfor any given collection date, please see our **Date Calculator** at\nhttps://www.accesspaysuite.com/date. Alternatively, see the `GET /paymentdate`\nAPI call available under **Payment Dates** to see the earliest possible\ndates for first and subsequent payments.\n\n## Using the API and UI together\n\nDDCMS provides a useful User Interface (UI) available\nvia your browser which gives access to your customer data and a suite of\nreports.\n\nIf you have chosen to do a “full integration” with your own Customer\nRelationship Management or Accounting software, then it must be borne in\nmind that your software is driving the payment process entirely. In\n“full integration” mode you will be using the API to set up direct\ndebits and send ad-hoc payments as and when collections are required; in\nthis arrangement we generally advise against using the UI other than to\ndownload paid/unpaid reports.\n\nIt is important to note that when using the API in a “full integration”\nthe following anomalies will be present within the UI:\n\n- The account and arrears balances shown in the Access Paysuite UI\n against each customer will not reflect manual payments made in your\n CRM/Accounts package unless they are also (double) keyed as manual\n payments onto the DDCMS UI.\n\nIf you require any further assistance with using the API and UI\ntogether, please contact the IT Helpdesk at support@accesspaysuite.com\n\n## Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof an API call. The error body provided will be either JSON or XML format \nper the preference included within the headers. Due to the complexity of the \nAPI and the Direct Debit Scheme, we are unable to provide a definitive list \nof all the errors that the system may generate, however we have attempted \nto make the errors generated as clear as possible – i.e. Plain English. \nWe also recommend using the panels on the right hand side to get aquainted\nwith the HTTP status codes the API may return. \n\n**Examples:**\n\n**JSON:**\n```json\n{\n \"Message\": \"The requested resource does not support http method 'POST'.\"\n}\n```\n\n**XML:**\n```xml\n\n The requested resource does not support http method 'POST'.\n\n```\n \n## Environments\nWe offer two environments to developers, `playpen` and `ddcms`. Our `playpen` environment is designed\nfor all your testing needs. Our `ddcms` environment is our production environment and we strongly\nrecommend using the `playpen` environment to get acquainted with how the API functions and returns\ndata. If you would like access to our `playpen` environment, please contact our sales team at `sales@accesspaysuite.com`. \n\nThe two environments behave identically, with the only difference being how you would access an environment. All requests to our production environment would go through `ddcms.accesspaysuite.com` whereas requests for our playpen environment would go through `playpen.accesspaysuite.com`.\n\n contact:\nemail: support@accesspaysuite.com\n", "license": { "name": "MIT", "url": "https://github.com/EazyCollectServices/EazyCollectAPIv3/blob/master/LICENSE" }, "title": "Access Paysuite", "version": "3.0.0", "x-logo": { "backgroundColor": "#4b112c", "url": "https://www.accesspaysuite.com/media/iwwhai0a/paysuite-logo.png" } }, "host": "ddcms.accesspaysuite.com", "basePath": "/api/v3", "schemes": [ "https" ], "paths": { "/client/{clientCode}/BACS/{entity}/callback": { "delete": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The entity for which to receive callback BACS messages.", "enum": [ "bulkpayment", "customer", "contract", "payment", "schedule" ], "in": "path", "name": "entity", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "schema": { "example": { "Message": "Callback URL cleared." }, "type": "string" } }, "application/xml": "\n Callback URL cleared.\n" } } }, "tags": [ "Return Endpoints" ], "description": "Clears the set callback URL for the specified entity.", "summary": "Clears the set callback URL for the given return endpoint", "x-codeSamples": [ { "lang": "C#", "source": "var delete = new Delete(settings); string request = delete.CallbackUrl(\"contract\");\n" }, { "lang": "Python", "source": "client = eazysdk.EazySDK() request = client.delete.callback_url(\"contract\")\n" }, { "lang": "Java", "source": "Delete delete = new Delete(settings); String request = delete.callbackUrl(\"contract\");\n" }, { "lang": "cURL", "source": "curl -L -g -X DELETE 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/BACS/contract/callback' -H 'apiKey: {apiKey}'\n" } ] }, "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The entity for which to receive callback BACS messages.", "enum": [ "bulkpayment", "customer", "contract", "payment", "schedule" ], "in": "path", "name": "entity", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "https://my.website.com/webhook" }, "application/xml": "https://my.website.com/webhook" } }, "401": { "description": "Unauthorised - API not enabled or API key incorrect", "examples": { "application/json": { "Message": "API not enabled" }, "application/xml": "API\n not enabled7" } }, "404": { "description": "Not found - Client code incorrect", "examples": { "application/json": { "ErrorCode": 7, "Message": "API not enabled" }, "application/xml": "API\n not enabled7" } }, "405": { "description": "API key not provided", "examples": { "application/json": { "Message": "The requested resource does not support http method 'POST'." }, "application/xml": "The requested resource does not support http method 'POST'." } } }, "tags": [ "Return Endpoints" ], "description": "Returns the assigned callback URL for the specified entity.", "summary": "Get the callback URL for the given return endpoint", "x-codeSamples": [ { "lang": "C#", "source": "var get = new Get(settings); string response = get.CallbackUrl(\"contract\");\n" }, { "lang": "Python", "source": "client = eazysdk.EazySDK() response = client.get.callback_url(\"contract\")\n" }, { "lang": "Java", "source": "Get get = new Get(settings); String response = get.callbackUrl(\"contract\");\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/BACS/contract/callback' -H 'apiKey: {apiKey}'\n" } ] }, "post": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The entity for which to receive callback BACS messages.", "enum": [ "bulkpayment", "customer", "contract", "payment", "schedule" ], "in": "path", "name": "entity", "required": true, "type": "string" }, { "description": "New value for the callback URL.", "format": "url", "in": "query", "name": "url", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Callback URL assigned." }, "application/xml": "Callback\n URL assigned." } } }, "tags": [ "Return Endpoints" ], "description": "Sets the callback URL for the specified entity.", "summary": "Sets the callback URL for the given return endpoint", "x-codeSamples": [ { "lang": "C#", "source": "var post = new Post(settings); string request = post.CallbackUrl(\"contract\", \"https://my.website.com/webhook\");\n" }, { "lang": "Python", "source": "client = eazysdk.EazySDK() request = client.post.callback_url(entity=\"contract\", callback_url=\"https://my.website.com/webhook\")\n" }, { "lang": "Java", "source": "Post post = new Post(settings); String request = post.callbackUrl(\"contract\", \"https://my.website.com/webhook\");\n" }, { "lang": "cURL", "source": "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}'\n" } ] } }, "/client/{clientCode}/info": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "schema": { "properties": { "CustomerEmailMandatory": { "type": "boolean", "description": "Whether or not the `email` parameter is required when adding new customer records." } } }, "examples": { "application/json": { "CustomerEmailMandatory": true } } } }, "tags": [ "Client Info" ], "description": "Retrieve configuration info about your DDCMS client.", "summary": "Retrieve configuration info about your DDCMS client." } }, "/client/{clientCode}/payments": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Example JSON payload format.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/ClientListPaymentsRequest" } } ], "responses": { "200": { "description": "OK - Paginated list of payments returned. Empty Data array if no matches. Sorted by createdAt descending.", "schema": { "properties": { "Pagination": { "type": "object", "properties": { "Page": { "description": "Page number for the pagination.", "type": "number" }, "PageSize": { "description": "Number of payment records to return per page.", "type": "number" }, "TotalPages": { "description": "Total number of pages returned by the search.", "type": "number" }, "TotalRecords": { "description": "Total number of payment records returned by the search.", "type": "number" } } }, "Data": { "type": "array", "items": { "$ref": "#/definitions/Payment" } } } } }, "400": { "description": "Bad Request - {specific error message} e.g. invalid status/type value, pageSize exceeds configured maximum." }, "403": { "description": "Forbidden - This contract cannot be used in API. When contract is protected." }, "500": { "description": "Internal Server Error - An unexpected error occurred while processing the request." } }, "tags": [ "Client Info" ], "description": "List all payments registered against your DDCMS client.", "summary": "List all payments registered against your DDCMS client." } }, "/client/{clientCode}/bulk/payments": { "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The payments to be processed.\n", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/BulkPaymentRequest", "example": { "Payments": [ { "amount": 1.1, "comment": "Up to 256 characters, optional", "contract": "GUID", "date": "YYYY-MM-DDT00:00:00.000", "isCredit": false }, { "amount": 1.1, "comment": "Up to 256 characters, optional", "contract": "GUID", "date": "YYYY-MM-DDT00:00:00.000", "isCredit": false } ] }, "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "properties": { "FailureCount": { "type": "number", "description": "Number of payment requests that failed to push to the queue." }, "Failures": { "type": "array", "items": { "$ref": "#/definitions/BulkPayment" }, "description": "Array of payment requests that failed to push to the queue." }, "IsSuccessfull": { "type": "boolean", "description": "Returns `true` if all requests were successfully submitted to the queue for processing, otherwise `false`." }, "Duration": { "type": "string", "description": "The length of time it took to submit the payments." }, "Message": { "type": "string", "description": "Returns `All payments are in queue for process` if Failures is empty, otherwise returns `Not all payments are in queue, please resend failures at a later time`." } } }, "examples": { "application/json": { "FailureCount": 0, "Failures": [], "IsSuccessfull": true, "Message": "All payments are in queue for process" }, "application/xml": "\n \n 0\n true\n All payments are in queue for process\n\n" } }, "400": { "description": "Bad request - no payments", "examples": { "application/json": { "ErrorCode": 2, "Detail": "No payments found in request", "Message": "Parameter arguments incorrect" }, "application/xml": "\n 2\n No payments found in request\n Parameter arguments incorrect\n\n" } } }, "tags": [ "Bulk Adding Payments" ], "summary": "Sends a list of payment requests to a queue to be processed in bulk.", "x-codeSamples": [ { "lang": "cURL", "sample": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/bulk/payments' -H 'apiKey: {apiKey}' -H 'Content-Type: application/json' --data-raw '{\n \"Payments\": [\n {\n \"contract\": \"1802e1dd-a657-428c-b8d0-ba162fc76203\",\n \"amount\": 9.99,\n \"date\": \"2019-08-01T00:00:00.000\",\n \"comment\": \"New payment\",\n \"isCredit\": false\n }\n ]\n }'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/amount": { "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The new amount to be taken.", "in": "query", "multipleOf": 0.01, "name": "amount", "required": true, "type": "number" }, { "description": "A comment to explain the reason for the change of amount.", "in": "query", "maxLength": 255, "name": "comment", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract updated" }, "application/xml": "\n Contract updated\n\n" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Detail": "Amount should be different than old contract amount", "ErrorCode": 3, "Message": "Validation error" }, "application/xml": "\n Validation error\n 3\n Amount should be different than old contract amount\n\n" } } }, "tags": [ "Contract Amendment" ], "description": "Amends an existing contract amount in the database.", "summary": "Changing the Amount", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.ContractAmount(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"9.99\", \"Change contract amount\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.patch.contract_amount('36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b', 10.50,\n'A comment')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Patch patch = new Patch(settings);\nString request = patch.contractAmount(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"9.99\", \"Change contract amount\");\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/amount?amount=9.99&comment=Change contract amount' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/annual": { "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The new day of the month on which payments are to be taken.\n**NOTE:** *You may not* select days `29`, `30` or `31` of the month;\nif you wish to select the last day of the month; pass the string\n`Last day of the Month`.\nPayments will be collected on the next available instance of the payment\nday, which will be a **minimum** of 5 working days in the future. Any\npayment already scheduled in the next 5 working days *will still be\ncollected*.\n", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "Last Day of the Month" ], "in": "query", "name": "monthDay", "required": true, "type": "string" }, { "description": "The new month in the year on which the payments are to be taken.", "in": "query", "maximum": 12, "minimum": 1, "name": "month", "required": true, "type": "integer" }, { "description": "A comment to explain the reason for the change of day.", "in": "query", "maxLength": 255, "name": "comment", "required": true, "type": "string" }, { "description": "If you wish to take the next payment to be a different amount (e.g.\npro rata because the number of days between payments will deb different)\nthen pass the amount using this parameter. Ensure that `patchNextPayment`\nis set to `true` if you are using this.\n", "in": "query", "multipleOf": 0.01, "name": "nextPaymentPatchAmount", "type": "number" }, { "description": "Set to `true` if using `nextPaymentPatchAmount` or `false` if not.\n", "in": "query", "name": "patchNextPayment", "required": true, "type": "boolean" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract updated" }, "application/xml": "\n Contract updated\n\n" } }, "400": { "description": "Bad request - invalid day", "examples": { "application/json": { "Message": "Month day is invalid for this contract" }, "application/xml": "\n Month day is invalid for this contract\n\n" } } }, "tags": [ "Contract Amendment" ], "description": "Amends an existing contract payment date in the database.", "summary": "Changing the Date (Annual Schedules)", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.ContractDayAnnually(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"15\", \"1\", \"Change day\", false);\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "contract_date_annually('36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b',\n15, 6, 'A comment', False)\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Patch patch = new Patch(settings);\nString request = patch.contractDayAnnually(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"15\", \"1\", \"Change day\", false);\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/annual?monthDay=15&month=1&comment=Change day&patchNextPayment=false' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/archive": { "post": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to archive.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract archived" }, "application/xml": "\n Contract archived\n\n" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "API not enabled" }, "application/xml": "\n API not enabled\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Archiving a Contract" ], "description": "**NOTE:** It is not possible to “unarchive” a contract once the archive\nprocess has been initiated.\n", "summary": "Cancels the direct debit, writes off any outstanding arrears balance, cancels\nfuture payments and sets the contract status to “archived”.\n", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.ArchiveContract(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.archive_contract('42217d45-cf22-4430-ab02-acc1f8a2d020')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.archiveContract(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/archive' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/cancel": { "post": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to cancel the direct debit on.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract cancelled" }, "application/xml": "\n Contract cancelled\n\n" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "Contract cannot be accessed" }, "application/xml": "\n Contract cannot be accessed\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Cancelling the Direct Debit (Does not cancel payment creation)" ], "description": "Future payments will be created within our system, but automatically marked\nas unpaid.\n", "summary": "Changes the status of the Direct Debit to “Cancelled”.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.CancelDirectDebit(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.cancel_direct_debit('42217d45-cf22-4430-ab02-acc1f8a2d020')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.cancelDirectDebit(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/cancel' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/monthly": { "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The new day of the month on which payments are to be taken.\n**NOTE:** *You may not* select days `29`, `30` or `31` of the month;\nif you wish to select the last day of the month; pass the string\n`Last day of the Month`.\nPayments will be collected on the next available instance of the payment\nday, which will be a **minimum** of 5 working days in the future. Any\npayment already scheduled in the next 5 working days *will still be\ncollected*.\n", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "Last Day of the Month" ], "in": "query", "name": "monthDay", "required": true, "type": "string" }, { "description": "A comment to explain the reason for the change of day.", "in": "query", "maxLength": 255, "name": "comment", "required": true, "type": "string" }, { "description": "If you wish to take the next payment to be a different amount (e.g.\npro rata because the number of days between payments will deb different)\nthen pass the amount using this parameter. Ensure that `patchNextPayment`\nis set to `true` if you are using this.\n", "in": "query", "multipleOf": 0.01, "name": "nextPaymentPatchAmount", "type": "number" }, { "description": "Set to `true` if using `nextPaymentPatchAmount` or `false` if not.\n", "in": "query", "name": "patchNextPayment", "required": true, "type": "boolean" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract updated" }, "application/xml": "\n Contract updated\n\n" } }, "400": { "description": "Bad request - invalid day", "examples": { "application/json": { "Message": "Month day is invalid for this contract" }, "application/xml": "\n Month day is invalid for this contract\n\n" } } }, "tags": [ "Contract Amendment" ], "description": "Amends an existing contract payment date in the database.", "summary": "Changing the Date (Monthly Schedules)", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.ContractDayMonthly(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"15\", \"Change day\", false);\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.patch.contract_date_monthly('36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b',\n15, 'A comment', False)\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Patch patch = new Patch(settings);\nString request = patch.contractDayMonthly(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"15\", \"Change day\", false);\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/monthly?monthDay=15&comment=Change day&patchNextPayment=false' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/payment": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to query.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The 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.\n", "in": "query", "maximum": 100, "minimum": 1, "name": "rows", "required": true, "type": "integer" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "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" } ] }, "application/xml": "\n \n \n 36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b\n Pending\n false\n true\n 15.99\n 2017-05-15T00:00:00\n 0\n This is a test\n BACS\n \n \n\n" }, "schema": { "properties": { "Payments": { "items": { "$ref": "#/definitions/Payment" }, "type": "array" } }, "type": "object" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "Contract cannot be accessed" }, "application/xml": "\n Contract cannot be accessed\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Adding/Querying Payments" ], "summary": "Queries the database and returns details of payments related to the\nspecified contract.\n", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.Payments(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.payments('ab09362d-f88e-4ee8-be85-e27e1a6ce06a')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get(settings);\nString response = get.payments(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\");\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment' -H 'apiKey: {apiKey}'\n" } ] }, "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to query.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The amount to be collected.", "in": "query", "multipleOf": 0.01, "name": "amount", "type": "number" }, { "description": "The date on which the payment should be collected.\nThis **must** be at least 5 **working** days in the future, on a permitted\ndate and not before the start date set when creating the contract.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "date", "type": "string" }, { "description": "A comment relating to the payment (which can be recalled using the GET\nmethod).\n", "in": "query", "maxLength": 200, "name": "comment", "type": "string" }, { "description": "If you have an own SUN and you have agreed by prior arrangement with your\naccount manager that you may issue credits, pass `true` with this parameter\nto issue a credit to the customer.\n", "in": "query", "name": "isCredit", "type": "boolean" }, { "description": "Example JSON/XML payload format.\n", "in": "body", "name": "body", "schema": { "example": { "Amount": 10, "Comment": "A comment.", "Date": "2019-08-01T00:00:00.000", "IsCredit": false }, "type": "object", "xml": { "name": "PaymentRequest" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Amount": 15.99, "Contract": "b3c17b6f-9ad2-4fa3-9a33-8a8f6813ab1f", "DueDate": "2017-05-15T00:00:00.000Z", "Id": "1b2ac277-5f1f-424a-b55f-323d5bcef8f6" }, "application/xml": "\n b3c17b6f-9ad2-4fa3-9a33-8a8f6813ab1f\n 15.99\n 2017-05-15T00:00:00\n 36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b\n\n" }, "schema": { "properties": { "Amount": { "description": "The amount of the payment.", "multipleOf": 0.01, "type": "number" }, "Contract": { "description": "The GUID of the contract to which the payment has been applied.\n", "format": "guid", "type": "string" }, "DueDate": { "description": "The due date (date of collection) of the payment.", "format": "date-time", "type": "string" }, "Error": { "description": "If any error occurs, a message will appear here.", "type": "string" }, "Id": { "description": "The GUID of the payment. We suggest that you save this so that you\ncan easily change or query the payment in future. If you are using\npushed return data, this will be included in any payload delivered\nconcerning the payment.\n", "format": "guid", "type": "string" }, "Message": { "description": "If any additional message from the system is generated, it will\nappear here (usually null).\n", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad request - invalid payment amount", "examples": { "application/json": { "Message": "Amount must be greater than zero" }, "application/xml": "\n Amount must be greater than zero\n\n" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "Contract cannot be accessed" }, "application/xml": "\n Contract cannot be accessed\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Adding/Querying Payments" ], "summary": "Adds a payment to the database to the contract specified in the URL.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.Payment(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"10.00\", \"2019-08-01\", \"A comment\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.payment('42217d45-cf22-4430-ab02-acc1f8a2d020', '10.00',\n '2019-05-07', 'A new payment')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.payment(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"10.00\", \"2019-08-01\", \"A comment\");\n" }, { "lang": "cURL", "source": "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}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/payment/{paymentId}": { "delete": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the payment you are amending has been lodged.\n", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The payment GUID of the payment you wish to amend.\n", "format": "guid", "in": "path", "name": "paymentId", "required": true, "type": "string" }, { "description": "A comment that can be returned when querying the payment.", "in": "query", "maxLength": 200, "name": "comment", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Payment deleted" }, "application/xml": "\n Payment deleted\n\n" } }, "400": { "description": "Bad request - missing comment", "examples": { "application/json": { "Message": "Comment must not be empty" }, "application/xml": "\n Comment must not be empty\n\n" } }, "403": { "description": "Forbidden - payment contract is protected", "examples": { "application/json": { "Message": "Payment cannot be accessed" }, "application/xml": "\n Payment cannot be accessed\n\n" } }, "404": { "description": "Payment not found", "examples": { "application/json": { "Message": "Payment not found" }, "application/xml": "\n Payment not found\n\n" } } }, "tags": [ "Payment Manipulation" ], "summary": "Deletes an existing payment from the database (providing it has not yet been submitted to BACS).", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var delete = new Delete(settings);\nstring request = delete.Payment(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"750f142f-1608-464a-8e34-4b322e703c2c\", \"A comment\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.delete.payment('2b62a358-9a1a-4c71-9450-e419e393dcd1', '750f142f-1608-464a-8e34-4b322e703c2c', 'A comment')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Delete delete = new Delete(settings);\nString request = delete.payment(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"750f142f-1608-464a-8e34-4b322e703c2c\", \"A comment\");\n" }, { "lang": "cURL", "source": "curl -L -g -X DELETE 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment/{paymentId}?comment=A comment' -H 'apiKey: {apiKey}'\n" } ] }, "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the payment you are amending has been lodged.\n", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The payment GUID of the payment you wish to amend.\n", "format": "guid", "in": "path", "name": "paymentId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "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" }, "application/xml": "\n 36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b\n Pending\n false\n true\n 15.99\n 2017-05-15T00:00:00\n 0\n This is a test\n BACS\n\n" } }, "403": { "description": "Forbidden - payment contract is protected", "examples": { "application/json": { "Message": "Payment cannot be accessed" }, "application/xml": "\n Payment cannot be accessed\n\n" } }, "404": { "description": "Payment not found", "examples": { "application/json": { "Message": "Payment not found" }, "application/xml": "\n Payment not found\n\n" } } }, "tags": [ "Payment Manipulation" ], "summary": "Queries the database for details of an existing payment.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.PaymentsSingle(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"6917d51a-be83-424f-b0a6-31fbf9574a79\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.payments_single('ab09362d-f88e-4ee8-be85-e27e1a6ce06a',\n '36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get(settings);\nString response = get.paymentsSingle(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"6917d51a-be83-424f-b0a6-31fbf9574a79\");\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment/{paymentId}' -H 'apiKey: {apiKey}'\n" } ] }, "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the payment you are amending has been lodged.\n", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The payment GUID of the payment you wish to amend.\n", "format": "guid", "in": "path", "name": "paymentId", "required": true, "type": "string" }, { "description": "A comment that can be returned when querying the payment.", "in": "query", "maxLength": 200, "name": "comment", "required": true, "type": "string" }, { "description": "The amount you wish to change the payment to.", "in": "query", "multipleOf": 0.01, "name": "amount", "required": true, "type": "number" }, { "description": "The date on which you require the payment to be taken.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "date", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Payment updated" }, "application/xml": "\n Payment updated\n\n" }, "schema": { "$ref": "#/definitions/Payment" } }, "400": { "description": "Bad request - invalid arguments", "examples": { "application/json": { "Message": "An amount, comment or date must be passed" }, "application/xml": "\n An amount, comment or date must be passed\n\n" } }, "403": { "description": "Forbidden - payment contract is protected", "examples": { "application/json": { "Message": "Payment cannot be accessed" }, "application/xml": "\n Payment cannot be accessed\n\n" } }, "404": { "description": "Payment not found", "examples": { "application/json": { "Message": "Payment not found" }, "application/xml": "\n Payment not found\n\n" } } }, "tags": [ "Payment Manipulation" ], "summary": "Amends an existing payment in the database.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.Payment(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"a75f9829-2753-4f67-aafb-bb24aba27dd1\", \"10.00\", \"2019-08-01\", \"test comment\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.patch.payment('36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b',\n'36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b', 10.50, '2019-06-04',\n'A comment')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Patch patch = new Patch(settings);\nString request = patch.payment(\"2b62a358-9a1a-4c71-9450-e419e393dcd1\", \"a75f9829-2753-4f67-aafb-bb24aba27dd1\", \"10.00\", \"2019-08-01\", \"test comment\");\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment/{paymentId}?amount=10.00&date=2019-08-01&comment=Test comment' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/reactivate": { "post": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to reactivate.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract reactivated" }, "application/xml": "\n Contract reactivated\n\n" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "Contract cannot be accessed" }, "application/xml": "\n Contract cannot be accessed\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Reactivating a Direct Debit" ], "summary": "Reactivates the Direct Debit if it is in the ***Cancelled*** state.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.ReactivateDirectDebit(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.reactivate_direct_debit('42217d45-cf22-4430-ab02-acc1f8a2d020')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.reactivateDirectDebit(\"1802e1dd-a657-428c-b8d0-ba162fc76203\");\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/reactivate' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/reference": { "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "If you have made arrangements with us to use a custom direct debit \nreferencing scheme, pass the new custom direct debit using this parameter.\nThe field may only contain alphanumeric data (`a-z`, `A-Z`, `0-9`) and\ncertain special characters (hyphen `-` or solidus `/`).\n", "in": "query", "maxLength": 18, "name": "newDDRef", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract reference updated" }, "application/xml": "\n Contract reference updated\n\n" } }, "403": { "description": "Forbidden - account not authorised", "examples": { "application/json": { "Message": "API not enabled" }, "application/xml": "\n API not enabled\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Contract Amendment" ], "description": "In general, our software will allocate a unique direct debit reference\nfor every contract created within the system. For own SUN and FM SUN\nclients that have made prior arrangements with us, it is possible to\nchange a reference number after the contract has been set up. Please\nnote that using this facility will incur extra charges as new\ninstructions will need to be sent to the bank via BACS.\n", "summary": "Changing the Direct Debit Reference (for authorised users only)", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/reference?newDDRef=TEST-MT012345' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/restart": { "post": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to restart.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "If the contract is for regular payments, then the day on which you wish\nthe first payment should be passed with this parameter. **NOTE:** *You\nmay not* select days 29, 30 or 31 of the month; if you wish to select the\nlast day of the month; pass the integer value 99 which represent `Last day of the Month`.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\nThis field is only mandatory if the contract is **annual** or **monthly**.\nYou may only select days 1 to 28 or “Last day of the month” which is equal with value 99.\nChoosing 29, 30 or 31 will result in payments being skipped in\nmonths that do not contain that date.\n", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 99 ], "in": "query", "name": "paymentDayInMonth", "type": "integer" }, { "description": "If the contract is for regular payments then the month in which you\nwish the first payment should be passed with this parameter.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\nThis field is only mandatory if the contract is **annual** or **monthly**.\n", "in": "query", "maximum": 12, "minimum": 1, "name": "paymentMonthInYear", "type": "integer" }, { "description": "Pass the way in which the contract should end using this parameter.\nIf the contract is **ad-hoc,** *you must* pass `Until further notice`.\n", "enum": [ "Take certain number of debits", "Until further notice", "End on exact date" ], "in": "query", "name": "terminationType", "required": true, "type": "string" }, { "description": "If this is a “Take certain Number of Debits” contract then the number of\ndebits to be taken should be passed using this parameter.\nThis field is only mandatory if the termination type is “Take Certain\nNumber of Debits”.\n", "in": "query", "maximum": 999, "minimum": 0, "name": "numberOfDebits", "type": "integer" }, { "description": "If this is a contract for regular payments **and** the first payment is\ndifferent to the regular payments, then pass the first payment amount\nwith this parameter.\n**Do not** pass this parameter with ad-hoc contracts, or where the first\namount is the same as the regular amount.\n", "in": "query", "multipleOf": 0.01, "name": "initialAmount", "type": "number" }, { "description": "If the contract is for regular payments, then the regular payment\namount should be passed using this parameter. Do not pass this\nparameter if the contract is an ad-hoc contract.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\n", "in": "query", "multipleOf": 0.01, "name": "amount", "type": "number" }, { "description": "If this is a contract for regular payments **and** the final payment is\ndifferent to the regular payments, then pass the final payment amount\nwith this parameter. **Do not** pass this parameter with ad-hoc\ncontracts, or where the final amount is the same as the regular amount.\n", "in": "query", "multipleOf": 0.01, "name": "finalAmount", "type": "number" }, { "description": "This parameter decides what will happen when the contract ends. If you have\nselected a `terminationType` of `Until Further Notice` or the contract is an\nad-hoc contract, *you must* pass `Switch to Further Notice`.\n", "enum": [ "Expire", "Switch to Further Notice" ], "in": "query", "name": "atTheEnd", "required": true, "type": "string" }, { "description": "If you wish to add an additional reference to the contract for you own use,\nthis can be passed to using the `additionalReference` parameter.\n", "in": "query", "maxLength": 200, "name": "additionalReference", "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract restarted" }, "application/xml": "\n Contract restarted\n\n" } }, "400": { "description": "Bad request - invalid restart date", "examples": { "application/json": { "Message": "Start date must be greater than {minStartDate}\n" }, "application/xml": "\n Start date must be greater than {minStartDate}\n\n" } }, "403": { "description": "Forbidden - contract is protected", "examples": { "application/json": { "Message": "Contract cannot be accessed" }, "application/xml": "\n Contract cannot be accessed\n\n" } }, "404": { "description": "Contract not found", "examples": { "application/json": { "Message": "Contract not found" }, "application/xml": "\n Contract not found\n\n" } } }, "tags": [ "Restart a Contract" ], "summary": "Reactivates the Direct Debit if it is in the ***Expired*** state and payments\nhave already come to an end.\n", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.RestartContract(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"Until further notice\", \"Switch to further notice\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.restart_contract(\n '42217d45-cf22-4430-ab02-acc1f8a2d020',\n 'Until further notice', 'Switch to further notice'\n)\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.restartContract().contract(\"1802e1dd-a657-428c-b8d0-ba162fc76203\").terminationType(\"Until further notice\").atTheEnd(\"Switch to further notice\").query();\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/restart?terminationType=Until further notice&atTheEnd=Switch to further notice' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/weekly": { "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The new day on which payments are to be taken. Must be passed as an integer: Payments will be collected on the next available instance of the payment\nday, which will be a **minimum** of 5 working days in the future. Any\npayment already scheduled in the next 5 working days will still be\ncollected.\n", "in": "query", "name": "day", "required": true, "type": "number", "minimum": 1, "maximum": 5 }, { "description": "A comment to explain the reason for the change of day.", "in": "query", "maxLength": 255, "name": "comment", "required": true, "type": "string" }, { "description": "If you wish to take the next payment to be a different amount (e.g.\npro rata because the number of days between payments will deb different)\nthen pass the amount using this parameter. Ensure that `patchNextPayment`\nis set to `true` if you are using this.\n", "in": "query", "multipleOf": 0.01, "name": "nextPaymentPatchAmount", "type": "number" }, { "description": "Set to `true` if using `nextPaymentPatchAmount` or `false` if not.\n", "in": "query", "name": "patchNextPayment", "required": true, "type": "boolean" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract updated" }, "application/xml": "\n Contract updated\n\n" } }, "400": { "description": "Bad request - invalid day", "examples": { "application/json": { "Message": "Day is invalid for this contract" }, "application/xml": "\n Day is invalid for this contract\n\n" } } }, "tags": [ "Contract Amendment" ], "description": "Amends an existing contract payment date in the database.", "summary": "Changing the Day (Weekly Schedules)", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.ContractDayWeekly(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"5\", \"Change to Friday\", false);\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.patch.contract_day_weekly('36bb4f4f-9a7f-4ead-82dc-9295c6fb9e8b', 5,\n'Change to Friday', False)\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Patch patch = new Patch(settings);\nString request = patch.contractDayWeekly(\"1802e1dd-a657-428c-b8d0-ba162fc76203\", \"5\", \"Change to Friday\", false);\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/weekly?day=5&comment=Change to Friday&patchNextPayment=false' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/customer": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The number of customer records to return per page.\nIf this parameter is omitted or `0` is passed in, no pagination will be used.\n", "in": "query", "name": "pageSize", "type": "number" }, { "description": "The current page of results you wish to view.", "in": "query", "name": "pageNumber", "type": "number" }, { "description": "Default is `false`.\nIf `true`, adds extra JSON metadata in the response to help callers using pagination.\n", "in": "query", "name": "includePagingDetail", "type": "boolean" }, { "description": "Default is `true`.\nIf `true`, includes an array of `Memos` for each customer record returned.\nIf `false`, `Memos` will return `null` for every customer.\n", "in": "query", "name": "includeMemos", "type": "boolean" }, { "description": "The customer’s contact email address.", "in": "query", "maxLength": 200, "name": "email", "type": "string" }, { "description": "The customer’s title (Mr/Mrs/Ms/Miss/Mx etc).", "in": "query", "maxLength": 200, "name": "title", "type": "string" }, { "description": "The date/time from which you want to find new customers added.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "from", "type": "string" }, { "description": "The date/time to which you want to find new customers added.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "to", "type": "string" }, { "description": "The customer’s date of birth.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "dateOfBirth", "type": "string" }, { "description": "A **unique** reference number allocated by the client for this customer.", "in": "query", "maxLength": 200, "name": "customerRef", "type": "string" }, { "description": "The customer's first name.", "in": "query", "maxLength": 200, "name": "firstName", "type": "string" }, { "description": "The customer's surname.", "in": "query", "maxLength": 200, "name": "surname", "type": "string" }, { "description": "The company name of the customer (if applicable).", "in": "query", "maxLength": 200, "name": "companyName", "type": "string" }, { "description": "The customer's Post Code.", "in": "query", "maxLength": 10, "name": "postCode", "type": "string" }, { "description": "The customer's bank account number.\nThis must be eight numerical characters with all leading zeros left intact.\nExamples include: `01065284`, `00000000`, `26280464`.\nAny non-numerical characters **must be removed** before passing the data to the API.\n", "in": "query", "maxLength": 8, "minLength": 8, "name": "accountNumber", "pattern": "[0-9]{8}", "type": "string" }, { "description": "The customer's bank sort code.\nThis must be six numerical characters with all leading zeros left intact.\nExamples include: `089286` `100000` `600000`, `230580`.\nIn the United Kingdom it is sometimes customary to insert dashes/hyphens\nbetween groups of two characters (e.g. `08-92-86`, `23-05-80`). Any hyphens,\ndashes or non-numerical characters **must be removed** before being passed\nto the API.\n", "in": "query", "maxLength": 6, "minLength": 6, "name": "bankSortCode", "pattern": "[0-9]{6}", "type": "string" }, { "description": "The name of the customer's bank account.\nThis must be a maximum of eighteen alphanumeric characters `[0-9a-zA-Z ]`.\nA space is also allowed. Any special characters or punctuation such as ampersands,\napostrophes, hyphens, slashes, backslashes, commas, full stops etc. **must be\nremoved** before passing to the API.\n", "in": "query", "maxLength": 18, "name": "accountHolderName", "pattern": "[0-9a-zA-Z ]{0, 18}", "type": "string" }, { "description": "The customer's home telephone number.", "in": "query", "maxLength": 200, "name": "homePhoneNumber", "type": "string" }, { "description": "The customer's work telephone number.", "in": "query", "maxLength": 200, "name": "workPhoneNumber", "type": "string" }, { "description": "The customer's mobile telephone number.", "in": "query", "maxLength": 200, "name": "mobilePhoneNumber", "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "AddressDetail": { "Line1": "1 Tebbit Mews", "Line2": "Winchcombe Street", "Line3": "Cheltenham", "PostCode": "A1 1AA" }, "BankDetail": { "AccountHolderName": "Access Paysuite", "AccountNumber": "01065285", "BankSortCode": "309906" }, "CompanyName": "Access Paysuite", "CustomerRef": "AE102890", "DateAdded\"": "2017-04-12T13:22:48.800Z", "DateOfBirth": "2017-01-01T00:00:00.000Z", "Email": "spam@eazycollect.co.uk", "FirstName": "Matthew", "HomePhoneNumber": "01234567890", "Id": "c36ce83c-0064-4c1e-a157-cd4c70decf47", "IsArchived": true, "Memos": [], "Surname": "Harris", "Title": "Mr" }, "application/xml": "\n c36ce83c-0064-4c1e-a157-cd4c70decf47\n AE102890\n true\n 2017-04-12T13:22:48.8\n Mr\n Matthew\n Harris\n Access Paysuite\n 2017-01-01T00:00:00\n 01234567890\n spam@eazycollect.co.uk\n \n 1 Tebbit Mews\n Winchcombe Street\n Cheltenham\n A1 1AA\n \n \n Access Paysuite\n 01065285\n 309906\n \n \n" }, "schema": { "properties": { "Customers": { "description": "Array of Customers matching the search criteria.", "type": "array", "items": { "$ref": "#/definitions/Customer" } }, "Metadata": { "description": "Object of metadata useful for clients using pagination.\nOnly included if `includePagingDetail=true`\n", "type": "object", "$ref": "#/definitions/PagingMetadata" } } } }, "404": { "description": "Customer not found", "examples": { "application/json": { "Message": "API not enabled" }, "application/xml": "API\n not enabled7" } } }, "tags": [ "Customer Manipulation" ], "description": "**NOTE:** The response from a GET method includes an `IsArchived` flag.\nOn a newly created customer, this will show as `true` which is normal.\nThe record will automatically change to `false` when an associated live\nDirect Debit (contract) is attached to it.\n", "summary": "Queries the database for a set of customers.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.Customers();\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.customers()\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get(settings);\nString response = get.customers();\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer' -H 'apiKey: {apiKey}'\n" } ] }, "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The customer’s contact email address.\nBy default this field is required, but this can be disabled at your request.\nThe `CustomerEmailMandatory` field in the Client Info response shows whether this field\nis mandatory.\n", "in": "query", "maxLength": 200, "name": "email", "required": false, "type": "string" }, { "description": "The customer’s title (Mr/Mrs/Ms/Miss/Mx etc).", "in": "query", "maxLength": 200, "name": "title", "required": true, "type": "string" }, { "description": "The customer’s date of birth.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "dateOfBirth", "type": "string" }, { "description": "A **unique** reference number allocated by the client for this customer.", "in": "query", "maxLength": 200, "name": "customerRef", "required": true, "type": "string" }, { "description": "The customer's first name.", "in": "query", "maxLength": 200, "name": "firstName", "required": false, "type": "string" }, { "description": "The customer's surname.", "in": "query", "maxLength": 200, "name": "surname", "required": true, "type": "string" }, { "description": "The company name of the customer (if applicable).", "in": "query", "maxLength": 200, "name": "companyName", "type": "string" }, { "description": "The customer's Post Code.", "in": "query", "maxLength": 10, "name": "postCode", "required": true, "type": "string" }, { "description": "The customer's bank account number.\nThis must be eight numerical characters with all leading zeros left intact.\nExamples include: `01065284`, `00000000`, `26280464`.\nAny non-numerical characters **must be removed** before passing the data to the API.\n", "in": "query", "maxLength": 8, "minLength": 8, "name": "accountNumber", "pattern": "[0-9]{8}", "required": true, "type": "string" }, { "description": "The customer's bank sort code.\nThis must be six numerical characters with all leading zeros left intact.\nExamples include: `089286` `100000` `600000`, `230580`.\nIn the United Kingdom it is sometimes customary to insert dashes/hyphens\nbetween groups of two characters (e.g. `08-92-86`, `23-05-80`). Any hyphens,\ndashes or non-numerical characters **must be removed** before being passed\nto the API.\n", "in": "query", "maxLength": 6, "minLength": 6, "name": "bankSortCode", "pattern": "[0-9]{6}", "required": true, "type": "string" }, { "description": "The name of the customer's bank account.\nThis must be a maximum of eighteen alphanumeric characters `[0-9a-zA-Z ]`.\nA space is also allowed. Any special characters or punctuation such as ampersands,\napostrophes, hyphens, slashes, backslashes, commas, full stops etc. **must be\nremoved** before passing to the API.\n", "in": "query", "maxLength": 18, "name": "accountHolderName", "pattern": "[0-9a-zA-Z ]{0, 18}", "required": true, "type": "string" }, { "description": "The customer's home telephone number.", "in": "query", "maxLength": 200, "name": "homePhoneNumber", "type": "string" }, { "description": "The customer's work telephone number.", "in": "query", "maxLength": 200, "name": "workPhoneNumber", "type": "string" }, { "description": "The customer's mobile telephone number.", "in": "query", "maxLength": 200, "name": "mobilePhoneNumber", "type": "string" }, { "description": "Line one of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line1", "required": true, "type": "string" }, { "description": "Line two of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line2", "required": true, "type": "string" }, { "description": "Line three of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line3", "type": "string" }, { "description": "Line four of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line4", "type": "string" }, { "description": "If the customer has provided any middle initials, they can be added in this field.", "in": "query", "maxLength": 200, "name": "initials", "type": "string" }, { "description": "Set the language of communications sent to this customer to English (`en-GB`) or Welsh (`cy-GB`).\nIf omitted, this defaults to English.\nIf Welsh support is not enabled for your organisation, submitting `cy-GB` returns a 400 error with the message: **\"Welsh language not enabled for this client\"**.", "in": "query", "maxLength": 5, "name": "customerLocale", "type": "string", "enum": [ "en-GB", "cy-GB" ] }, { "description": "Example JSON/XML payload.", "in": "body", "name": "body", "schema": { "example": { "Email": "john.doe@test.com", "Title": "Mr", "CustomerRef": "999999", "FirstName": "John", "Surname": "Doe", "Line1": "1 Tebbit Mews", "Line2": "Winchcombe Street", "PostCode": "GL52 2NF", "AccountNumber": "12345678", "BankSortCode": "123456", "AccountHolderName": "Mr John Doe" }, "xml": { "name": "CustomerRequestDto" }, "type": "object" } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "CustomerRef": "AE102888", "Id": "12f5734a-bfc3-45f2-9edd-44d4a05cf751" }, "application/xml": "\n AE102889\n a1d86a0a-6806-408b-b5ce-1fae797cc142\n\n" }, "schema": { "properties": { "Id": { "description": "The GUID of the customer record. You must save this to your database\nas it will be needed should you wish to update the customer record\nor create a Direct Debit (Contract).\n", "type": "string" }, "customerRef": { "description": "The customer reference that you passed via the API into the system.\n", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad request - email mandatory", "examples": { "application/json": { "ErrorCode": 2, "Message": "Customer email is mandatory for this client" }, "application/xml": "\n 2\n Customer email is mandatory for this client\n\n" }, "schema": { "properties": { "Message": { "description": "If there are any problems with the record, these will be shown in\nthe message field.\n", "type": "string" } } } } }, "tags": [ "Customer Manipulation" ], "description": "### Error Handling\nErrors are presented back in the JSON or XML response in human readable\nform.\n**Common Errors:**\n*Error:*\n“There is an existing Customer with the same Client and Customer ref in\nthe database already.”\n*Explanation:*\nThe customer reference must be unique; this indicates that a customer\nwith the customerRef provided in the API call already exists\n*Resolution:*\nCheck that the customer does not already exist; if not, you must use\nanother unique customerRef.\n*Error:*\nInvalid Postcode. The postcode must have 5, 6 or 7 characters only\n*Explanation:*\nThe postcode supplied is not in a correct UK format.\n*Resolution:*\nUK postcodes can be formed in the following ways:\n- A99 9AA\n- AA99 9AA\n- AA9A 9AA\nWhere A is a capital letter \\[A-Z\\] and 9 is a number \\[0-9\\]. Please\nprovide the postcode in one of the recognised formats.\n", "summary": "Creates a customer in the database.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.Customer(\"john.doe@test.com\", \"Mr\", \"999999\", \"John\", \"Doe\", \"1 Tebbit Mews\", \"GL52 2NF\", \"12345678\", \"123456\", \"Mr John Doe\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.customer(email=\"john.doe@test.com\", title=\"Mr\", customer_reference=\"999999\", first_name=\"John\", surname=\"Doe\", line1=\"1 Tebbit Mews\", post_code=\"GL52 2NF\", account_number=\"12345678\", sort_code=\"123456\", account_holder_name=\"Mr John Doe\")\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.customer().email(\"john.doe@test.com\").title(\"Mr\").customerReference(\"999999\")\n .firstName(\"John\").surname(\"Doe\").line1(\"1 Tebbit Mews\").postCode(\"GL52 2NF\").accountNumber(\"12345678\")\n .sortCode(\"123456\").accountHolderName(\"Mr John Doe\").query();\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer?email=john.doe@test.com&title=Mr&customerRef=999999&firstName=John&surname=Doe&line1=1 Tebbit Mews&postCode=GL52 2NF&accountNumber=12345678&bankSortCode=123456&accountHolderName=Mr John Doe' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/customer/{customerId}": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The GUID of the customer.", "in": "path", "name": "customerId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "AddressDetail": { "Line1": "1 Tebbit Mews", "Line2": "Winchcombe Street", "Line3": "Cheltenham", "PostCode": "A1 1AA" }, "BankDetail": { "AccountHolderName": "Access Paysuite", "AccountNumber": "01065285", "BankSortCode": "309906" }, "CompanyName": "Access Paysuite", "CustomerRef": "AE102890", "DateAdded\"": "2017-04-12T13:22:48.800Z", "DateOfBirth": "2017-01-01T00:00:00.000Z", "Email": "spam@eazycollect.co.uk", "FirstName": "Matthew", "HomePhoneNumber": "01234567890", "Id": "c36ce83c-0064-4c1e-a157-cd4c70decf47", "IsArchived": true, "Memos": [], "Surname": "Harris", "Title": "Mr" }, "application/xml": "\n c36ce83c-0064-4c1e-a157-cd4c70decf47\n AE102890\n true\n 2017-04-12T13:22:48.8\n Mr\n Matthew\n Harris\n Access Paysuite\n 2017-01-01T00:00:00\n 01234567890\n spam@eazycollect.co.uk\n \n 1 Tebbit Mews\n Winchcombe Street\n Cheltenham\n A1 1AA\n \n \n Access Paysuite\n 01065285\n 309906\n \n \n" }, "schema": { "$ref": "#/definitions/Customer" } }, "404": { "description": "Customer not found", "examples": { "application/json": { "Message": "API not enabled" }, "application/xml": "API\n not enabled7" } } }, "tags": [ "Customer Manipulation" ], "description": "**NOTE:** The response from a GET method includes an `IsArchived` flag.\nOn a newly created customer, this will show as `true` which is normal.\nThe record will automatically change to `false` when an associated live\nDirect Debit (contract) is attached to it.\n", "summary": "Queries the database for a single customer by ID.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.Customers();\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.customers()\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get(settings);\nString response = get.customers();\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/c36ce83c-0064-4c1e-a157-cd4c70decf47' -H 'apiKey: {apiKey}'\n" } ] }, "patch": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The GUID of the customer.", "in": "path", "name": "customerId", "required": true, "type": "string" }, { "description": "The customer’s contact email address.", "in": "query", "maxLength": 200, "name": "email", "required": false, "type": "string" }, { "description": "The customer’s title (Mr/Mrs/Ms/Miss/Mx etc).", "in": "query", "maxLength": 200, "name": "title", "required": false, "type": "string" }, { "description": "The customer’s date of birth.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "dateOfBirth", "type": "string" }, { "description": "A **unique** reference number allocated by the client for this customer.", "in": "query", "maxLength": 200, "name": "customerRef", "required": false, "type": "string" }, { "description": "The customer's first name.", "in": "query", "maxLength": 200, "name": "firstName", "required": false, "type": "string" }, { "description": "The customer's surname.", "in": "query", "maxLength": 200, "name": "surname", "required": false, "type": "string" }, { "description": "The company name of the customer (if applicable).", "in": "query", "maxLength": 200, "name": "companyName", "type": "string" }, { "description": "The customer's Post Code.", "in": "query", "maxLength": 10, "name": "postCode", "required": false, "type": "string" }, { "description": "The customer's bank account number.\nThis must be eight numerical characters with all leading zeros left intact.\nExamples include: `01065284`, `00000000`, `26280464`.\nAny non-numerical characters **must be removed** before passing the data to the API.\n", "in": "query", "maxLength": 8, "minLength": 8, "name": "accountNumber", "pattern": "[0-9]{8}", "required": false, "type": "string" }, { "description": "The customer's bank sort code.\nThis must be six numerical characters with all leading zeros left intact.\nExamples include: `089286` `100000` `600000`, `230580`.\nIn the United Kingdom it is sometimes customary to insert dashes/hyphens\nbetween groups of two characters (e.g. `08-92-86`, `23-05-80`). Any hyphens,\ndashes or non-numerical characters **must be removed** before being passed\nto the API.\n", "in": "query", "maxLength": 6, "minLength": 6, "name": "bankSortCode", "pattern": "[0-9]{6}", "required": false, "type": "string" }, { "description": "The name of the customer's bank account.\nThis must be a maximum of eighteen alphanumeric characters `[0-9a-zA-Z ]`.\nA space is also allowed. Any special characters or punctuation such as ampersands,\napostrophes, hyphens, slashes, backslashes, commas, full stops etc. **must be\nremoved** before passing to the API.\n", "in": "query", "maxLength": 18, "name": "accountHolderName", "pattern": "[0-9a-zA-Z ]{0, 18}", "required": false, "type": "string" }, { "description": "The customer's home telephone number.", "in": "query", "maxLength": 200, "name": "homePhoneNumber", "type": "string" }, { "description": "The customer's work telephone number.", "in": "query", "maxLength": 200, "name": "workPhoneNumber", "type": "string" }, { "description": "The customer's mobile telephone number.", "in": "query", "maxLength": 200, "name": "mobilePhoneNumber", "type": "string" }, { "description": "Line one of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line1", "required": false, "type": "string" }, { "description": "Line two of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line2", "required": false, "type": "string" }, { "description": "Line three of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line3", "type": "string" }, { "description": "Line four of the customer's postal address.", "in": "query", "maxLength": 200, "name": "line4", "type": "string" }, { "description": "If the customer has provided any middle initials, they can be added in this field.", "in": "query", "maxLength": 200, "name": "initials", "type": "string" }, { "description": "Set the language of communications sent to this customer to English (`en-GB`) or Welsh (`cy-GB`).\nIf omitted, this defaults to English.\nIf Welsh support is not enabled for your organisation, submitting `cy-GB` returns a 400 error with the message: **\"Welsh language not enabled for this client\"**.", "in": "query", "maxLength": 5, "name": "customerLocale", "type": "string", "enum": [ "en-GB", "cy-GB" ] } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Customer updated" }, "application/xml": "\n Customer updated\n\n" }, "schema": { "properties": { "Message": { "type": "string" } }, "type": "object" } } }, "tags": [ "Customer Manipulation" ], "description": "### Error Handling\nErrors are presented back in the JSON or XML response in human readable\nform.\n**Common Errors:**\n*Error:*\n“There is an existing Customer with the same Client and Customer ref in\nthe database already.”\n*Explanation:*\nThe customer reference must be unique; this indicates that a customer\nwith the customerRef provided in the API call already exists\n*Resolution:*\nCheck that the customer does not already exist; if not, you must use\nanother unique customerRef.\n*Error:*\nInvalid Postcode. The postcode must have 5, 6 or 7 characters only\n*Explanation:*\nThe postcode supplied is not in a correct UK format.\n*Resolution:*\nUK postcodes can be formed in the following ways:\n- A99 9AA\n- AA99 9AA\n- AA9A 9AA\nWhere A is a capital letter \\[A-Z\\] and 9 is a number \\[0-9\\]. Please\nprovide the postcode in one of the recognised formats.\n", "summary": "Updates (or partially updates) an existing customer in the database.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var patch = new Patch(settings);\nstring request = patch.Customer(\"dfca6da1-2490-4607-a256-c5799d2584e9\", Email: \"john.doe@test.com\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.patch.customer(\"dfca6da1-2490-4607-a256-c5799d2584e9\", email=\"john.doe@test.com\")\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post patch = new Patch(settings);\nString request = patch.customer(\"dfca6da1-2490-4607-a256-c5799d2584e9\").email(\"john.doe@test.com\").query();\n" }, { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/dfca6da1-2490-4607-a256-c5799d2584e9?email=john.doe@test.com' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/customer/{customerId}/edit": { "patch": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The GUID of the customer.", "format": "guid", "in": "path", "name": "customerId", "required": true, "type": "string" }, { "description": "The customer fields to update. Send only the fields you want to change.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/UpdateCustomerJsonRequest" } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Customer updated" } }, "schema": { "properties": { "Message": { "type": "string" } }, "type": "object" } } }, "tags": [ "Customer Manipulation" ], "description": "Updates, or partially updates, an existing customer record by sending a JSON body. Send only the fields you want to change.", "summary": "Updates an existing customer using a JSON request body.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/dfca6da1-2490-4607-a256-c5799d2584e9/edit' -H 'Content-Type: application/json' -H 'apiKey: {apiKey}' -d '{\"Email\":\"john.doe@test.com\",\"FirstName\":\"John\",\"Surname\":\"Doe\"}'\n" } ] } }, "/client/{clientCode}/question": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Label for the question.", "in": "query", "maxLength": 500, "name": "label", "required": true, "type": "string" }, { "description": "Data type for answers to this question.", "in": "query", "enum": [ "text", "list", "date" ], "name": "type", "required": true, "type": "string" }, { "description": "Comma-separated list of possible answers for this question. Can only be used when type is `list`.", "in": "query", "name": "options", "required": false, "type": "string", "pattern": "[A-Za-z0-9,]+", "maxLength": 800 }, { "description": "A custom tag that can be assigned to this question. This tag does *not* need to be unique.", "in": "query", "name": "tags", "required": false, "type": "string", "maxLength": 200 }, { "description": "Whether or not an answer is required for this question.", "in": "query", "name": "isMandatory", "required": true, "type": "boolean" }, { "description": "Example JSON payload.", "in": "body", "name": "body", "schema": { "example": { "label": "Would you like us to send you offers by email?", "type": "list", "options": "Yes,No", "isMandatory": false } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Id": "e45afe74-0217-43e1-8afc-0f60b887c691", "Message": "Client custom question was added successfully" } }, "schema": { "properties": { "Id": { "description": "The GUID of the question. You must save this to your database as it will be needed when you add an answer.\n", "type": "string" }, "Message": { "description": "Success message.\n", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad request - options not provided for `list` question", "examples": { "application/json": { "ErrorCode": 3, "Detail": "Please provide Options for the selected Type.", "Message": "Validation error" } } } }, "summary": "Creates a new question.", "tags": [ "Customer Questions" ] } }, "/client/{clientCode}/question/{questionId}": { "patch": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The ID of the question to update.", "in": "path", "name": "questionId", "required": true, "type": "string", "format": "guid" }, { "description": "Label for the question.", "in": "query", "maxLength": 500, "name": "label", "required": false, "type": "string" }, { "description": "Data type for answers to this question.", "in": "query", "enum": [ "text", "list", "date" ], "name": "type", "required": false, "type": "string" }, { "description": "Comma-separated list of possible answers for this question. Can only be used when type is `list`.", "in": "query", "name": "options", "required": false, "type": "string", "pattern": "[A-Za-z0-9,]+", "maxLength": 800 }, { "description": "Whether or not an answer is required for this question.", "in": "query", "name": "isMandatory", "required": false, "type": "boolean" }, { "description": "Example JSON payload.", "in": "body", "name": "body", "schema": { "example": { "label": "Would you like us to send you offers by email?", "type": "list", "options": "Yes,No", "isMandatory": false } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Client custom question updated" } }, "schema": { "properties": { "Id": { "description": "The GUID of the question. You must save this to your database as it will be needed when you add an answer.\n", "type": "string" }, "Message": { "description": "Success message.\n", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad request - options not provided for `list` question", "examples": { "application/json": { "ErrorCode": 3, "Detail": "Please provide Options for the selected Type.", "Message": "Validation error" } } } }, "summary": "Updates an existing question.", "tags": [ "Customer Questions" ] } }, "/client/{clientCode}/questions": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Questions": [ { "Id": "3836f9ea-bf95-495b-a87b-76012056ab3d", "Label": "Enter your pet's name:", "Type": "Text", "Options": [ "" ], "Tags": "pet-appeal", "IsMandatory": false }, { "Id": "dec0153e-7e75-4666-9b90-08efb48cea0b", "Label": "Would you like us to send you offers by email?", "Type": "List", "Options": [ "Yes", "No" ], "Tags": null, "IsMandatory": false } ] } }, "schema": { "properties": { "Questions": { "description": "Array of Questions.", "type": "array", "items": { "$ref": "#/definitions/Question" } } }, "type": "object" } } }, "summary": "Lists all questions created for the client.", "tags": [ "Customer Questions" ] } }, "/client/{clientCode}/customer/{customerId}/question/{questionId}/answer": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Customer to assign the answer to.", "in": "path", "name": "customerId", "required": true, "type": "string", "format": "guid" }, { "description": "Question the answer relates to.", "in": "path", "name": "questionId", "required": true, "type": "string", "format": "guid" }, { "description": "The answer to add.", "in": "query", "required": true, "name": "value", "type": "string", "maxLength": 500 } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Customer Answer added" } } }, "400": { "description": "Bad request - answer exists", "examples": { "application/json": { "ErrorCode": 3, "Detail": "There is an existing Customer answer with the same Customer and Question in the database already.", "Message": "Validation error" } } } }, "summary": "Adds an answer for a customer.", "tags": [ "Customer Questions" ] }, "patch": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Customer to assign the answer to.", "in": "path", "name": "customerId", "required": true, "type": "string", "format": "guid" }, { "description": "Question the answer relates to.", "in": "path", "name": "questionId", "required": true, "type": "string", "format": "guid" }, { "description": "The answer to add.", "in": "query", "required": true, "name": "value", "type": "string", "maxLength": 500 } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Customer Answer updated" } } }, "400": { "description": "Bad request - answer not in Options", "examples": { "application/json": { "ErrorCode": 3, "Detail": "Please provide a valid response to this question. Possible responses are Yes,No", "Message": "Validation error" } } }, "404": { "description": "Answer not found", "examples": { "application/json": { "ErrorCode": 9, "Detail": null, "Message": "Customer Answer not found" } } } }, "summary": "Updates an existing customer answer.", "tags": [ "Customer Questions" ] }, "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Customer to assign the answer to.", "in": "path", "name": "customerId", "required": true, "type": "string", "format": "guid" }, { "description": "Question the answer relates to.", "in": "path", "name": "questionId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Customer Answer deleted" } } }, "404": { "description": "Answer not found", "examples": { "application/json": { "ErrorCode": 9, "Detail": null, "Message": "Customer Answer not found" } } } }, "summary": "Deletes an existing customer answer.", "tags": [ "Customer Questions" ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "Customer to assign the answer to.", "in": "path", "name": "customerId", "required": true, "type": "string", "format": "guid" }, { "description": "Question the answer relates to.", "in": "path", "name": "questionId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Answer" }, "examples": { "application/json": { "Id": "37c1def5-e9e5-4be4-bd6a-bc8fb5f0cbc2", "Product": null, "Customer": "66e88855-a07e-40d8-aff6-1fa7ace4dd1d", "CustomQuestion": "ba8a6aef-756f-4945-b846-f8adaafb69df", "Answer": "Yes" } } }, "404": { "description": "Answer not found", "examples": { "application/json": { "ErrorCode": 9, "Detail": null, "Message": "Customer Answer not found" } } } }, "summary": "Gets the answer for a particular customer and question.", "tags": [ "Customer Questions" ] } }, "/client/{clientCode}/paymentdate": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "NextFirstPaymentDate": "2022-08-22T00:00:00+01:00", "NextSubsequentPaymentDate": "2022-08-19T00:00:00+01:00" } }, "schema": { "properties": { "NextFirstPaymentDate": { "description": "The earliest contract start/first collection date currently allowed by your SUN.", "type": "string", "format": "datetime" }, "NextSubsequentPaymentDate": { "description": "The earliest adhoc payment date for active contracts after first collection currently allowed by your SUN.", "type": "string", "format": "datetime" } }, "type": "object" } } }, "tags": [ "Payment Dates" ], "summary": "Gets the earliest first and subsequent payment dates currently allowed.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/paymentdate' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/futureSchedules": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to query.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "StreamVersions": [ { "Id": "e4dda449-4bf3-44fc-b8a6-29b3f90576f7", "Status": "Future version", "IsPatch": false, "StartDate": "2026-06-11T00:00:00", "Frequency": "Monthly", "Every": 1, "PaymentDayInWeek": null, "PaymentDayInMonth": 2, "PaymentMonthInYear": null, "InitialDate": null, "InitialAmount": 1, "RegistrationFee": null, "ExtraInitialAmounts": "1", "Amount": 1, "FinalAmount": 1, "IsGiftAid": false, "TerminationType": "End on exact date", "TerminationDate": "2030-06-15T00:00:00", "NumberOfDebits": null } ], "SearchInput": null, "TotalExpectedResults": 1 } }, "schema": { "properties": { "StreamVersions": { "description": "Array of stream versions.", "type": "array", "items": { "$ref": "#/definitions/StreamVersion" } }, "SearchInput": { "description": "Search input.", "type": "object" }, "TotalExpectedResults": { "description": "Total expected results.", "type": "integer" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } } }, "tags": [ "Frequency Switching" ], "summary": "Retrieves all future schedules (stream versions) for a given contract and stream.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/futureSchedules' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/schedule": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to query.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" }, { "description": "The StreamVersion (schedule) GUID that you wish to query.", "in": "query", "name": "versionId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "StreamVersion": { "Id": "c036d70c-6578-4608-acd2-78511acc02f0", "Status": "Active version", "IsPatch": false, "StartDate": "2025-01-15T00:00:00", "Frequency": "Annually", "Every": 1, "PaymentDayInWeek": null, "PaymentDayInMonth": 15, "PaymentMonthInYear": null, "InitialDate": null, "InitialAmount": null, "RegistrationFee": null, "ExtraInitialAmounts": null, "Amount": 400, "FinalAmount": null, "IsGiftAid": false, "TerminationType": "End on exact date", "TerminationDate": "2025-05-01T00:00:00", "NumberOfDebits": null }, "SearchInput": null, "TotalExpectedResults": 1 } }, "schema": { "properties": { "StreamVersion": { "$ref": "#/definitions/StreamVersion" }, "SearchInput": { "description": "Search input.", "type": "object" }, "TotalExpectedResults": { "description": "Total expected results.", "type": "integer" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } } }, "tags": [ "Frequency Switching" ], "summary": "Retrieves details of a specific contract stream version (schedule).", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/schedule?versionId={versionId}' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/deleteSchedule/{futureScheduleId}": { "delete": { "produces": [ "text" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the future schedule has been applied to.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" }, { "description": "The StreamVersion (schedule) GUID that you wish to delete.", "in": "path", "name": "futureScheduleId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "text": "Schedule successfully deleted." } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } } }, "tags": [ "Frequency Switching" ], "summary": "Deletes a future contract schedule (stream version) by its ID.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X DELETE 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/deleteSchedule/{futureScheduleId}' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/editSchedule/{futureScheduleId}": { "patch": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to amend.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" }, { "description": "The StreamVersion (schedule) GUID that you wish to amend.", "in": "path", "name": "futureScheduleId", "required": true, "type": "string", "format": "guid" }, { "description": "Effective date of change.", "in": "query", "name": "startDate", "required": true, "type": "string", "format": "datetime" }, { "description": "Schedule ID from available schedules.", "in": "query", "name": "scheduleId", "required": false, "type": "string", "format": "guid" }, { "description": "Schedule name from available schedules.", "in": "query", "name": "scheduleName", "required": false, "type": "string" }, { "description": "If the schedule is set to take regular payments, this parameter allows you to skip periods (e.g. every 2 months, every 4 weeks etc). This field is only mandatory if the schedule is not an ad-hoc schedule.", "in": "query", "name": "every", "required": false, "type": "integer" }, { "description": "If the schedule is for regular payments, then the day on which you wish\nthe first payment should be passed with this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **annual** or **monthly**.\n**NOTE:** You may only select:\n - days **1** to **28**\n - **98**, which represents `Last working day of the Month`\n - **99**, which represents `Last day of the Month`\nequal with value 99.\n*You may not* select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.\n", "in": "query", "name": "paymentDayInMonth", "required": false, "type": "integer" }, { "description": "1 -> Monday \n2 -> Tuesday \n3 -> Wednesday \n4 -> Thursday \n5 -> Friday\nIf the schedule is for regular payments and has a weekly frequency, pass the\nday of the week that you wish payments to be collected via this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **weekly**.\n", "in": "query", "name": "paymentDayInWeek", "required": false, "type": "integer" }, { "description": "If the schedule is for regular payments then the month in which you\nwish the first payment should be passed with this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **annual** or **monthly**.\n", "in": "query", "name": "paymentMonthInYear", "required": false, "type": "integer" }, { "description": "Different first payment date.", "in": "query", "name": "initialDate", "required": false, "type": "string", "format": "datetime" }, { "description": "If this is a schedule for regular payments **and** the first payment is\ndifferent to the regular payments, then pass the first payment amount\nwith this parameter.\n**Do not** pass this parameter with ad-hoc schedule, or where the first\namount is the same as the regular amount.\n", "in": "query", "name": "initialAmount", "required": false, "type": "number", "format": "decimal" }, { "description": "If there are extra charges to be collected with the first payment\n(e.g. a gym joining fee/registration fee) then these can be added\nseparately with this parameter. Do not pass the parameter if there\nare no extra amounts, and this must not be used if the schedule is\nan ad-hoc payment schedule.\n", "in": "query", "name": "extraInitialAmounts", "required": false, "type": "string" }, { "description": "If the schedule is for regular payments, then the regular payment\namount should be passed using this parameter. Do not pass this\nparameter if the schedule is an ad-hoc schedule.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\n", "in": "query", "name": "amount", "required": false, "type": "number", "format": "decimal" }, { "description": "If this is a schedule for regular payments **and** the final payment is\ndifferent to the regular payments, then pass the final payment amount\nwith this parameter. **Do not** pass this parameter with ad-hoc\nschedules, or where the final amount is the same as the regular amount.\n", "in": "query", "name": "finalAmount", "required": false, "type": "number", "format": "decimal" }, { "description": "Pass the way in which the schedule should end using this parameter.\nIf the schedule is **ad-hoc,** *you must* pass `Until further notice`.\n", "enum": [ "Take certain number of debits", "Until further notice", "End on exact date" ], "in": "query", "name": "terminationType", "required": false, "type": "string" }, { "description": "If the `terminationType` is `End on Exact Date` then the termination date\nshould be passed using this.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "in": "query", "name": "terminationDate", "required": false, "type": "string", "format": "datetime" }, { "description": "If this is a “Take certain Number of Debits” schedule then the number of\ndebits to be taken should be passed using this parameter.\nThis field is only mandatory if the termination type is “Take Certain\nNumber of Debits”.\n", "in": "query", "name": "numberOfPayments", "required": false, "type": "integer" }, { "description": "Pass true if the payments to be collected are to be subject to a gift aid\nclaim, false if not (pass false if the client is not a charity).\n", "in": "query", "name": "isGiftAid", "required": false, "type": "boolean" }, { "description": "Example JSON payload.", "in": "body", "name": "body", "schema": { "example": { "StartDate": "2025-07-01T00:00:00Z", "ScheduleId": "guid-value", "ScheduleName": "string", "Every": 1, "PaymentDayInMonth": 1, "PaymentDayInWeek": 1, "PaymentMonthInWeek": 1, "InitialDate": "2025-07-01T00:00:00Z", "InitialAmount": 100, "ExtraInitialAmounts": "string", "Amount": 50, "FinalAmount": 0, "TerminationType": "string", "TerminationDate": "2026-07-01T00:00:00Z", "NumberOfPayments": 12, "IsGiftAid": false } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract schedule was edited successfully." } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } } }, "tags": [ "Frequency Switching" ], "summary": "Edits an existing future contract schedule.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/editSchedule/{futureScheduleId}?startDate=2025-07-01T00:00:00Z&scheduleId=guid-value&scheduleName=string&every=1&paymentDayInMonth=1&paymentDayInWeek=1&paymentMonthInYear=1&initialDate=2025-07-01T00:00:00Z&initialAmount=100.0&extraInitialAmounts=string&amount=50.0&finalAmount=0.0&terminationType=string&terminationDate=2026-07-01T00:00:00Z&numberOfPayments=12&isGiftAid=false' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/newSchedule": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you wish to add a new future schedule to.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" }, { "description": "Effective date of change.", "in": "query", "name": "startDate", "required": true, "type": "string", "format": "datetime" }, { "description": "Schedule ID from available schedules.", "in": "query", "name": "scheduleId", "required": false, "type": "string", "format": "guid" }, { "description": "Schedule name from available schedules.", "in": "query", "name": "scheduleName", "required": false, "type": "string" }, { "description": "If the schedule is set to take regular payments, this parameter allows you\nto skip periods (e.g. every 2 months, every 4 weeks etc).\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\n", "in": "query", "name": "every", "required": false, "type": "integer" }, { "description": "If the schedule is for regular payments, then the day on which you wish\nthe first payment should be passed with this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **annual** or **monthly**.\n**NOTE:** You may only select:\n - days **1** to **28**\n - **98**, which represents `Last working day of the Month`\n - **99**, which represents `Last day of the Month`\nequal with value 99.\n*You may not* select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.\n", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 98, 99 ], "in": "query", "name": "paymentDayInMonth", "required": false, "type": "integer" }, { "description": "1 -> Monday \n2 -> Tuesday \n3 -> Wednesday \n4 -> Thursday \n5 -> Friday\nIf the schedule is for regular payments and has a weekly frequency, pass the\nday of the week that you wish payments to be collected via this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **weekly**.\n", "in": "query", "name": "paymentDayInWeek", "required": false, "type": "integer" }, { "description": "If the schedule is for regular payments then the month in which you\nwish the first payment should be passed with this parameter.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\nThis field is only mandatory if the schedule is **annual** or **monthly**.\n", "in": "query", "name": "paymentMonthInYear", "required": false, "type": "integer" }, { "description": "Different first payment date.", "in": "query", "name": "initialDate", "required": false, "type": "string", "format": "datetime" }, { "description": "If this is a schedule for regular payments **and** the first payment is\ndifferent to the regular payments, then pass the first payment amount\nwith this parameter.\n**Do not** pass this parameter with ad-hoc schedules, or where the first\namount is the same as the regular amount.\n", "in": "query", "name": "initialAmount", "required": false, "type": "number", "format": "decimal" }, { "description": "If there are extra charges to be collected with the first payment\n(e.g. a gym joining fee/registration fee) then these can be added\nseparately with this parameter. Do not pass the parameter if there\nare no extra amounts, and this must not be used if the schedule is\nan ad-hoc payment schedule.\n", "in": "query", "name": "extraInitialAmounts", "required": false, "type": "string" }, { "description": "If the schedule is for regular payments, then the regular payment\namount should be passed using this parameter. Do not pass this\nparameter if the schedule is an ad-hoc schedule.\nThis field is only mandatory if the schedule is **not** an ad-hoc schedule.\n", "in": "query", "name": "amount", "required": false, "type": "number", "format": "decimal" }, { "description": "If this is a schedule for regular payments **and** the final payment is\ndifferent to the regular payments, then pass the final payment amount\nwith this parameter. **Do not** pass this parameter with ad-hoc\nschedules, or where the final amount is the same as the regular amount.\n", "in": "query", "name": "finalAmount", "required": false, "type": "number", "format": "decimal" }, { "description": "Pass the way in which the schedule should end using this parameter.\nIf the schedule is **ad-hoc,** *you must* pass `Until further notice`.\n", "enum": [ "Take certain number of debits", "Until further notice", "End on exact date" ], "in": "query", "name": "terminationType", "required": false, "type": "string" }, { "description": "If the `terminationType` is `End on Exact Date` then the termination date\nshould be passed using this.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "in": "query", "name": "terminationDate", "required": false, "type": "string", "format": "datetime" }, { "description": "If this is a “Take certain Number of Debits” schedule then the number of\ndebits to be taken should be passed using this parameter.\nThis field is only mandatory if the termination type is “Take Certain\nNumber of Debits”.\n", "in": "query", "maximum": 999, "minimum": 0, "name": "numberOfPayments", "required": false, "type": "integer" }, { "description": "Pass true if the payments to be collected are to be subject to a gift aid\nclaim, false if not (pass false if the client is not a charity).\n", "in": "query", "name": "isGiftAid", "required": false, "type": "boolean" }, { "description": "Example JSON payload.", "in": "body", "name": "body", "schema": { "example": { "StartDate": "2025-07-01T00:00:00Z", "ScheduleId": "guid-value", "ScheduleName": "string", "Every": 1, "PaymentDayInMonth": 1, "PaymentDayInWeek": 1, "PaymentMonthInWeek": 1, "InitialDate": "2025-07-01T00:00:00Z", "InitialAmount": 100, "ExtraInitialAmounts": "string", "Amount": 50, "FinalAmount": 0, "TerminationType": "string", "TerminationDate": "2026-07-01T00:00:00Z", "NumberOfPayments": 12, "IsGiftAid": false } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "NewScheduleId": "guid-value" } }, "schema": { "properties": { "NewScheduleId": { "description": "New schedule ID.", "type": "string", "format": "guid" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } } } } }, "tags": [ "Frequency Switching" ], "summary": "Creates a new future contract schedule.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/editSchedule/{futureScheduleId}?startDate=2025-07-01T00:00:00Z&scheduleId=guid-value&scheduleName=string&every=1&paymentDayInMonth=1&paymentDayInWeek=1&paymentMonthInYear=1&initialDate=2025-07-01T00:00:00Z&initialAmount=100.0&extraInitialAmounts=string&amount=50.0&finalAmount=0.0&terminationType=string&terminationDate=2026-07-01T00:00:00Z&numberOfPayments=12&isGiftAid=false' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/cancelSchedule": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you want to cancel the schedule for.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract schedule was cancelled successfully." } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } }, "403": { "description": "Forbidden", "examples": { "application/json": { "Message": "API not enabled", "ErrorCode": 7, "Detail": "This contract cannot be used in API" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } }, "404": { "description": "Not Found", "examples": { "application/json": { "Message": "Contract not found", "ErrorCode": 0 } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" } }, "type": "object" } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } } }, "tags": [ "Frequency Switching" ], "summary": "Cancels the schedule of a contract.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/cancelSchedule' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/restartSchedule": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID that you want to restart the schedule for.", "in": "path", "name": "contractId", "required": true, "type": "string", "format": "guid" }, { "description": "An optional comment.", "in": "query", "name": "comment", "required": false, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Contract schedule was restarted successfully." } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad Request", "examples": { "application/json": { "Message": "Validation error", "ErrorCode": 3, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } }, "403": { "description": "Forbidden", "examples": { "application/json": { "Message": "API not enabled", "ErrorCode": 7, "Detail": "This contract cannot be used in API" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } }, "404": { "description": "Not Found", "examples": { "application/json": { "Message": "Contract not found", "ErrorCode": 0 } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" } }, "type": "object" } }, "500": { "description": "Internal Server Error", "examples": { "application/json": { "Message": "Internal server error", "ErrorCode": 4, "Detail": "" } }, "schema": { "properties": { "Message": { "description": "Message.", "type": "string" }, "ErrorCode": { "description": "Error code.", "type": "integer" }, "Detail": { "description": "Detail.", "type": "string" } }, "type": "object" } } }, "tags": [ "Frequency Switching" ], "summary": "Restarts the schedule of a contract.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/restartSchedule' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/customer/{customerId}/contract": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The GUID of the customer (if the customer already exists).", "format": "guid", "in": "path", "name": "customerId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Contracts": [ { "Amount": 1, "AtTheEnd": "Expire", "Description": "Collect an initial £1.00 followed by 9 payments of\n£1.00 on 15th of the month ending on 25th April 2017\n", "DirectDebitReference": "LUISCT-MT000325", "Every": 1, "ExtraInitialAmounts": "", "Id": "7aa8cef6-ec95-47a7-9ced-4aa0938559ab", "InitialAmount": 1, "IsGiftAid": true, "NumberOfDebits": 10, "PaymentDayInMonth": "15", "PaymentMonthInYear": 7, "ScheduleName": "DD Dates 1/15 - Fixed", "Start": "2016-07-15T00:00:00.000Z", "Status": "Active", "StatusExplanation": "N/A", "TerminationType": "Take certain number of debits" } ], "CustomerId": "19283a22-7442-4c92-b035-8fa7f5e6a9a0" }, "application/xml": "\n 19283a22-7442-4c92-b035-8fa7f5e6a9a0\n \n \n 7aa8cef6-ec95-47a7-9ced-4aa0938559ab\n LUISCT-MT000325\n DD Dates 1/15 - Fixed\n Collect an initial £1.00 followed by 9 payments of\n £1.00 on 15th of the month ending on 25th April\n 2017\n 7\n 15\n 2016-07-15T00:00:00\n \n Take certain number of\n debits\n 10\n 1.00\n \n 1.00\n \n 1\n true\n Expire\n Active\n N/A\n \n \n\n" }, "schema": { "properties": { "Contracts": { "description": "Array of contracts for the given customer.", "items": { "$ref": "#/definitions/Contract" }, "type": "array" }, "CustomerId": { "description": "Database GUID for the given customer.", "type": "string", "format": "guid" } }, "type": "object" } } }, "tags": [ "Contract Querying and Creation" ], "summary": "Queries the database for a contract or set of contracts.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.Contracts(\"310a826b-d095-48e7-a55a-19dba82c566f\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.contracts(\"310a826b-d095-48e7-a55a-19dba82c566f\")\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get(settings);\nString response = get.contracts(\"310a826b-d095-48e7-a55a-19dba82c566f\");\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/{customerId}/contract' -H 'apiKey: {apiKey}'\n" } ] }, "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The GUID of the customer (if the customer already exists).", "format": "guid", "in": "path", "name": "customerId", "required": true, "type": "string" }, { "description": "The name of the schedule to be used when creating a contract. You must include either this or the `scheduleId` parameter.", "in": "query", "maxLength": 200, "name": "scheduleName", "required": true, "type": "string" }, { "description": "The database GUID to be used when creating a contract. You must include either this or the `scheduleName` parameter.", "in": "query", "format": "guid", "name": "scheduleId", "required": true, "type": "string" }, { "description": "The start date of the contract. This **must** be at least 10 **working**\ndays in the future, on a permitted date and not after the anticipated\nfirst payment date. If this is a regular schedule, use the same date as\nthe first payment date.\nOnly up to 364 days in advance.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "start", "required": true, "type": "string" }, { "description": "If this is a “Take certain Number of Debits” contract then the number of\ndebits to be taken should be passed using this parameter.\nThis field is only mandatory if the termination type is “Take Certain\nNumber of Debits”.\n", "in": "query", "maximum": 999, "minimum": 0, "name": "numberOfDebits", "type": "integer" }, { "description": "If the contract is set to take regular payments, this parameter allows you\nto skip periods (e.g. every 2 months, every 4 weeks etc).\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\n", "in": "query", "name": "every", "type": "integer" }, { "description": "Pass true if the payments to be collected are to be subject to a gift aid\nclaim, false if not (pass false if the client is not a charity).\n", "in": "query", "name": "isGiftAid", "required": true, "type": "boolean" }, { "description": "If this is a contract for regular payments **and** the first payment is\ndifferent to the regular payments, then pass the first payment amount\nwith this parameter.\n**Do not** pass this parameter with ad-hoc contracts, or where the first\namount is the same as the regular amount.\n", "in": "query", "multipleOf": 0.01, "name": "initialAmount", "type": "number" }, { "description": "If there are extra charges to be collected with the first payment\n(e.g. a gym joining fee/registration fee) then these can be added\nseparately with this parameter. Do not pass the parameter if there\nare no extra amounts, and this must not be used if the contract is\nan ad-hoc payment contract.\n", "in": "query", "multipleOf": 0.01, "name": "extraInitialAmounts", "type": "number" }, { "description": "If the contract is for regular payments, then the regular payment\namount should be passed using this parameter. Do not pass this\nparameter if the contract is an ad-hoc contract.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\n", "in": "query", "multipleOf": 0.01, "name": "amount", "type": "number" }, { "description": "If this is a contract for regular payments **and** the final payment is\ndifferent to the regular payments, then pass the final payment amount\nwith this parameter. **Do not** pass this parameter with ad-hoc\ncontracts, or where the final amount is the same as the regular amount.\n", "in": "query", "multipleOf": 0.01, "name": "finalAmount", "type": "number" }, { "description": "If the contract is for regular payments then the month in which you\nwish the first payment should be passed with this parameter.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\nThis field is only mandatory if the contract is **annual** or **monthly**.\n", "in": "query", "maximum": 12, "minimum": 1, "name": "paymentMonthInYear", "type": "integer" }, { "description": "If the contract is for regular payments, then the day on which you wish\nthe first payment should be passed with this parameter.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\nThis field is only mandatory if the contract is **annual** or **monthly**.\n**NOTE:** You may only select:\n - days **1** to **28**\n - **98**, which represents `Last working day of the Month`\n - **99**, which represents `Last day of the Month`\nequal with value 99.\n*You may not* select days 29, 30 or 31 of the month; choosing 29, 30 or 31 will result in payments being skipped in months that do not contain that date.\n", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 98, 99 ], "in": "query", "name": "paymentDayInMonth", "type": "integer" }, { "description": "1 -> Monday \n2 -> Tuesday \n3 -> Wednesday \n4 -> Thursday \n5 -> Friday\nIf the contract is for regular payments and has a weekly frequency, pass the\nday of the week that you wish payments to be collected via this parameter.\nThis field is only mandatory if the contract is **not** an ad-hoc contract.\nThis field is only mandatory if the contract is **weekly**.\n", "in": "query", "maximum": 5, "minimum": 1, "name": "paymentDayInWeek", "type": "integer" }, { "description": "Pass the way in which the contract should end using this parameter.\nIf the contract is **ad-hoc,** *you must* pass `Until further notice`.\n", "enum": [ "Take certain number of debits", "Until further notice", "End on exact date" ], "in": "query", "name": "terminationType", "required": true, "type": "string" }, { "description": "This parameter decides what will happen when the contract ends. If you have\nselected a `terminationType` of `Until Further Notice` or the contract is an\nad-hoc contract, *you must* pass `Switch to Further Notice`.\n", "enum": [ "Expire", "Switch to Further Notice" ], "in": "query", "name": "atTheEnd", "required": true, "type": "string" }, { "description": "If the `terminationType` is `End on Exact Date` then the termination date\nshould be passed using this.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "in": "query", "name": "terminationDate", "type": "string" }, { "description": "If you wish to add an additional reference to the contract for you own use,\nthis can be passed to using the `additionalReference` parameter.\n", "in": "query", "maxLength": 200, "name": "additionalReference", "type": "string" }, { "description": "**THIS PARAMETER SHOULD ONLY BE USED IF YOU HAVE BEEN INSTRUCTED TO DO SO** \nIf you have made arrangements with us to use a custom direct debit\nreferencing scheme, pass the custom direct debit using this parameter.\nThe field may only contain alphanumeric data (`a-z`, `A-Z`, `0-9`) and\ncertain special characters (whitespace, ampersand `&`, hyphen `-`, solidus `/` or full stop `.`).\n", "in": "query", "maxLength": 18, "name": "customDirectDebitRef", "type": "string" }, { "description": "Example JSON/XML payload.\n", "in": "body", "name": "body", "schema": { "example": { "ScheduleName": "adhoc_monthly_free", "Start": "2019-08-01T00:00:00.000", "IsGiftAid": false, "TerminationType": "Until further notice", "AtTheEnd": "Switch to further notice" }, "type": "object", "xml": { "name": "ContractRequestDto" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "DirectDebitRef": "LUISCT-MT000341", "Id": "e39940cc-9917-4b9e-8da4-5da4866862f1" }, "application/xml": "\n LUISCT-MT000340\n f98c6339-6cdf-4ea6-8523-ea2bd17aedb7\n\n" }, "schema": { "properties": { "Id": { "description": "The GUID of the contract record. You must save this to your database\nas it will be needed should you wish to update the contract or create\nad-hoc payments using the payments or bulk payments call.\n", "type": "string" }, "Message": { "description": "This will be `null`.", "type": "object" }, "directDebitRef": { "description": "This is the Direct Debit Reference that will be quoted to the\ncustomer’s bank when collecting funds. Some banks will show this\nreference on the customer’s statement, although this is not\nguaranteed.\n", "type": "string" } }, "type": "object" } }, "400": { "description": "Bad request - invalid schedule name", "examples": { "application/json": { "Message": "{scheduleName} is not given to any schedule of any service as a name\n" }, "application/xml": "\n {scheduleName} is not given to any schedule of any service as a name\n \n" } } }, "tags": [ "Contract Querying and Creation" ], "description": "For ad-hoc contracts, you will only need to pass `scheduleName`, `start`,\n`terminationType`, `atTheEnd` and `isGiftAid`.\n### Contract Statuses\nUpon creation, a Contract Status will read \"Active\". While a newly created contract is awaiting its first collection, it is inadvisable to attempt to make changes to the contract or to push ad-hoc payments to the contract as payments may be missed or marked unpaid without an attempt to collect being made. We recommend allowing the lead times that apply to your configuration to elapse before making changes to the contract or pushing ad-hoc payments into the system.\nA contract can be manifested in one of two ways:\n\n| Status | Description\n| ------ | ---------------------------------------------\n| **Active** | The contract is active and will either be producing payments if it is a scheduled contract, or able to accept ad-hoc payments if it is an ad-hoc contract.\n| **Inactive** | The contract has been cancelled and is no longer active. It cannot produce or accept payments, scheduled or otherwise.\n\nFor more information on a contract's status, the `StatusExplanation` field can provide a more detailed explanation. This field is free text and we recommend that it is stored and displayed to the end user as necessary.\n### Timeframes\nYou should also be aware that you must allow a minimum number of clear working days between setting up a contract and collecting the first payment, and a minimum number of clear working days between pushing a second or subsequent ad-hoc payment and its collection date on an active contract. The number of days required is configured per client and is not the same for all clients, so you should refer to the lead times that apply to your own configuration.\nA working day means a banking day in the United Kingdom which is Mondays to Fridays and excludes public and bank holidays. A list of public and bank holidays can be found here: . A date checker is also provided on our website: .\nWhile the above timeframes are the minimum required, we strongly recommend building yourself a day or two of contingency into your processes so that you have time to rectify any problems that may be encountered. We are unable under any circumstances to accept instructions for payments or new contracts after the appropriate cut off dates.\n", "summary": "Creates a contract in the database.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var post = new Post(settings);\nstring request = post.contract(\"310a826b-d095-48e7-a55a-19dba82c566f\", \"adhoc_monthly_free\", \"2019-08-01\", false, \"Until further notice\", \"Switch to further notice\");\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nrequest = client.post.contract('42217d45-cf22-4430-ab02-acc1f8a2d020',\n'test_schedule', '2019-05-07', False, 'Until further notice',\n'Switch to further notice', additional_reference='test_123')\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Post post = new Post(settings);\nString request = post.contract().customer(\"310a826b-d095-48e7-a55a-19dba82c566f\")\n .scheduleName(\"adhoc_monthly_free\").startDate(\"2019-08-01\").giftAid(false)\n .terminationType(\"Until further notice\").atTheEnd(\"Switch to further notice\").query();\n" }, { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/customer/{customerId}/contract?scheduleName=adhoc_monthly_free&start=2019-08-01&isGiftAid=false&terminationType=Until further notice&atTheEnd=Switch to further notice' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/schedules": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Services": [ { "RefPrefix": "AN", "RefProtocol": "Auto-number", "RefTo": "null,", "Schedules": [ { "AllowDifferentFirstPayment": true, "AllowDifferentLastPayment": false, "AllowFreeMonthDaySelection": false, "AllowFreeMonthSelection": true, "AllowFreeWeekDaySelection": true, "AtTheEnd": "Switch to further notice", "DayOfWeek": "Free", "DaysOfMonth": "15,24", "Description": "Annually > Every 1 year > 15th, 24th of any month\ncustomer's choice) > First , then on a regular basis\n", "Every": 1, "ExtraInitialPayments": "", "Frequency": "Annually", "IsExpiryDateReached": false, "IsNotScheduled": false, "IsSuspended": false, "MonthOfYear": "Free", "Name": "AN Dates 15/24 - Rolling", "RegistrationCharge": 0, "ScheduleId": "7663e3a0-514c-4ec7-808e-05d27a85fa98", "StartType": "As soon as possible", "TerminationType": "Until further notice" } ], "Title": "Annual Membership" } ] }, "application/xml": "\n \n \n Annual Membership\n Auto-number\n AN\n null\n \n \n 7663e3a0-514c-4ec7-808e-05d27a85fa98\n AN Dates 15/24 - Rolling\n \n Annually > Every 1 year > 15th, 24th of any month\n customer's choice) > First , then on a regular basis\n \n true\n false\n false\n true\n true\n Switch to further notice\n Free\n 15,24\n 1\n \n Annually\n false\n false\n false\n Free\n 0\n As soon as possible\n Until further notice\n \n \n \n \n\n" } } }, "tags": [ "Obtaining Available Schedules" ], "description": "The response is split into two parts as follows:\n1. Services\n Services give some general set-up detail for the underlying payment\n schedules:\n - Title\n - RefProtocol\n - RefPrefix\n - RefFrom\n - RefTo\n2. Schedules sit underneath Services and these are allocated to the customer\n in order to collect payments. The parameters returned are as\n follows:\n - ScheduleId\n - Name\n - Deacription\n - AllowDifferentFirstPayment\n - AllowDifferentLastPayment\n - AllowFreeMonthDaySelection\n - AllowFreeMonthSelection\n - AllowFreeWeekDaySelection\n - Amount\n - AtTheEnd\n - DayOfWeek\n - DaysOfMonth\n - Every\n - ExpectedNumberOfPayments\n - ExtraInitialPayments\n - FinalAmount\n - Frequency\n - InitialAmount\n - IsExpiryDateReached\n - IsNotScheduled\n - IsSuspended\n - MonthOfYear\n - RegistrationCharge\n - Start\n - StartType\n - TerminationDate\n - TerminationType\n", "summary": "Queries the database for details of existing schedules.", "x-codeSamples": [ { "lang": "C#", "name": "C# (EazySDK)", "source": "var get = new Get(settings);\nstring response = get.Schedules();\n" }, { "lang": "Python", "name": "Python (EazySDK)", "source": "client = eazysdk.EazySDK()\nresponse = client.get.schedules()\n" }, { "lang": "Java", "name": "Java (EazySDK)", "source": "Get get = new Get();\nString response = get.schedules();\n" }, { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/schedules' -H 'apiKey: {apiKey}'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/patch/changeamount": { "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which to add the patch.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "Start date of the patch.", "format": "datetime", "in": "query", "name": "from", "required": true, "type": "string" }, { "description": "End date of the patch.", "format": "datetime", "in": "query", "name": "to", "required": true, "type": "string" }, { "description": "Sets the contract's effective amount during the patch period.", "format": "decimal", "in": "query", "name": "amount", "required": true, "type": "number" }, { "description": "Comment for the patch.", "in": "query", "name": "comment", "required": true, "type": "string" }, { "description": "Example JSON/XML payload.\n", "in": "body", "name": "body", "schema": { "example": { "Comment": "Price increase", "From": "2021-12-05T00:00:00", "To": "2021-12-15T00:00:00", "Amount": 9.99 }, "type": "object", "xml": { "name": "PatchChangeAmountRequestDto" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "New Patch added to contract" } } }, "400": { "description": "Bad Request - Overlapping patches", "examples": { "application/json": { "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.", "ErrorCode": 3, "Message": "Validation error" } } }, "404": { "description": "Contract not found", "examples": { "application/json": { "error": "The requested resource is not found" } } } }, "tags": [ "Patches" ], "summary": "Adds a patch to change payment amount for a contract." } }, "/client/{clientCode}/contract/{contractId}/patch/skip": { "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which to add the patch.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "Start date of the patch.", "format": "datetime", "in": "query", "name": "from", "required": true, "type": "string" }, { "description": "End date of the patch.", "format": "datetime", "in": "query", "name": "to", "required": true, "type": "string" }, { "description": "Comment for the patch.", "in": "query", "name": "comment", "required": true, "type": "string" }, { "description": "Example JSON/XML payload.\n", "in": "body", "name": "body", "schema": { "example": { "Comment": "Payment pause", "From": "2021-12-05T00:00:00", "To": "2021-12-15T00:00:00" }, "type": "object", "xml": { "name": "PatchCollectionRequestDto" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "New Patch added to contract" } } }, "400": { "description": "Bad Request - Overlapping patches", "examples": { "application/json": { "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.", "ErrorCode": 3, "Message": "Validation error" } } }, "404": { "description": "Contract not found", "examples": { "application/json": { "error": "The requested resource is not found" } } } }, "tags": [ "Patches" ], "summary": "Adds a patch to skip collections for a contract." } }, "/client/{clientCode}/contract/{contractId}/patch/freeze": { "post": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which to add the patch.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "Start date of the patch.", "format": "datetime", "in": "query", "name": "from", "required": true, "type": "string" }, { "description": "End date of the patch.", "format": "datetime", "in": "query", "name": "to", "required": true, "type": "string" }, { "description": "Comment for the patch.", "in": "query", "name": "comment", "required": true, "type": "string" }, { "description": "Example JSON/XML payload.\n", "in": "body", "name": "body", "schema": { "example": { "Comment": "Payment pause", "From": "2021-12-05T00:00:00", "To": "2021-12-15T00:00:00" }, "type": "object", "xml": { "name": "PatchCollectionRequestDto" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "New Patch added to contract" } } }, "400": { "description": "Bad Request - Overlapping patches", "examples": { "application/json": { "Detail": "This Patch overlaps with an existing Patch for the same Contract. Please check dates.", "ErrorCode": 3, "Message": "Validation error" } } }, "404": { "description": "Contract not found", "examples": { "application/json": { "error": "The requested resource is not found" } } } }, "tags": [ "Patches" ], "summary": "Adds a patch to freeze collections for a contract." } }, "/client/{clientCode}/contract/{contractId}/patches": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the patches have been applied to.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "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" } ] } }, "schema": { "properties": { "Patches": { "description": "Array of Patches applied to this contract.", "type": "array", "items": { "$ref": "#/definitions/Patch" } } } } }, "404": { "description": "Contract not found", "examples": { "application/json": { "error": "The requested resource is not found" } } } }, "tags": [ "Patches" ], "summary": "Returns all patches applied to a given contract." } }, "/client/{clientCode}/contract/{contractId}/patch/{patchId}": { "get": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the patch has been applied to.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The patch GUID.", "format": "guid", "in": "path", "name": "patchId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "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" } }, "schema": { "$ref": "#/definitions/Patch" } }, "404": { "description": "Contract/patch not found", "examples": { "application/json": { "ErrorCode": 0, "Detail": null, "Message": "Patch not found" } } } }, "tags": [ "Patches" ], "summary": "Gets details of a specific patch." }, "patch": { "consumes": [ "application/json", "application/xml" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the patch has been applied to.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The patch GUID.", "format": "guid", "in": "path", "name": "patchId", "required": true, "type": "string" }, { "description": "The new end date to set for this patch.", "format": "datetime", "in": "query", "name": "to", "required": true, "type": "string" }, { "description": "A comment for this update.", "in": "query", "name": "comment", "required": true, "type": "string" }, { "description": "Example JSON/XML payload.\n", "in": "body", "name": "body", "schema": { "example": { "To": "2021-12-15T00:00:00.000", "Comment": "Extend patch" }, "type": "object", "xml": { "name": "PatchUpdateRequestDto" } } } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Patch updated" } } }, "400": { "description": "Bad Request - Invalid To date", "examples": { "application/json": { "ErrorCode": 3, "Detail": "To date should be greater than From Date. Please check patch dates", "Message": "Validation error" } } }, "404": { "description": "Contract/patch not found", "examples": { "application/json": { "ErrorCode": 0, "Detail": null, "Message": "Patch not found" } } } }, "tags": [ "Patches" ], "summary": "Updates the end date of a patch." }, "delete": { "produces": [ "application/json", "application/xml" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract GUID on which the patch has been applied to.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The patch GUID.", "format": "guid", "in": "path", "name": "patchId", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "examples": { "application/json": { "Message": "Patch deleted" } } }, "404": { "description": "Contract/patch not found", "examples": { "application/json": { "ErrorCode": 0, "Detail": null, "Message": "Patch not found" } } } }, "tags": [ "Patches" ], "summary": "Deletes a patch." } }, "/client/{clientCode}/ddcmsdirect/import": { "post": { "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The file to be imported. Must be in one of the supported formats:\nBACS Standard 18, BACS Standard 18 Payment Lines, SmartDebit Direct CSV,\nor BACS Active (EaziPay).\n", "in": "formData", "name": "file", "required": true, "type": "file" }, { "description": "The file format type, which determines which structural validation rules\nare applied to the uploaded file. Must be one of the following values:\n- `bacs_standard_18` - BACS Standard 18\n- `bacs_standard_18_payment_lines` - BACS Standard 18 Payment Lines\n- `smartdebit_direct_csv` - SmartDebit Direct CSV\n- `bacs_active_eazipay` - BACS Active (EaziPay)\n", "in": "formData", "name": "fileType", "required": true, "type": "string", "enum": [ "bacs_standard_18", "bacs_standard_18_payment_lines", "smartdebit_direct_csv", "bacs_active_eazipay" ] } ], "responses": { "200": { "description": "File imported successfully", "schema": { "properties": { "status": { "type": "string", "description": "Returns `success` when the file has been imported." }, "fileId": { "type": "string", "format": "uuid", "description": "The unique idenitifer assigned to the imported file.\nYou should save this for future reference.\n" }, "importedAt": { "type": "string", "format": "date-time", "description": "The date/time at which the file was imported." }, "message": { "type": "string", "description": "A human-readable message confirming the import." }, "fileStatus": { "type": "string", "description": "The current status of the file. Will be `Queued for validation` on a successful import." }, "nextSteps": { "type": "string", "description": "Guidance on what to do next after a successful import." } }, "type": "object" }, "examples": { "application/json": { "status": "success", "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "importedAt": "2024-01-20T15:30:00Z", "message": "File imported successfully", "fileStatus": "Queued for validation", "nextSteps": "File is queued for validation. Check DDCMS Direct UI for validation results and any required actions such as SUN assignment or processing date selection." } } }, "400": { "description": "Bad request. This can occur for several reasons:\n- **Missing `fileType` parameter:** The `fileType` form field was not included in the request.\n- **Invalid `fileType` value:** The `fileType` value is not one of the supported file types.\n- **Missing or empty `file`:** The `file` form field was not included or the file is empty.\n- **Request not `multipart/form-data`:** The request `Content-Type` is not `multipart/form-data`.\n- **Structural validation failure:** The file was parsed but failed structural/format validation checks.\n", "schema": { "properties": { "status": { "type": "string", "description": "Returns `error` for parameter issues,\nor `validation_failed` for structural validation features.\n" }, "message": { "type": "string", "description": "A human-readable description of the error." }, "errors": { "type": "array", "description": "Only present when `status` is `validation_failed`.\nAn array of structural validation errors found in the file.\n", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "The category of the error (e.g. `structural_validation`, `file_format`)." }, "message": { "type": "string", "description": "A human-readable description of the specific validation error." } } } }, "errorType": { "type": "string", "description": "Only present when `status` is `validation_failed`. Returns `structural`." }, "supportedFileTypes": { "type": "array", "items": { "type": "string" }, "description": "Only present when the error is caused by an invalid `fileType` value.\nLists the supported file type keys.\n" } }, "type": "object" }, "examples": { "Missing fileType parameter": { "status": "error", "message": "fileType parameter is required" }, "Invalid fileType value": { "status": "error", "message": "Invalid fileType value. Must be one of the supported file types.", "supportedFileTypes": [ "bacs_standard_18", "bacs_standard_18_payment_lines", "smartdebit_direct_csv", "bacs_active_eazipay" ] }, "Missing or empty file": { "status": "error", "message": "file is required and must not be empty" }, "Request not multipart": { "status": "error", "message": "Request must be multipart/form-data" }, "Structural validation failure": { "status": "validation_failed", "message": "File structural validation failed", "errors": [ { "category": "structural_validation", "message": "Invalid BACS Standard 18 file structure: Missing HDR2 header record" }, { "category": "structural_validation", "message": "File does not match selected format type" } ], "errorType": "structural" } } }, "403": { "description": "Forbidden - DDCMS Direct feature not enabled for this client", "schema": { "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "examples": { "application/json": { "status": "error", "message": "DDCMS Direct feature not enabled for this client" } } }, "413": { "description": "Request Entity Too Large - the uploaded file exceeds the maximum allowed size of 137000000 bytes (130 MB)", "schema": { "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "maxFileSizeBytes": { "type": "integer", "description": "The maximum file size allowed, in bytes (137000000)." } }, "type": "object" }, "examples": { "application/json": { "status": "error", "message": "File exceeds the maximum allowed size", "maxFileSizeBytes": 137000000 } } }, "500": { "description": "Internal Server Error. This may occur if:\n- The API user is not configured in the system.\n- An unexpected error occurred during processing.\n", "schema": { "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "examples": { "application/json": { "status": "error", "message": "An internal server error occurred" } } } }, "tags": [ "DDCMS Direct File Import" ], "summary": "Imports a BACS payment file via the API for processing through DDCMS Direct.", "description": "Imports a file into DDCMS Direct for processing through the existing approval\nworkflows. The file undergoes initial structural validation based on the specified\n`fileType`. If validation passes, the file is stored and queued for further\nvalidation.\n**Prerequisites:**\n- The client must have the DDCMS Direct feature enabled.\n- The request must be sent as `multipart/form-data`.\n- Both `file` and `fileType` form fields are required.\n\n**Upload Attribution:**\nFiles uploaded via this endpoint are recorded as \"Uploaded by: API User\".\nThe file will appear in the DDCMS Direct UI and on the home screen with\n\"API User\" attribution. When a user subsequently interacts with the file,\nthe attribution transfers to that user to ensure correct approval workflows.\n\n**After a Successful Import:**\nThe file will have status \"Queued for validation\". Check the DDCMS Direct UI\nfor validation results and any required actions such as SUN assignment or\nprocessing date selection.\n", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X POST \\\n 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/ddcmsdirect/import' \\\n -H 'apiKey: {apiKey}' \\\n -F 'file=@/path/to/payment-file.txt' \\\n -F 'fileType=bacs_standard_18'\n" }, { "lang": "C#", "source": "using (var client = new HttpClient())\n{\n client.DefaultRequestHeaders.Add(\"apiKey\", \"{apiKey}\");\n using (var content = new MultipartFormDataContent())\n {\n var fileContent = new ByteArrayContent(File.ReadAllBytes(\"/path/to/payment-file.txt\"));\n fileContent.Headers.ContentType = new MediaTypeHeaderValue(\"application/octet-stream\");\n content.Add(fileContent, \"file\", \"payment-file.txt\");\n content.Add(new StringContent(\"bacs_standard_18\"), \"fileType\");\n var response = await client.PostAsync(\n \"https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/ddcmsdirect/import\",\n content);\n var result = await response.Content.ReadAsStringAsync();\n }\n}\n" }, { "lang": "Python", "source": "import requests\nurl = \"https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/ddcmsdirect/import\"\nheaders = {\"apiKey\": \"{apiKey}\"}\nfiles = {\"file\": open(\"/path/to/payment-file.txt\", \"rb\")}\ndata = {\"fileType\": \"bacs_standard_18\"}\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())\n" }, { "lang": "Java", "source": "HttpClient client = HttpClient.newHttpClient();\nPath filePath = Path.of(\"/path/to/payment-file.txt\");\nString boundary = UUID.randomUUID().toString();\nString body = \"--\" + boundary + \"\\r\\n\"\n + \"Content-Disposition: form-data; name=\\\"fileType\\\"\\r\\n\\r\\n\"\n + \"bacs_standard_18\\r\\n\"\n + \"--\" + boundary + \"\\r\\n\"\n + \"Content-Disposition: form-data; name=\\\"file\\\"; filename=\\\"payment-file.txt\\\"\\r\\n\"\n + \"Content-Type: application/octet-stream\\r\\n\\r\\n\"\n + Files.readString(filePath) + \"\\r\\n\"\n + \"--\" + boundary + \"--\";\nHttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/ddcmsdirect/import\"))\n .header(\"apiKey\", \"{apiKey}\")\n .header(\"Content-Type\", \"multipart/form-data; boundary=\" + boundary)\n .POST(HttpRequest.BodyPublishers.ofString(body))\n .build();\nHttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());\n" } ] } }, "/client/{clientCode}/unpaidPaymentRetrySettings": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/UnpaidPaymentRetrySettings" }, "examples": { "application/json": { "AllowRetryFailedPayments": true, "RetryPaymentsDelayDays": 10, "FailedPaymentRetries": 2 } } } }, "tags": [ "Configurable Represents" ], "summary": "Returns the current retry configuration for your client.", "description": "Returns the current retry configuration for your client.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X GET 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/unpaidPaymentRetrySettings' -H 'apiKey: {apiKey}'\n" } ] }, "patch": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The updated retry settings for your client.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/UpdateUnpaidPaymentRetrySettingsRequest" } } ], "responses": { "200": { "description": "OK - Returns the updated retry settings.", "schema": { "$ref": "#/definitions/UnpaidPaymentRetrySettings" }, "examples": { "application/json": { "AllowRetryFailedPayments": true, "RetryPaymentsDelayDays": 10, "FailedPaymentRetries": 2 } } } }, "tags": [ "Configurable Represents" ], "summary": "Updates the retry configuration for your client.", "description": "Updates the retry configuration for your client.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X PATCH 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/unpaidPaymentRetrySettings' -H 'apiKey: {apiKey}' -H 'Content-Type: application/json' --data-raw '{\n \"AllowRetryFailedPayments\": true,\n \"RetryPaymentsDelayDays\": 10,\n \"FailedPaymentRetries\": 2\n }'\n" } ] } }, "/client/{clientCode}/contract/{contractId}/payment/{paymentId}/retry": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "description": "The client code provided in your welcome email.", "in": "path", "maxLength": 6, "name": "clientCode", "required": true, "type": "string" }, { "description": "The contract ID for the payment.", "format": "guid", "in": "path", "name": "contractId", "required": true, "type": "string" }, { "description": "The payment ID to represent.", "format": "guid", "in": "path", "name": "paymentId", "required": true, "type": "string" }, { "description": "The date the re-presented payment should be collected.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/ManuallyRepresentPaymentRequest" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request - payment not eligible, processing date is not a valid working day, date exceeds Bacs limit, or required fields are missing." }, "401": { "description": "Unauthorised - invalid or missing API key." }, "403": { "description": "Forbidden - the payment belongs to a different client." }, "404": { "description": "Not Found - payment or contract not found." } }, "tags": [ "Configurable Represents" ], "summary": "Triggers a re-presentation for a specific failed payment.", "description": "Triggers a re-presentation for a specific failed payment. The payment must be eligible: within 1 calendar month of the original payment date, the Direct Debit Instruction must be active, and the payment must not already be in a Pending or Paid status.\n", "x-codeSamples": [ { "lang": "cURL", "source": "curl -L -g -X POST 'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/contract/{contractId}/payment/{paymentId}/retry' -H 'apiKey: {apiKey}' -H 'Content-Type: application/json' --data-raw '{\n \"ProcessingDate\": \"2026-06-21T00:00:00.000Z\"\n }'\n" } ] } } }, "definitions": { "AddressDetail": { "description": "Address of the customer.", "type": "object", "properties": { "Line1": { "description": "Line 1 of the customer's address.", "type": "string" }, "Line2": { "description": "Line 2 of the customer's address.", "type": "string" }, "Line3": { "description": "Line 3 of the customer's address.", "type": "string" }, "Line4": { "description": "Line 4 of the customer's address.", "type": "string" }, "PostCode": { "description": "The customer's registered postcode.", "type": "string" } } }, "Answer": { "description": "Answer to a custom question.", "type": "object", "properties": { "Id": { "description": "Unique ID for the answer.", "type": "string", "format": "guid" }, "Product": { "description": "If the question is a ServiceCustomQuestion, returns the service the question belongs to. Otherwise, returns `null`.", "type": "string", "format": "guid" }, "Customer": { "description": "Unique ID for the customer.", "type": "string", "format": "guid" }, "CustomQuestion": { "description": "Unique ID for the question the answer is for.", "type": "string", "format": "guid" }, "Answer": { "description": "Actual value of the answer.", "type": "string" } } }, "BankDetail": { "description": "Details of the customer's bank account.", "type": "object", "properties": { "AccountHolderName": { "description": "Name on the account.", "type": "string" }, "AccountNumber": { "description": "The eight-digit account number.", "type": "string" }, "BankSortCode": { "description": "The six-digit bank sort code.", "type": "string" } } }, "BulkPayment": { "description": "Single ad-hoc payment request used in bulk adding payments.", "type": "object", "properties": { "amount": { "description": "The amount to be collected.", "multipleOf": 0.01, "type": "number" }, "comment": { "description": "A comment relating to the payment (which can be recalled using\nthe GET method).\n", "maxLength": 200, "type": "string" }, "contract": { "description": "The contract GUID that you wish to collect a payment against.", "format": "guid", "type": "string" }, "date": { "description": "The date on which the payment should be collected.\nThis **must** be at least 5 **working** days in the future,\non a permitted date and not before the start date set when\ncreating the contract.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "format": "date-time", "type": "string" }, "isCredit": { "description": "If you have an own SUN and you have agreed by prior arrangement\nwith your account manager that you may issue credits, pass\n`true` with this parameter to issue a credit to the customer.\nIf omitted, this will be a debit.\n", "type": "boolean" } }, "required": [ "amount", "contract", "date" ] }, "BulkPaymentRequest": { "description": "Payload for the bulk adding payments request.", "type": "object", "properties": { "Payments": { "description": "Array of payments to be inserted in bulk.", "type": "array", "items": { "$ref": "#/definitions/BulkPayment" } } } }, "CallbackEntities": { "description": "The entity for which to receive callback BACS messages.", "enum": [ "bulkpayment", "customer", "contract", "payment", "schedule" ], "type": "string" }, "ClientListPaymentsRequest": { "description": "Payload for the `/client/{clientCode}/payments` endpoint.", "type": "object", "properties": { "PageNumber": { "description": "Page number for the pagination.", "type": "number", "default": 1 }, "PageSize": { "description": "Number of payment records to return per page.", "type": "number", "default": 100 }, "ContractId": { "description": "Unique ID for a particular contract you want to list payments for.", "type": "string", "format": "uuid" }, "CustomerId": { "description": "Unique ID for a particular customer you want to list payments for.\n**Note:** this will be ignored if `ContractId` is also provided.\n", "type": "string", "format": "uuid" }, "IsCredit": { "description": "Set to `true` to only return credit payments.\nSet to `false` to only return debit payments.\n", "type": "boolean" }, "IsScheduled": { "description": "Set to `true` to only return payments generated by DDCMS on a regular/fixed schedule. \nSet to `false` to only return ad-hoc payments.\n", "type": "boolean" }, "Status": { "description": "Set to only return payments with a particular status.", "type": "string", "enum": [ "Indemnity Claimed", "Paid", "Pending", "Represented", "Unpaid", "withdrawn" ] }, "Type": { "description": "Set to only return payments of a particular type.", "type": "string", "enum": [ "Credit", "Final", "First Time", "Regular", "Retry" ] }, "CollectionDateFrom": { "description": "Earliest `Due` date to return payments for.", "type": "string", "format": "date-time" }, "CollectionDateTo": { "description": "Latest `Due` date to return payments for.", "type": "string", "format": "date-time" }, "CreatedAfter": { "description": "Earliest `DateAdded` date to return payments for.", "type": "string", "format": "date-time" }, "CreatedBefore": { "description": "Latest `DateAdded` date to return payments for.", "type": "string", "format": "date-time" } } }, "Contract": { "properties": { "Amount": { "description": "If the contract is for regular payments, then the regular payment amount is returned in this parameter.", "type": "number" }, "AtTheEnd": { "description": "This parameter decides what will happen when the contract ends.", "enum": [ "Expire", "Switch to Further Notice" ], "type": "string" }, "Description": { "description": "A description of the contract. This can include number of payments, payment amount, end date etc.", "type": "string" }, "DirectDebitReference": { "description": "The bank reference for the contract.", "type": "string" }, "Every": { "description": "If the contract is set to take regular payments, this parameter shows the frequency of payments generated (e.g. every 2 months, every 4 weeks etc).", "type": "integer" }, "ExtraInitialAmounts": { "description": "If there are extra charges to be collected with the first payment (e.g. a gym joining fee/registration fee) then these are shown separately with this parameter.", "type": "number" }, "Id": { "description": "The DDCMS database GUID for this contract.", "format": "guid", "type": "string" }, "InitialAmount": { "description": "If this is a contract for regular payments and the first payment is different to the regular payments, then the first payment amount is passed with this parameter.", "type": "number" }, "IsGiftAid": { "description": "Whether or not payments for the contract are subject to a gift aid claim.", "type": "boolean" }, "NumberOfDebits": { "description": "If this is a “Take Certain Number of Debits” contract then the number of debits to be taken are returned in this parameter.", "type": "integer" }, "PaymentDayInMonth": { "description": "If the contract is for regular payments, then the day on which the first payment is taken is returned with this parameter.", "type": "string", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, "Last Day of the Month" ] }, "PaymentMonthInYear": { "description": "If the contract is for regular payments then the month in which the first payment is taken is returned with this parameter.", "maximum": 12, "minimum": 1, "type": "integer" }, "ScheduleName": { "description": "The name of the schedule the contract was setup against.", "type": "string" }, "Start": { "description": "The start date of the contact.", "format": "date-time", "type": "string" }, "Status": { "description": "The current status of the contract.", "type": "string", "enum": [ "Inactive", "Expired", "Cancelled", "Pause", "Suspended", "Cancellation Pending", "Active", "Creation Pending" ] }, "StatusExplanation": { "description": "Provides an explanation for the most recent status update for the contract.", "type": "string" }, "TerminationType": { "description": "How this contract will end.", "type": "string", "enum": [ "Take certain number of debits", "Until further notice", "End of exact date" ] } } }, "Customer": { "properties": { "AddressDetail": { "$ref": "#/definitions/AddressDetail" }, "BankDetail": { "$ref": "#/definitions/BankDetail" }, "CompanyName": { "description": "The customer's registered company.", "type": "string" }, "CustomerRef": { "description": "The unique customer reference.", "type": "string" }, "DateAdded": { "description": "Datetime for when this customer was created in the database.", "type": "string", "format": "datetime" }, "DateOfBirth": { "description": "The customer's date of birth.", "type": "string", "format": "datetime" }, "Email": { "description": "The customer's email address.", "type": "string", "format": "email" }, "FirstName": { "description": "First name of the customer.", "type": "string" }, "HomePhoneNumber": { "description": "The customer's home phone number.", "type": "string" }, "Id": { "description": "The GUID for this customer object.", "type": "string", "format": "guid" }, "IsArchived": { "description": "Returns true if all of the customer's contracts are archived, otherwise false.", "type": "boolean" }, "Memos": { "description": "Memos for this customer. When calling `GET /customer` with `includeMemos=false`, this will be `null`.", "type": "array", "items": { "$ref": "#/definitions/CustomerMemo" } }, "MobilePhoneNumber": { "description": "The customer's mobile phone number.", "type": "string" }, "Surname": { "description": "Last name of the customer.", "type": "string" }, "Title": { "description": "The customer's preferred title.", "type": "string", "enum": [ "Mrs", "Mr", "Miss", "Ms", "Dr", "Sir", "Lord", "Lady", "Prof.", "Rev.", "Master", "Mx" ] }, "WorkPhoneNumber": { "description": "The customer's work phone number.", "type": "string" } }, "type": "object" }, "CustomerMemo": { "description": "Memo attached to a customer's contract.", "type": "object", "properties": { "At": { "description": "Datetime for when the memo was added.", "type": "string", "format": "datetime" }, "Body": { "description": "HTML body of the memo.", "type": "string" }, "ContractRef": { "description": "Direct Debit reference for the contract the memo was assigned to.", "type": "string" } } }, "ManuallyRepresentPaymentRequest": { "description": "Request body for manually triggering a re-presentation for a specific failed payment.", "type": "object", "required": [ "ProcessingDate" ], "properties": { "ProcessingDate": { "description": "The date the re-presented payment should be collected. Must be a working day within 1 calendar month of the original payment date.", "type": "string", "format": "date-time" } } }, "PagingMetadata": { "description": "Object providing useful metadata for clients calling an endpoint with pagination.", "type": "object", "properties": { "TotalPages": { "description": "Total count of pages.", "type": "number" }, "TotalRecords": { "description": "Count of records with current filter.", "type": "number" }, "PageSize": { "description": "Number of records returned per page.", "type": "number" }, "PageNumber": { "description": "Current page.", "type": "number" } } }, "Patch": { "properties": { "Amount": { "description": "If type is `Change amount`, defines the effective contract amount during this patch.", "format": "decimal", "type": "number" }, "Comment": { "description": "A user-defined comment for this patch.", "type": "string" }, "DateAdded": { "description": "Date-time this patch was added in the system.", "format": "datetime", "type": "string" }, "DateFrom": { "description": "Start date for the patch.", "format": "datetime", "type": "string" }, "DateTo": { "description": "End date for the patch.", "format": "datetime", "type": "string" }, "Id": { "description": "The GUID for this patch object.", "format": "guid", "type": "string" }, "Type": { "description": "Type of patch.", "enum": [ "Change amount", "Freeze collect (leave contract as is)", "Skip collection (adjusts contract)" ], "type": "string" } } }, "Payment": { "properties": { "Amount": { "description": "The amount of the payment.", "type": "number" }, "Comment": { "description": "The comment passed when the payment was added; a ReasonMessage\nmay be appended to the end of this.\n", "type": "string" }, "Date": { "description": "The due date of the payment.", "format": "date-time", "type": "string" }, "Id": { "description": "The GUID of the payment. We suggest that you save this so that you can easily\nchange or query the payment in future. If you are using pushed return data,\nthis will be included in any payload delivered concerning the payment.\n", "format": "guid", "type": "string" }, "IsAdhoc": { "description": "If this is an adhoc payment, this will show as `true`, else if it is a\nscheduled payment, it will shows as `false`.\n", "type": "boolean" }, "IsCredit": { "description": "If the payment is a credit to the customer, this will show as `true`, else it\nwill show as `false`.\n", "type": "boolean" }, "ReasonCode": { "description": "The BACS reason code of the payment if the payment has been returned unpaid.\nThe possible reasons are:\n- 0: Refer to payer.\n- 1: Instruction cancelled.\n- 2: Payer deceased.\n- 3: Account transferred.\n- 4: Advance notice disputed.\n- 5: No account/Wrong account type.\n- 6: No instruction.\n- 7: Amount differs.\n- 8: Amount not yet due.\nFor further details on the meanings of these codes, and the associated action\nrequired, please see our separate booklet.\n", "maximum": 8, "minimum": 0, "type": "integer" }, "ReasonMessage": { "description": "Plain text explanation of the ReasonCode.", "type": "string" }, "Status": { "description": "The status of the payment. This can be:\n- Paid - We have received the payment from the customer (\\*\\*see below)\n- Pending – The payment has been queued to be sent to the bank for collection.\n- Represented – The payment has been returned by the bank **unpaid**, and the\n system has created a new transaction to try and collect the amount again.\n- Unpaid – The payment has been returned by the bank unpaid and **will not**\n be sent again to the bank for collection.\n- Withdrawn – The payment was at the point of being sent to the bank for\n collection, but was withdrawn by Access Paysuite at the last minute. The\n payment has not been collected.\n- Indemnity Claimed – The customer has approached their bank for a refund\n which is being/has been processed.\n\\*\\* BACS works by exception; that is to say that payments are assumed to be\npaid unless we hear from the bank otherwise. As such, payments remain in the\n`Pending` state up until the point they are submitted to the bank for\ncollection (3 – 4 working days before the collection date). Upon submission,\nthe payment status changes to `Paid` although the actual status of the payment\nis not known until 1-2 working days after the due date. Because of this, we\nrecommend that you do not update your system with the payment status until \n2-3 working days after the Due Date.\nIt is also important to note that BACS only works on banking days (Monday to\nFriday excluding bank and public holidays). For that reason, if a payment\nDue Date is on a weekend or a public holiday, the collection will take place\non the next banking day. For example, a payment due on Saturday, 15th April\n2017 will actually collect on Tuesday 18th April 2017 (the Monday being Easter\nMonday which is a bank holiday in the UK). Again, this needs to be factored in\nto when you check the status of payments; in the above example, it would be\nprudent to wait until late in the afternoon of 20th April 2017 or better 21st\nApril 2017 to ensure that all unpaid messages have been received from the bank\nand processed.\n", "enum": [ "Paid", "Pending", "Represented", "Unpaid", "Withdrawn", "Indemnity Claimed" ], "type": "string" }, "Type": { "description": "The type of payment (BACS being a bank processed payment,\nManual being something manually added via the UI.\n", "type": "string" } }, "type": "object" }, "Question": { "properties": { "Id": { "description": "Unique ID for this question. We recommend you keep a record of this as it's required for adding answers.", "type": "string", "format": "guid" }, "Label": { "description": "Label for the question.", "type": "string" }, "Type": { "description": "Data type for answers to this question.", "type": "string", "enum": [ "text", "list", "date" ] }, "Options": { "description": "Comma-separated list of possible answers for this question. Can only be used when type is `list`.", "type": "array", "items": { "type": "string" } }, "Tags": { "description": "A custom tag that was assigned to this question.\n\nIf the question was created from an eDD page, this will be populated with the end of the URL to the page. For example, if the question was added on `https://secure.edirectdebit.co.uk/Example/DD-Signups`, the Tags would be `DD-Signups`.\n", "type": "string" }, "IsMandatory": { "description": "Whether or not an answer is required for this question.", "type": "boolean" } } }, "StreamVersion": { "properties": { "Id": { "description": "The stream version identifier.", "type": "string", "format": "guid" }, "Status": { "description": "Status.", "type": "string" }, "IsPatch": { "description": "Is patch.", "type": "boolean" }, "StartDate": { "description": "Start date.", "type": "string", "format": "datetime" }, "Frequency": { "description": "Frequency.", "type": "string" }, "Every": { "description": "Every.", "type": "integer" }, "PaymentDayInWeek": { "description": "Payment day in week.", "type": "integer" }, "PaymentDayInMonth": { "description": "Payment day in month.", "type": "integer" }, "PaymentMonthInYear": { "description": "Payment month in year.", "type": "integer" }, "InitialDate": { "description": "Initial date.", "type": "string", "format": "datetime" }, "InitialAmount": { "description": "Initial amount.", "type": "number", "format": "decimal" }, "RegistrationFee": { "description": "Registration fee.", "type": "number", "format": "decimal" }, "ExtraInitialAmounts": { "description": "Extra initial amounts.", "type": "string" }, "Amount": { "description": "Amount.", "type": "number", "format": "decimal" }, "FinalAmount": { "description": "Final amount.", "type": "number", "format": "decimal" }, "IsGiftAid": { "description": "Is gift aid.", "type": "boolean" }, "TerminationType": { "description": "Termination type.", "type": "string" }, "TerminationDate": { "description": "Termination date.", "type": "string", "format": "datetime" }, "NumberOfDebits": { "description": "Number of debits.", "type": "integer" } } }, "UnpaidPaymentRetrySettings": { "description": "Retry configuration for unpaid (failed) payments for a client.", "type": "object", "properties": { "AllowRetryFailedPayments": { "description": "Whether Configurable Represents is enabled for your organisation.", "type": "boolean" }, "RetryPaymentsDelayDays": { "description": "Number of working days configured between a failed payment and its re-presentation.", "type": "integer" }, "FailedPaymentRetries": { "description": "Maximum number of retry attempts configured (1-3).", "type": "integer" } } }, "UpdateCustomerJsonRequest": { "description": "Request body for updating (or partially updating) an existing customer via JSON. Send only the fields you want to change.", "type": "object", "properties": { "Email": { "description": "The customer's contact email address.", "type": "string", "maxLength": 200 }, "Title": { "description": "The customer's title (Mr/Mrs/Ms/Miss/Mx etc).", "type": "string", "maxLength": 200 }, "DateOfBirth": { "description": "The customer's date of birth.\n**Format: `YYYY-MM-DDT00:00:00.000`**\n", "type": "string", "format": "date-time" }, "CustomerRef": { "description": "A unique reference number allocated by the client for this customer.", "type": "string", "maxLength": 200 }, "FirstName": { "description": "The customer's first name.", "type": "string", "maxLength": 200 }, "Surname": { "description": "The customer's surname.", "type": "string", "maxLength": 200 }, "CompanyName": { "description": "The company name of the customer (if applicable).", "type": "string", "maxLength": 200 }, "PostCode": { "description": "The customer's Post Code.", "type": "string", "maxLength": 10 }, "AccountNumber": { "description": "The customer's bank account number.\nThis must be eight numerical characters with all leading zeros left intact.\nExamples include: `01065284`, `00000000`, `26280464`.\nAny non-numerical characters **must be removed** before passing the data to the API.\n", "type": "string", "maxLength": 8, "minLength": 8, "pattern": "[0-9]{8}" }, "BankSortCode": { "description": "The customer's bank sort code.\nThis must be six numerical characters with all leading zeros left intact.\nExamples include: `089286` `100000` `600000`, `230580`.\nIn the United Kingdom it is sometimes customary to insert dashes/hyphens\nbetween groups of two characters (e.g. `08-92-86`, `23-05-80`). Any hyphens,\ndashes or non-numerical characters **must be removed** before being passed\nto the API.\n", "type": "string", "maxLength": 6, "minLength": 6, "pattern": "[0-9]{6}" }, "AccountHolderName": { "description": "The name of the customer's bank account.\nThis must be a maximum of eighteen alphanumeric characters `[0-9a-zA-Z ]`.\nA space is also allowed. Any special characters or punctuation such as ampersands,\napostrophes, hyphens, slashes, backslashes, commas, full stops etc. **must be\nremoved** before passing to the API.\n", "type": "string", "maxLength": 18, "pattern": "[0-9a-zA-Z ]{0, 18}" }, "HomePhoneNumber": { "description": "The customer's home telephone number.", "type": "string", "maxLength": 200 }, "WorkPhoneNumber": { "description": "The customer's work telephone number.", "type": "string", "maxLength": 200 }, "MobilePhoneNumber": { "description": "The customer's mobile telephone number.", "type": "string", "maxLength": 200 }, "Line1": { "description": "Line one of the customer's postal address.", "type": "string", "maxLength": 200 }, "Line2": { "description": "Line two of the customer's postal address.", "type": "string", "maxLength": 200 }, "Line3": { "description": "Line three of the customer's postal address.", "type": "string", "maxLength": 200 }, "Line4": { "description": "Line four of the customer's postal address.", "type": "string", "maxLength": 200 }, "Initials": { "description": "If the customer has provided any middle initials, they can be added in this field.", "type": "string", "maxLength": 200 }, "CustomerLocale": { "description": "Set the language of communications sent to this customer to English (`en-GB`) or Welsh (`cy-GB`).\nIf omitted, this defaults to English.\nIf Welsh support is not enabled for your organisation, submitting `cy-GB` returns a 400 error with the message: **\"Welsh language not enabled for this client\"**.", "type": "string", "maxLength": 5, "enum": [ "en-GB", "cy-GB" ] } } }, "UpdateUnpaidPaymentRetrySettingsRequest": { "description": "Request body for updating the retry configuration for a client.", "type": "object", "required": [ "AllowRetryFailedPayments" ], "properties": { "AllowRetryFailedPayments": { "description": "Set to `true` to enable Configurable Represents, `false` to disable.", "type": "boolean" }, "RetryPaymentsDelayDays": { "description": "Working days between a failed payment and re-presentation. Minimum = your look-forward days setting; maximum = 20. Required when `AllowRetryFailedPayments` is `true`.", "type": "integer" }, "FailedPaymentRetries": { "description": "Maximum retry attempts. Range: 1-3. Required when `AllowRetryFailedPayments` is `true`.", "type": "integer" } } } }, "securityDefinitions": { "ApiKeyAuth": { "in": "header", "name": "apiKey", "type": "apiKey" } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "description": "\nReturn data is passed to endpoints of your choice by setting the URL\nthat 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 at\nsupport@accesspaysuite.com to advise whether you require return\ninformation in XML or JSON format; the default is JSON.\n\n| Entity | Payload | \n| ------ | ------- |\n| bulkpayment | Notification of success/failure to process a bulk payment request - see 'Bulk Adding Payments' section for more info.\n| customer | Notification of customer changes due to BACS notifications \n| contract | Notification of contract changes due to BACS notifications \n| payment | Notification of payment status (Unpaid/Indemnity Claimed) changes due to BACS notifications\n| schedule | Notification of change, addition or deletion of a contract schedule\n", "name": "Return Endpoints" }, { "description": "Retrieve configuration info about your DDCMS client.", "name": "Client Info" }, { "description": "A customer record captures the personal and banking details of the\nperson or organisation that you wish to collect funds from. A customer\nrecord needs to be created before a Direct Debit (contract) record can\nbe created to collect payments. There can be multiple Direct Debits\n(contracts) attached to a customer record.\n**Important: You are required to perform a modulus check on bank account numbers\nand sort codes before they are passed to the API. We can offer a bank\nchecking API on a pay-per-use basis – please contact our Sales\nDepartment on `01206 675847` for further details on pricing. Failure to\nmodulus check data is likely to cause problems in processing your\npayments. **\n", "name": "Customer Manipulation" }, { "description": "Add custom fields to your customer data.", "name": "Customer Questions" }, { "description": "Although our documentation advises in most cases to lodge ad-hoc collections at least 5 working days before collection, and new contracts at least 10 working days before first collection, DDCMS can handle collections with these periods reduced to 3 and 5 working days respectively - depending on your SUN.\n\nIf you're testing on our playpen server, please send an email to us if you wish to reduce the period dates on your test account.\n\nIf you're a live customer and wish to discuss the possibility of reducing your SUN delay periods, please raise a support case.\n", "name": "Payment Dates" }, { "description": "A contract record represents the Direct Debit associated with a customer\nrecord. There are two forms of contract record:\n- **Ad-hoc:** This is where a Direct Debit is created at the bank for\n the customer, but no payments are requested unless you specifically\n input payments via the Payments or Bulk Payments API call.\n- **Scheduled:** In this mode, a schedule for payments is stated at\n the outset and the system will create the relevant payments in the\n database approximately five working days before the payments become\n due. Schedules can usually be weekly or monthly, however the\n frequencies available will be communicated to you when the API\n details are provided.\nCustomers can have multiple contracts attached to them in order that\nthey may have multiple payment streams being collected simultaneously.\n", "name": "Contract Querying and Creation" }, { "description": "Changing the payment amount or date on a scheduled contract can be\nachieved by using one of the following calls. You will need to select\nthe correct call for the type of contract that you are amending. For\nexample, changing the date on a monthly contract will need a monthly\ncall.\nWe have only shown the responses from one of the calls as all of the\ncalls respond in the same manner. One example of an error is shown,\nhowever you should be prepared to accept different errors and handle\nthem as exceptions during the testing stage.\n", "name": "Contract Amendment" }, { "description": "Managing frequencies on a future scheduled contract can be achieved \nusing the Frequency Switching API endpoints below. These endpoints allow \nfor dynamic adjustments to future contract schedules, including retrieving, \ncreating, editing, or deleting future schedules. By selecting the \nappropriate endpoint for the required action, users can efficiently manage \npayment frequencies, ensuring automated and accurate handling of future \ncontract schedules without manual intervention.\n", "name": "Frequency Switching" }, { "description": "It is important to understand that there are two parts to a contract;\nthe schedule which creates payments and the Direct Debit which collects\nthose payments. By running the following call against the contract, the\nDirect Debit is cancelled which will stop the system from sending\n**scheduled** payments to the bank for collection. They will still be\ncreated within the system, however they will not be sent to the bank and\nwill contribute to customer arrears.\n**NOTE:** This function will **not** affect ad-hoc payments which will\nbe sent regardless of the direct debit status. To prevent ad-hoc\npayments from being sent to the bank, they must *be deleted\nindividually*.\n", "name": "Cancelling the Direct Debit (Does not cancel payment creation)" }, { "description": "Archiving a contract achieves four things:\n- It cancels the direct debit.\n- Writes off any arrears that is outstanding on the contract.\n- Cancels any future scheduled payments (it does not cancel ad-hoc\n payments).\n- Sets the contract status to “archived”.\n", "name": "Archiving a Contract" }, { "description": "Reactivating a Direct Debit takes a contract that is in the cancelled\nstate and changes it to “Pending to Activate”. This sends a new\ninstruction to the bank to re-set up the direct debit. A “new 0N” charge\nwill be made for reactivating a direct debit.\n", "name": "Reactivating a Direct Debit" }, { "description": "Restarting a contract is fundamentally different to reactivating a\ncontract as it can only be performed if two criteria have been met:\n- The original contract was a fixed term contract which has “Expire”\n as its “atTheEnd” parameter.\n- The payment schedule has come to a natural end **and** the contract\n status has changed to “Expired”.\nThis call adds a new contract onto the end of the previous contract, in\neffect “recycling” the previous direct debit at the bank which can save\non direct debit set up charges.\nThis call cannot be used unless both of the two criteria above have been\nmet, otherwise unexpected results may occur.\n", "name": "Restart a Contract" }, { "name": "Patches", "description": "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.\nWe offer four different types of patches:\n - `Change amount`\n - `Freeze collect (leave contract as is)`\n - `Give notice (terminate contract)`\n - `Skip collection`\n\nPlease 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.\n" }, { "name": "Adding/Querying Payments" }, { "description": "We will send the payment creation API responses to your configured 'bulk payments' webhook - please see the Return Endpoints section for setting this.\n", "name": "Bulk Adding Payments" }, { "name": "Payment Manipulation" }, { "name": "Obtaining Available Schedules" }, { "description": "Import BACS payment files via the API for processing through DDCMS Direct. The client must have the DDCMS Direct feature enabled.\n", "name": "DDCMS Direct File Import" }, { "description": "Configurable Represents lets you control how failed Direct Debit payments are automatically retried, and lets you manually trigger a re-presentation for a specific failed payment.\n\nThese three endpoints allow you to retrieve and update your retry settings, and to trigger a re-presentation for a specific payment programmatically.\n", "name": "Configurable Represents" }, { "description": "If you have provided us with a return endpoint using the `Return\nEndpoint` call, data will be posted back to you either in XML or JSON as\nrequired. The default is JSON – if you need XML return information,\nplease let us know.\n\nWe 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.\n### Object Change Return Information\n#### Example JSON Payload\nThis is for an ADDACS change – where a customer has cancelled their\nDirect Debit with the bank.\n```json\n{\n \"NewStatus\": \"Cancelled\",\n \"Id\": \"ac190e35-2fa7-162c-8505-18702c186a43\",\n \"ChangeDate\": \"2017-05-09T10:20:10\",\n \"Entity\": \"contract\",\n \"ChangeType\": \"BACS\",\n \"Source\": \"ADDACS\",\n \"ReportCode\": \"1\",\n \"ReportMessage\": \"Contract Cancelled because of ADDACS code 1 (Instruction Cancelled)\",\n \"Comment\": \"Auto-updated by BACS file\"\n}\n```\n#### Example XML Payload\nThis is for an ARUDD change when a customer’s payment has been returned\nunpaid by the bank.\n```xml\n\n Unpaid\n f6dc0f34-1a71-4493-a0af-2f0993f36dc5\n 2017-05-09T12:17:50\n payment\n BACS\n ARUDD\n 0\n The payment marked as 'Unpaid' because of ARUDD code 0 (Refer to Payer)\n Auto-updated by BACS file\n\n```\n#### Output Parameters:\n| **Parameter** | **Description**\n| ------------- | ---------------\n| AccountName | If the Entity type is customer, the customers name as it appears on their bank account.\n| AccountNumber | If the Entity type is customer, the customers bank account number.\n| SortCode | If the Entity type is customer, the bank sort code of the customer.\n| 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
\n| Id | The GUID of the object being reported on.\n| ChangeDate | The date/time that the change took place.\n| Entity | The entity type: either payment, contract or customer.\n| ChangeType | BACS or Manual depending on how the change came about.\n| Source | ADDACS, ARUDD, DDIC or Manual depending on the source if the change.\n| 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.\n| ReportMessage | Plain text explanation of the change. We recommend this is logged at your end for reference.\n| Comment | If any comment was input by a user during a manual change, it will appear here.\n\n### Object Change Report Codes\n\nThe 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](https://access-support.force.com/Support/s/article/Access-PaySuite-DDCMS-Guide-to-BACS-Reporting-and-Associated-Transaction-Codes)\n\n| **Source** | **Entity** | **ReportCode** | **ReportMessage**\n| ---------- | ---------- | -------------- | -----------------\n| AUDDIS | Contract | 1 | Instruction Cancelled by Payer\n| AUDDIS | Contract | 2 | Payer Deceased\n| AUDDIS | Contract | 3 | Account Transferred to a new Bank or Building Society\n| AUDDIS | Contract | 5 | No Account\n| AUDDIS | \\- | 6 | No Instruction\n| AUDDIS | Contract | B | Account Closed\n| AUDDIS | Customer | C | Account Transferred to a Different Branch of Bank/Building Society\n| AUDDIS | Contract | F | Invalid Account Type\n| AUDDIS | Contract | G | Bank will not accept Direct Debits on Account\n| AUDDIS | Contract | H | Instruction has Expired\n| AUDDIS | Contract | I | Payer Reference is not Unique\n| AUDDIS | Contract | K | Instruction Cancelled by Paying Back\n| ADDACS | Contract | 0 | Instruction Cancelled - Refer to Payer\n| ADDACS | Contract | 1 | Instruction Cancelled\n| ADDACS | Contract | 2 | Payer Deceased\n| ADDACS | Customer | 3 | Account transferred to new Bank or Building Society\n| ADDACS | Contract | B | Account Closed\n| ADDACS | Customer | C | Account transferred to a different branch of Bank or Building Society\n| ADDACS | Contract | D | Advance Notice Disputed\n| ADDACS | Customer | E | Instruction Amended\n| ADDACS | Contract | R | Instruction Reinstated\n| ARUDD | Payment | 0 | Refer to Payer\n| ARUDD | Payment | 1 | Instruction Cancelled\n| ARUDD | Payment | 2 | Payer Deceased\n| ARUDD | Payment | 3 | Account Transferred\n| ARUDD | Payment | 4 | Advance Notice Disputed\n| ARUDD | Payment | 5 | No Account\n| ARUDD | Payment | 6 | No Instruction\n| ARUDD | Payment | 7 | Amount Differs\n| ARUDD | Payment | 8 | Amount Not Yet Due\n| ARUDD | Payment | 9 | Presentation Overdue\n| ARUDD | Payment | A | Service User Differs\n| ARUDD | Payment | B | Account Closed\n| DDIC | Contract | 1 | The amount and/or date of the Direct Debit differs from the Advance Notice\n| DDIC | Contract | 2 | No advance notice was received by the payer or the amount quoted is disputed by the payer\n| DDIC | Contract | 3 | DDI cancellation by the paying bank\n| DDIC | Contract | 4 | Payer has cancelled the DDI direct with the Service User\n| DDIC | Contract | 5 | Payer disputes having given authority\n| DDIC | Contract | 6 | Signature on DDI is fraudulent or not in accordance with the account authorised signature(s) held by the paying bank\n| DDIC | Contract | 7 | An indemnity claim has been raised at the Service User's request\n| DDIC | Contract | 8 | Payer does not recognise Service User collecting Direct Debit\n\n### New Payment Generated Notification Information\nThis 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.\n\nCurrently 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.\n#### Example JSON Payload\n```json\n{\n \"CustomerId\": \"8e8880dc-d36a-500e-9757-dcdab7418f8a\",\n \"CustomerRef\": null,\n \"ContractId\": \"bca883a2-e939-44ff-b3f0-9823°00dd388\",\n \"DirectDebitRef\": \"ABC-XY009999\",\n \"DateAdded\": \"2021-02-19T11:22:26.7662254+00:00\",\n \"DateDue\": \"2021-03-01T00:00:00\",\n \"Amount\": 49.7,\n \"Comments\": null,\n \"Id\": \"59cde7d8-1a81-4da3-b04f-10e71020ed74\",\n \"Entity\": \"payment\",\n \"CreateType\": \"BACS\",\n \"Source\": null,\n \"Status\": \"Pending\"\n}\n```\n### New eDD Signup Notification Information\nThis 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.\n\nThis 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.\n\nCurrently 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.\n```json\n{\n \"CustomerId\": \"e4e9bdad-4370-4072-ad4f-77454a42d839\",\n \"AdditionalRef\": \"My Additional Ref\",\n \"DirectDebitReference\": \"ABC-XY123456\",\n \"ScheduleName\": \"Monthly\",\n \"Description\": \"Monthly > Every 1 month > Day chosen by customer starting on any month (customer's choice) > Until further notice > Switch to further notice\",\n \"PaymentMonthInYear\": 4,\n \"PaymentDayInMonth\": 15,\n \"PaymentDayInWeek\": null,\n \"Start\": \"2023-04-15T00:00:00\",\n \"TerminationDate\": null,\n \"TerminationType\": \"Until further notice\",\n \"NumberOfDebits\": null,\n \"InitialAmount\": null,\n \"ExtraInitialAmounts\": \"\",\n \"Amount\": 15,\n \"FinalAmount\": null,\n \"Every\": 1,\n \"IsGiftAid\": true,\n \"AtTheEnd\": \"Switch to further notice\",\n \"Status\": \"Creation Pending\",\n \"StatusExplanation\": \"\",\n \"Id\": \"6062addf-768c-40d6-af08-e8e4e32d7c80\",\n \"Entity\": \"contract\",\n \"CreateType\": \"API\",\n \"Source\": null\n}\n```\n### Bulk Payment Insert Return Information\nThis is what the API returns from a bulk payment insert - see the *Bulk Adding Payments* section for more info.\n#### Example XML Payload - Successful Insert\n```xml\n\n 07024c7a-c31c-46c1-8e0e-8fcff640b35c\n 15.99\n 2017-06-01T00:00:00\n 1522c59f-87dc-4b31-9931-a6083776f670\n \n Successful Payment Example\n false\n \n\n```\n#### Example XML Payload - Error\n```xml\n\n 07024c7a-c31c-46c1-8e0e-8fcff640b35c\n 15.99\n 2017-06-01T00:00:00\n 00000000-0000-0000-0000-000000000000\n Contract not found - Invalid Contract Id\n Failed Payment Example\n false\n \n\n```\n#### Example JSON Payload - Successful Insert\n```json\n{\n \"Contract\":\"07024c7a-c31c-46c1-8e0e-8fcff640b35c\",\n \"Amount\":15.99,\n \"DueDate\":\"2017-06-01T00:00:00\",\n \"Id\":\"23bc8558-51cd-4c4e-b223-260010c69d38\",\n \"Error\": null,\n \"Comment\": \"Successful Payment Example\",\n \"IsCredit\": false,\n \"Message\": null\n}\n```\n#### Example JSON Payload - Error\n```json\n{\n \"Contract\":\"07024c7a-c31c-46c1-8e0e-8fcff640b35c\",\n \"Amount\":15.99,\n \"DueDate\":\"2017-06-01T00:00:00\",\n \"Id\": \"00000000-0000-0000-0000-000000000000\",\n \"Error\": \"Contract not found - Invalid Contract Id\",\n \"Comment\": \"Failed Payment Example\",\n \"IsCredit\": false,\n \"Message\": null\n}\n```\n#### Output Parameters:\n| Parameter | Description\n| --------- | -----------\n| Contract | The Contract GUID that the payment has been added to.\n| Amount | The amount of the payment.\n| DueDate | The due date of the payment.\n| Id | The payment GUID that you should keep a record of. If the request fails, this will be `00000000-0000-0000-0000-000000000000`\n| Error | Any validation errors will appear here.\n| Comment | The custom comment passed in for this payment request.\n| IsCredit | Whether the payment is a credit (`True`) or debit (`False`) collection.\n| Message | Any validation messages or warnings will appear here.\n\n### Schedule Change Return Information\nThe 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.\n#### Example JSON Payload\n```json\n{\n \"Entity\": \"schedule\",\n \"Id\": \"94821c14-8ba3-483f-a9db-02af004d9938\",\n \"Schedule\": {\n \"ScheduleId\": \"94821c14-8ba3-483f-a9db-02af004d9938\",\n \"Name\": \"yyy\",\n \"Description\": \"Weekly > Every 1 week > Week day chosen by customer starting on any month (customer's choice) > First , then on a regular basis\",\n \"AllowDifferentFirstPayment\": false,\n \"AllowDifferentLastPayment\": false,\n \"AllowFreeMonthDaySelection\": true,\n \"AllowFreeMonthSelection\": true,\n \"AllowFreeWeekDaySelection\": true,\n \"Amount\": null,\n \"AtTheEnd\": \"Expire\",\n \"DayOfWeek\": \"Free\",\n \"DaysOfMonth\": \"Free\",\n \"Every\": 1,\n \"ExpectedNumberOfPayments\": null,\n \"ExtraInitialPayments\": \"\",\n \"FinalAmount\": null,\n \"Frequency\": \"Weekly\",\n \"InitialAmount\": null,\n \"IsExpiryDateReached\": false,\n \"IsNotScheduled\": false,\n \"IsSuspended\": false,\n \"MonthOfYear\": \"Free\",\n \"RegistrationCharge\": 0.0,\n \"Start\": null,\n \"StartType\": \"As soon as possible\",\n \"TerminationDate\": null,\n \"TerminationType\": \"Until further notice\"\n },\n \"ParentService\": {\n \"Title\": \"Default Service\",\n \"RefProtocol\": \"Auto-number\",\n \"RefPrefix\": \"DEF\",\n \"RefFrom\": null,\n \"RefTo\": null,\n \"Schedules\": null\n },\n \"ParentClient\": {\n \"Id\": \"da550c70-b879-4e89-b918-00f8ecb4d703\",\n \"Name\": \"The Waffle Factory\",\n \"ClientPrefix\": \"WF\"\n },\n \"ChangeDate\": \"2021-08-12T08:04:38\",\n \"OperationTypeVal\": 1,\n \"OperationType\": \"Create\"\n}\n```\n#### Output Parameters:\n| Parameter | Description\n| --------- | -----------\n| Entity | Returns 'schedule'.\n| Id | The schedule's database GUID.\n| Schedule | Details of the affected schedule - see the *Obtaining Available Schedules* section for more info.\n| Parent Service | Details of the service which the schedule belongs to - see the *Obtaining Available Schedules* section for more info.\n| 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.\n| Change Date | Date-time for when the action took place.\n| Operation Type Val | Integer value for the OperationType enum.\n| Operation Type | Action performed on the schedule - can be **Create**, **Update** or **Delete**.\n", "name": "Return endpoints" } ], "x-components": {} }