This page provides key information relating to our API (Application Programming Interface) and how it works.
What is an API? – Quite simply an API is a link from one database to another and passing information requests between the two databases or in this case software applications.
What can our API be used for?- Our API is used to allow other software providers to submit customer and payment information to our Payment gateway. It does this to allow for a simple process for new customers to sign up via a third party application. We then pass certain validation on the information without the need for the third party to directly key information via our platform.
How to get started
Our API has 5 core endpoints, and these are
Customers
Bank Accounts
Mandates
Subscriptions
Payments
Each of these endpoints has information fields within them can be passed and some are required. The flow of the endpoints can work in a number of ways but the typical scenario is a Customer is added then a Bank account is added then a mandate at which point you then set up a subscription or payment to be collected.
When you are looking to connect with ourselves you will need to request and authentification key and if you are using our API for multiple clients/customers each account would require a unique key.
Customer End Point:
The customer is the person whom the account is linked too and typically the bank account holder. The object of the customer endpoint is noted below.
| Property | Type | Description |
| “address_Line1”: | “string”, | This is the 1st line of the customer’s address |
| “address_Line2”: | “string”, | This is the 2nd line of the customer’s address |
| “address_Line3”: | “string”, | This is the 3rd line of the customer’s address |
| “city”: | “string”, | This is the city or region of the customer’s address |
| “postal_Code”: | “string”, | The postal address of the customer |
| “email”: | “string”, | This is the email address of the customer |
| “first_Name”: | “string”, | This is the first name of the customer |
| “surname_Name”: | “string”, | This is the surname / last name of the customer |
| “metadata”: | “string”, | You will also be able to send some additional metadata |
| “mobile_Number”: | “string”, | This is the mobile number of the customer |
| “land_Number”: | “string”, | This is the landline of the customer |
| “status”: | “string”, | This is the status of the customer |
Bank Account End Point
The bank account for the customer is the next endpoint for setting up payments.
| Property | Type | Description |
| “account_Holder_Name”: | “string”, | This the name that has been given to the account |
| “account_Number”: | “string”, | This is the 8 digit UK account number |
| “branch_Code”: | “string”, | This is the 6 digit sort code |
| “bank_Name”: | “string”, | This is bank for which the customer holds an account with |
| “customer_Id”: | “string”, | This is the Customer ID number that has been generated from the previous customer end point |
| “status”: | string”, | This is the status of the customer |
Mandates End Point
A mandate is an electronic advice and identifier that is linked to the customer’s bank account, this enables payments to be taken.
| Property | Type | Description |
| “reference”: | “string”, | This is the reference that has been generated and that will be placed and lodged with the customer’s account. This is usually a combination made up like this 999/12345/001. |
| “metadata” | “string”, | You will have the ability to add additional metadata. |
| “next_Possible_Charge_Date”: | “string”, | This is the next possible date that a payment could be processed not necessary when it will be. |
| “customerMandateStatus”: | 0, | A mandate goes through some stages before it is live or ultimately cancelled |
| “customer_Bank_Account_Id”: | “string”, | This is the ID number that has been generated from adding a bank account from the accounts endpoint. |
| “status”: | “string”, | This is the status of the customer |
Subscriptions Endpoint
A subscription is where an agreed and continuous payment is to be requested. For example the 1st of each month at £30 per month for 12 months.
| Property | Type | Description |
| “amount”: | 0, | This is the consistent amount/value that is to be charged. |
| “count”: | 0, | This confirms how many payments are to be collected. |
| “day_Of_Month”: | “string”, | This confirms the day of each month the payment will be debited. |
| “status”: | 0, | This is the status of the customer |
Payments End Point
This endpoint is used for singular payments or one-offs or where the clients choose to manually add payments and differing frequency and value.
| Property | Type | Description |
| “amount”: | “string”, | This is the consistent amount/value that is to be charged. |
| “description”: | “string”, | This is the name of the subscription sometimes called the package or membership type. |
| “metadata”: | “string”, | This is where you have the ability to include additional data. |
| “customerPaymentStatus”: | 0, | This is to indicate if the payment has been successful |
| “status”: | 0, | This is the status of the customer |
| “mandate_Id”: | “string”, | A payment/subscription must be assigned to a mandate. |
More information on the Direct Debit process
The Direct Debit scheme is managed on a set on standards and timings that each authorised provider agrees too. The setting up of a mandate requires a minimum of 4 working days this combined with a payment request is 8 working days. Best practise is that 8 working days are required to formally set up and lodge payment with the customer’s bank.
The process of setting up a mandate will go through certain validation checks to ensure the banking account details are correct and this is done via a modules check. Our API will instantly confirm if the details will be accepted. The API will also pass back an ID for each of the endpoints. Depending on how your system is being used and how customers are setting up payment will mean that an end customer requires advance notice of at least 3 working days before the payment is due to leave there account. From our side, we will email the end customer to confirm a mandate is set up and also an advance notice confirming the frequency and value of the debit. However, any commitment that an end customer is agreeing too needs to confirmed via your application or from a paper-based agreement.
Once payment has been lodged whether this is on an individual basis or via the subscription we are unable to stop any payment so it worth making this point within your system so you client can understand the payment has been processed.