Quickstart

From zero to a Direct Debit collection on the playpen sandbox.

This page walks through one complete collection as a sequence of API calls, in the order you would make them: create a customer, put them on a schedule, set up the Direct Debit, take a payment and check its outcome.

Get playpen access

You need a playpen API key. Contact our sales team to get one.

The examples below run against the playpen base URL, https://playpen.accesspaysuite.com/api/v3 — see Environments for that and the production one. Replace the LUISCT client code in each path with your own (also called the client prefix), and the customer, contract and payment GUIDs with the ones your own calls return.

Every request carries your key in an apiKey header, not an Authorization header and not a query parameter:

apiKey: xAQdXTPtZPG3QqsUJw73wx1o
Accept: application/json
Content-Type: application/json

The API accepts input as a JSON body or as x-www-form-urlencoded — either query string or form body — and the Accept header selects JSON or XML for the response. See Authentication and API Technical Details.

How the pieces fit together

Direct Debit has four core objects, and they nest in this order:

Customer  ──has many──▶  Contract  ──has many──▶  Payment
                            │
                            └── follows a ──▶ Schedule

Step 1 — Find the schedules on your account

Because you do not create schedules, the first job is to see which ones your client already has. The response lists your services and the schedules underneath each of them.

Step 2 — Create a customer

Now create the person you will collect from. customerRef is your own reference and must be unique within your client; accountNumber and bankSortCode are the customer's bank details, digits only with leading zeros intact.

Step 3 — Create the contract

This registers the Direct Debit mandate with the customer's bank. It hangs off the customer Id from step 2 and points at a schedule from step 1 — identified by either scheduleName or scheduleId.

Step 4 — Check the earliest date you can collect

Rather than reproduce the working-day arithmetic, which has to skip weekends and UK bank holidays, ask the API. It returns the earliest first collection date and the earliest subsequent collection date currently allowed by your SUN.

Step 5 — Take a payment

Now collect against the contract Id from step 3. Amount and Date are required, and the date must be on or after the earliest date from step 4.

Step 6 — Check what happened

You can list the payments held against a contract at any time. They come back most recent first; rows sets how many you get, up to 100.

A payment moves through roughly this lifecycle:

Pending ──▶ Paid
   │
   └──(returned unpaid by the bank)──▶ Represented / Unpaid

While a payment is still Pending you can amend or delete it; once it has been submitted to the bank it can no longer be changed.

Next steps

• The Direct Debit Process — how instructions and collections flow through BACS.
• Payment Manipulation — query, amend or delete a payment that has not been submitted.
• Patches — skip, freeze or change the amount of a contract's collections between two dates.
• Return Endpoints — register a callback so DDCMS tells you when payments and mandates change state, instead of polling step 6.
• Frequency Switching — move a contract onto a different collection pattern.
• Errors — the error envelope and what the status codes mean.