Direct Debit Guide: Facilities Management API Technical Implementation Manual

Contents

What is Direct Debit (DD) API?

• Important information about DD API
  • Request Structure
  • Base64 Encoding
  • API Call Types (REST)
  • Authentication

Validation

• Valid Requests
• Invalid Requests

API Request Summary

• Create Mandate
  • Create Mandate with Payment Schedule
  • Create Mandate without Payment Schedule
• Create Variable Mandate
  • Create Variable Mandate with Payment Schedule
  • Create Variable Mandate without Payment Schedule
• Edit Mandate Details
  • Edit allpay account holder details
  • Edit bank account holder details
  • Edit email address
  • Edit mobile number
  • Delete bank account holder details
  • Delete email address
  • Delete mobile number
• Add Immediate Payment Schedule
• Add Payment Schedule to an existing mandate
• Add Payment Schedule to an existing variable mandate
• Add Annual Renewal Schedule
• Retrieve Mandate Information
  • Retrieve account holder details
  • Retrieve account holder details using DD reference
  • Retrieve bank account holder details
  • Retrieve unverified email addresses
  • Retrieve correspondence history
  • Retrieve account holder details for a scheme code
• Retrieve Schedule Components
• Retrieve Payment Schedule
• Remove Schedule Components
• Show Previous Collection History
• Close Mandate
• Retrieve Failed Payments
• Modulus Check
  • Modulus Check Scenarios
• Sort Code Lookup

API Validation Rules

Example API Request Details

• Create Mandate: POST
  • Create mandate with payment schedule
  • Create mandate without payment schedule
  • Create variable mandate with payment schedule
  • Create variable mandate without payment schedule
• Edit Mandate Details
  • Edit allpay Account Holder Details: PUT
  • Edit Bank Account Holder Details: PUT
  • Edit Email Address: PUT
  • Edit Mobile Number: PUT
• Immediate Payment Schedule: PUT
  • Immediate Renewal Payment Schedule (Suppress Notification)
• Add Payment Schedule
  • Add Payment Schedule: POST
  • Add Variable Payment Schedule: POST
  • Add Renewal Payment Schedule: POST (Suppress Notification)

API Error Codes

What is Direct Debit (DD) API?

The allpay Direct Debit Application Programming Interface (API) is a set of methods to allow allpay’s clients to Create, Edit and Retrieve Direct Debit related information programmatically.

Important information about DD API

Request Structure

In order for an API call to be successful, the request URL will need the following generic structure:

https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 encoded Client Reference>/<base64 encoded Surname>

Any other information required in the request URL is dependent on the type of API call being made, see API Request summary.

The API request header must contain:

Authorization: Bearer <API authorization token>
Content-Type: application/json

See Authentication for further details

Base64 Encoding

As it is possible for allpay Client References and Surnames to include characters that are not allowed in URLs, the Client Reference and Surname need to be provided in Base64 encoded format in order for the API call to be successful.

API Call Types (REST)

Authentication

DD enabled schemes set up for DD APIs will require an API authentication token. The API token is a GUID and will be provided by allpay and can be per Scheme Code or per Organisation. This authentication token is needed in the API request header in the format:

Authorization: Bearer <API authorization token>

Any API calls using an invalid or non-existent API token will not be successful and will result in HTTP 401: Unauthorized error message.

Validation

Valid Requests

Valid requests will result in a HTTP 200 OK response message.

This response message will include the Scheme Code, Client Reference and Surname.

Example:

Invalid Requests

Invalid requests will result in a variety of HTTP responses.

For HTTP 422 responses (Unprocessable Entity) the body of the JSON response will contain “Error=true” and one or more validation messages detailing the issue e.g.:

API Request summary

FM Script Call

To conform with Bacs regulations this API request must be used and read to the customer for each new mandate created.

The API call which fetches the script will be read out to customers takes a POST request with a JSON body.

Assuming the request is valid, it will return a JSON array of strings. The scheme code is to be provided in the URL as follows for the test environment:

https://ddtest.allpay.net/AllpayAPI/Mandates/{SCHEMECODE}/GetScript

A valid Facilities Management client code that is enabled for DD API usage must be supplied at minimum. If a request is made with no DD schedule information, you will receive the generic version of the script, and you will have to fill in the dates/amounts etc yourself.

If you supply both the initial and subsequent schedule information as well as the bank account account number and sort code, the API will automatically fall back to hard coded generic version of the script.

Script Examples

Request with a non-API Enabled Client Code.

Response:

["The provided scheme code is not enabled for use with the DD API"]

Request for a non-FM API Enabled Client Code:

["The provided scheme code is not FM enabled"]

Request with an empty body for an FM API Enabled Client Code:

{
}

Response

[
"To avoid delay and to save you having to fill in any paperwork, I can set up your Direct Debit right now. Would that be helpful?",
"The initial payment of [Amount] will come out of your account on the [Date]. Further payments will be made of [Amount] on [Date] and every [frequency] thereafter.",
"ALLPAY LIMITED will appear on your bank statement against the Direct Debit.",
"That completes the set-up of your Direct Debit instruction with us. You will receive written confirmation of this within 3 working days. ",
"In future, if the payment dates, amount or frequency of your Direct Debit changes, we will give you 10 working days notice in advance of your account being debited.",
"In the event of any error, you are entitled to an immediate refund from your Bank or Building Society. You have the right to cancel at any time and this guarantee is offered by all the banks and building societies that take part in the Direct Debit scheme.A copy of this guarantee will be sent along with your confirmation. ",
"Finally, let me just confirm your account details back to you, account number [insert] sort code [insert]. Is that correct?"
]

Request for an FM API Enabled Client Code with DD Information supplied

{
    "Schedules": [
        {
            "ScheduleDate": "20-07-2023",
            "Amount": "4006",
            "Frequency": "1",
            "TotalPayments": 1
        },
        {
            "ScheduleDate": "27-07-2023",
            "Amount": "5583",
            "Frequency": "Month",
            "TotalPayments": 0
        }
],
    "BankAccount": {
        "BankDetails": {
            "SortCode": "40-22-25",
            "AccountNumber": "13852733"
        }
    }
}

Response

[
"To avoid delay and to save you having to fill in any paperwork, I can set up your Direct Debit right now. Would that be helpful?",
"The initial payment of £40.06 will come out of your account on the 20-07-2023. Further payments will be made of £55.83 on 27-07-2023 and every Month thereafter.",
"ALLPAY LIMITED will appear on your bank statement against the Direct Debit.",
"That completes the set-up of your Direct Debit instruction with us. You will receive written confirmation of this within 3 working days.",
"In future, if the payment dates, amount or frequency of your Direct Debit changes, we will give you 10 working days notice in advance of your account being debited.",
"In the event of any error, you are entitled to an immediate refund from your Bank or Building Society. You have the right to cancel at any time and this guarantee is offered by all the banks and building societies that take part in the Direct Debit scheme. A copy of this guarantee will be sent along with your confirmation.",
"Finally, let me just confirm your account details back to you, account number 13852733 sort code 40-22-25. Is that correct?"
]

Create Mandate

Create mandate is a single API call that is used to create a DD with or without a payment schedule. Details of each of the different calls can be found below:

Create Mandate with payment Schedule

The create mandate call comprises of allpay account holder details, payment schedule and bank account holder details.

Bank account holder address details only need to be provided if they are different from allpay account holder address details.

All current allpay portal validation rules apply (i.e. mandatory fields, field lengths and invalid character ranges)

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/Mandates/Create

Create Mandate without Payment Schedule

The create mandate can also be used to create a DD without a payment schedule. It uses the same call as create mandate but within the body you do not need to specify any payment details. The call will comprise of just the allpay account holder details and bank account holder details. The option to create a DD without a payment schedule is only available to schemes which have pre-schedule accounts enabled. If pre-schedule accounts are not enabled on the scheme the call will be rejected.

Bank account holder address details only need to be provided if they are different from allpay account holder address details.

All current allpay portal validation rules apply (i.e. mandatory fields, field lengths and invalid character ranges)

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/Mandates/Create

Create Variable Mandate

Create variable mandate is a single API call that is used to create a DD with or without a payment schedule. Details of each of the different calls can be found below.

Create Variable Mandate with Payment Schedule

The create variable mandate call comprises of allpay account holder details, payment schedule and bank account holder details.

This call is only available on schemes set up for variable Direct Debits.

For a variable mandate with a payment, the schedule consists of a payment date and payment amount only.

Bank account holder address details only need to be provided if they are different from allpay account holder address details.

All current allpay portal validation rules apply (i.e. mandatory fields, field lengths and invalid character ranges)

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/VariableMandates/Create

Create Variable Mandate without Payment Schedule

The create variable mandate can also be used to create a DD without a payment schedule. It uses the same call as create variable mandate but within the body you do not need to specify any payment details. The call will comprise of just the allpay account holder details and bank account holder details. The option to create a DD without a payment schedule is only available to schemes which have pre-schedule accounts enabled. If pre-schedule accounts are not enabled on the scheme the call will be rejected.

This call is only available on schemes set up for variable Direct Debits.

Bank account holder address details only need to be provided if they are different from allpay account holder address details.

All current allpay portal validation rules apply (i.e. mandatory fields, field lengths and invalid character ranges)

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/VariableMandates/Create

Edit Mandate Details

Edit mandate uses the PUT HTTP verb and consists of 3 individual calls.

Edit allpay account holder details

This is an edit to allpay account holder details. As per current functionality, if the bank account holder address details are currently using the allpay account holder address details, these changes will be reflected.

All current allpay portal validation rules apply to data posted in request body.

API URL format:

PUT https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>

Edit bank account holder details

This is an edit to bank account holder address details.

API URL format:

PUT https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccounts

Edit email address

This API call is used to add or update an email address on a Direct Debit.

API URL format

PUT https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccountEmail

Edit mobile number

This API call is used to add or update a mobile number on a Direct Debit.

API URL format:

PUT https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccountMobileNumber

Delete bank account holder details

This API call is to remove the bank account holder address details so that it is the same as the account details.

This will not remove any stored email address or mobile number.

API URL format:

Delete https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccounts

Delete email address

This API call is used to remove the email address from the Direct Debit.

API URL format:

Delete https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccountEmail

Delete mobile number

This API call is used to remove the mobile number from the Direct Debit.

API URL format:

Delete https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccountMobileNumber

Add Immediate Payment schedule

This API allows a user to add a new payment schedule to an existing mandate. Any currently collecting schedule will complete immediately. The API behaves slightly different to the allpay Portal as a user can now setup an ongoing payment without having to supply an initial payment. Also, it will replace any future schedules where the new schedule date clashes.

Payment schedules will need to be provided in date order, if the first schedule date is later than the second schedule date, HTTP/1.1 422 Unprocessable Entity will be returned.

All current allpay portal validation rules apply to data posted in request body.

API URL format (see Example API Request Details for body):

PUT https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates

Add Payment Schedule to an existing mandate

This API allows a user to add a new payment schedule to an existing mandate. Any existing currently collecting schedule will be interrupted by the new future schedule, but will not complete. The API behaves slightly different to the allpay Portal as a user can now setup an ongoing payment without having to supply an initial payment. Also, it will replace any future schedules where the new schedule date clashes. The following API call is used to add a payment schedule to an existing schedule. Note, for an add payment schedule we use the POST command whereas for the immediate payment schedule we use the PUT command.

Payment schedules will need to be provided in date order, if the first schedule date is later than the second schedule date, HTTP/1.1 422 Unprocessable Entity will be returned.

All current allpay portal validation rules apply to data posted in request body.

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates

Add Payment Schedule to an existing variable mandate

This API call allows a user to add a new payment schedule to an existing variable mandate. Only available on schemes set up for variable Direct Debits. Payment schedules will need to be provided in date order, if the first schedule date is later than the second schedule date, HTTP/1.1 422 Unprocessable Entity will be returned.

All current allpay portal validation rules apply to data posted in request body.

API URL format:

POST https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/VariableMandates

Add Annual Renewal Schedule

Adding an annual renewal schedule to a Direct Debit is done using the two add schedule calls listed above.

The ‘Add immediate payment’ (PUT) or ‘Add payment schedule’ (POST) calls can be used to add a renewal schedule (as they use the same request body). When adding the renewal schedule the “SuppressNotification” flag needs to be ‘1’ in the Request Body to ensure it will not result in a Renewal Amendment letter being printed by allpay.

When a “SuppressNotification flag” is ‘0’ or not provided in a schedule amendment call, a ‘normal’ schedule will be added (as per Edit Mandate Details & Add Immediate Payment schedule) and an amendment letter will be flagged for printing as per existing functionality.

Retrieve Mandate Information

Retrieve account holder details

API URL format: allpay Account Holder Details using a combination of scheme code, client reference and account holder surname

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>

Response: Allpay account Holder Details:

JSON
    - Address
        - County=
        - LastName=
        - Line1=
        - Line2=
        - PostCode=
        - TitleInitials=
        - Town=
    - ClientReference=
    - LastName=
    - SchemeCode=

Retrieve account holder details using DD reference

Note this call can be used when the client does not know the surname of the account holder so cannot use the previous API call. However, this call could potentially return more than one account as just the scheme code and DD reference is not a unique identifier.

API URL format: allpay account holder details using a combination of scheme code and DD reference.

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 DDReference>/Mandates

Response: Allpay Account Holder Details

JSON
    - Mandates
        - Address
            - Line1=
        - Bank details
            - AccountNumber=
            - SortCode=
        - DDReference=
        - LastName=
        - MandateState=
        - SchemeCode=
    - TotalRecords=

Retrieve account holder details using DD reference

Note this call can be used when the client does not know the surname of the account holder so cannot use the previous API call. However, this call could potentially return more than one account as just the scheme code and DD reference is not a unique identifier.

API URL format: allpay account holder details using a combination of scheme code and DD reference.

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 DDReference>/Mandates

Response: Allpay Account Holder Details

JSON
    - Address
        - County=
        - LastName=
        - Line1=
        - Line2=
        - PostCode=
        - TitleInitials=
        - Town=
    - ClientReference=
    - LastName=
    - SchemeCode=

Retrieve bank account holder details

API URL format: Bank account holder details

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/BankAccounts

Response: Bank Account Holder

JSON
    - Address
        - County=
        - LastName=
        - Line1=
        - Line2
        - PostCode=
        - TitleInitials=
        - Town=
    - BankDetails
        - AccountName=
        - AccountNumber=
        - SortCode=
    - MandateState=

Retrieve unverified email addresses

This API call will return all email addresses that have not been verified against a specified scheme code. To run the API call the user supplies the scheme code, page number and page size. If the scheme is not setup for email notifications an error message will be displayed.

API URL format:

GET
https://<APIHost>/AllpayApi/Customers/GetUnverifiedEmailAddresses/?schemeCode=<SchemeCode>&pageNumber=<Page Number>&pageSize=<Page Size>

Response:

JSON
    - EmailAddress
        - {}
            - ClientReference=
            - Email=
            - LastName=
            - SchemeCode=
        - {}
            - ClientReference=
            - Email=
            - LastName=
            - SchemeCode=
        - TotalRecords=2

Retrieve correspondence history

This API call will return all customer correspondence (letter, email, SMS) based on the enabled notification types for a given live account. The user will need to pass in the client code, client reference, surname and a notification type to receive notifications that were sent to the account holder / bank account holder. If the account is closed an error message will be displayed.

There are three different notification types the API can return:

• AdvanceNotice - All correspondence regarding any new changes to the Direct Debit
• Payment - Any payments processed from the Direct Debit
• All - Both AdvanceNotice and Payment correspondence

API URL Format:

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Notifications/CorrespondenceHistory/<NotificationType>

Response:

JSON
    -Notifications
        - {}
            - Date= 24/10/2016
            - NotificationType=Email
            - Recipient= email.address@email.com
            - SchemeCode=CSDD
            - Status=Sent
            - Type=DD Amend
        - {}
            - Date=01/09/2016
            - NotificationType=Letter
            - Recipient=SMITH
            - SchemeCode=CSDD
            - Status=Printed
            - Type=DD Setup and Confirmation
        - {}
            - Date=28/08/2016
            - NotificationType=SMS
            - Recipient=07000000000
            - SchemeCode=CSDD
            - Status=Sent
            - Type=DD Failed Payment

Retrieve account holder details for a scheme code

API URL format: allpay Account Holder Details for a scheme code

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>?from=2023-02-11&to=2023-02-12

Response: Collection of Allpay Account Holder Details

JSON
{
[ {
    - Address
        - Line1=
        - LastName=
        - TitleInitials=
    - SchemeCode=
    - ClientReference=
    - LastName=
    - PRN=
  }
]
}

Retrieve Schedule Components

This API call retrieves the Scheduled Components for the live DD related to the account.

API URL format:

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/Schedule

For an ongoing currently collecting schedule, the response is in the format:

JSON
    - Schedules
        -{}
            - Amount=222
            - CollectionDay=7th
            - FirstPaymentDate=2016-02-08T00:00:00Z
            - Frequency=Monthly
            - NextPaymentDate=2016-06-07T00:00:00Z
            - PaymentsRequested=4
            - PreviousPaymentDate=2016-05-07T00:00:00Z
            - RemainingPayments=Ongoing
            - TotalPayments=Ongoing
    - TotalRecords=1

For a fixed term currently collecting schedule, the response is in the format:

JSON
    - Schedules
        -{}
            - Amount=5000
            - CollectionDay=29th
            - FinalScheduledPaymentDate=2016-10-31T00:00:00Z
            - FirstPaymentDate=2016-04-29T00:00:00Z
            - Frequency=Monthly
            - NextPaymentDate=2016-06-29T00:00:00Z
            - PaymentsRequested=2
            - PreviousPaymentDate=2016-05-29T00:00:00Z
            - RemainingPayments=5
            - TotalPayments=9
    - TotalRecords=1

For a future schedule (initial and subsequent), the response is in the format:

JSON
    - Schedules
        -{}
            - Amount=6000
            - CollectionDay=1st
            - FinalScheduledPaymentDate=2016-07-01T00:00:00Z
            - FirstPaymentDate=2016-07-01T00:00:00Z
            - Frequency=Once
            - RemainingPayments=1
            - TotalPayments=1
        -{}
            - Amount=12000
            - CollectionDay=1st
            - FirstPaymentDate=2016-08-01T00:00:00Z
            - Frequency=Monthly
            - RemainingPayments=Ongoing
            - TotalPayments=Ongoing
    - TotalRecords=2

Retrieve Payment Schedule

This API call retrieves up to the next 6 un-triggered payments due to be taken for the DD Mandate.

All current allpay portal validation rules apply to data posted in request body.

API URL format:

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/Payments

Response:

JSON
    - ClientReference=abc123
    - LastName=davies
    - Payments
        -{}
            - Amount=1
            - Frequency=Once
            - PaymentDate=2016-07-01T00:00:00Z
            - Type=Fixed
        -{}
            - Amount=100
            - Frequency=Monthly
            - PaymentDate=2016-10-31T00:00:00Z
            - Type=Fixed
        -{}
            - Amount=101
            - Frequency=Once
            - PaymentDate=2016-12-01T00:00:00Z
            - Type=Fixed
    - SchemeCode=ABCD
    - TotalRecords=3

Remove Schedule Components

This API call will delete a currently collecting or future payment schedule by specifying the first payment date and amount. If the API call cannot determine which schedule component to delete an error message will be returned to advise the user that they need to manually delete the component. API URL format:

DELETE https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/Schedule/<FirstPaymentDate yyyy-mm-dd>/<Amount in pence>

Response:

JSON
    - ClientReference=TESTREF01
    - LastName=SMITH
    - SchemeCode=WAHA

Show Previous Collection History

This API call retrieves up to the last 6 payments (including those triggered but not yet collected) for the allpay account number associated with the DD Mandate. As payments are retrieved based on allpay account number, the state and number of DD Mandates against this account does not impact the results returned.

The PaymentDate received in the response JSON is the Payment Due Date of the payment as shown in the allpay Portal.

API URL format:

GET https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/PaymentHistory

Response:

JSON
    - ClientReference=SO4497
    - LastName=jones-harris
    - Payments
        -{}
            - Amount=1625
            - PaymentDate=2015-11-16T00:00:00Z
        -{}
            - Amount=100
            - PaymentDate=2015-11-17T00:00:00Z
        -{}
            - Amount=101
            - PaymentDate=2015-11-18T00:00:00Z
    - SchemeCode=ABCD
    - TotalRecords=3

Close Mandate

Using ‘DELETE’ HTTP verb with any closure date provided in the format ‘YYYY-MM-DD’ will result in a closure of the mandate being created on the system. If the date provided is ‘today’s date’, this will result in an immediate closure. Where the date provided is in the future, this will result in a future closure being set up with the closure of the mandate being processed on the specified date.

API URL format:

DELETE https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/<YYYY-MM-DD>

To edit a future closure date, send another future closure request using a new future closure date to override the current one.

To remove a future closure date, send a closure request without a closure date, i.e.:

DELETE https://<APIHost>/AllpayApi/Customers/<SchemeCode>/<base64 ClientRef>/<base64 Surname>/Mandates/

Retrieve Failed Payments

This API call will return all failed payments for a scheme code at a given period of time.

The payments will be ordered by collection date (descending), reason code (ascending) and then by the amount in descending order. Only 6 records are displayed at one time along with the total number of records found. To display the records you will need to specify a page number so page 1 will show you the first 6, page 2 the next 6 and so on.

API URL format:

GET
https://<APIHost>/AllpayApi/Customers/<SchemeCode>/Mandates/FailedPayments/<From date yyyy-mm-dd>/<To date yyyy-mm-dd>/<Page number>

Response

JSON
    - FailedPayments
        -{}
            - Amount=202971
            - ClientReference=Y037477
            - CollectionDate=20/05/2016 00:00:00
            - IsRepresented=True
            - LastName=JONES
            - Line1=FLAT 2
            - ProcessedDate=26/05/2016 00:00:00
            - ReasonCode=BACS 0 : Refer to payer
            - SchemeCode=ESLP
        -{}
            - Amount=75000
            - ClientReference=Y035800
            - CollectionDate=20/05/2016 00:00:00
            - IsRepresented=False
            - LastName=MAXIM CONSULTANCY U
            - Line1=22 BOROUGH WAY
            - ProcessedDate=26/05/2016 00:00:00
            - ReasonCode=BACS 0 : Refer to payer
            - SchemeCode=ESLP
    - TotalRecords=2

Modulus Check

This API call does not require authentication or indeed a message header. The modulus check call takes a sort-code and account number as input parameters and returns bank details (if the sort-code is valid), whether the sort-code is Direct Debit or Direct Credit enabled and if the combination of sort-code and account number are valid.

API URL format:

GET
https://<APIHost>/AllpayApi/BankAccounts/?sortcode=<SortCode>&accountnumber=<AccountNumber>

Responses come in two forms:

16. Where the sort code and account number combination are invalid “Valid” will be displayed as “False”. (Note: “DirectDebitCapable” and “DirectCreditCapable” may be “True” for a sort code, but “Valid” will still be “false” due an invalid account number combination.

17. Where the sort code and account number combination are valid “Valid” will be displayed as “True”. In this instance, the bank address details for the account will also be returned.

JSON
    - AccountNumber=XXXXXXXX
    - Address
        - Fax=
        - Line1=Chelmsford Legg St OSC
        - Line2=1 Legg Street
        - Phone=0121 7411380
        - PostCode=CM1 1JS
        - Town=Chelmsford
    - Branch=1 QUEEN ST CARDIFF
    - BankName=LLOYDS TSB BANK PLC
    - DirectDebitCapable=True
    - DirectCreditCapable=True
    - SortCode=309691
    - Valid=True

Modulus Check Scenarios

1. Sort code and account number is a valid combination.

   When a valid sort code is combined with a valid account number the response will show this by setting the valid attribute to True. The bank details are also displayed as the sort code is valid.

JSON
  AccountNumber = xxxxxxx
    - Address
        - Fax=
        - Line1=40 Wakefield Road
        - Line2=
        - Phone=03456 100100
        - PostCode=LS98 1FD
        - Town=Leeds
    - BankName= HSBC BANK PL
    - Branch= FIRSTDIRECT LEEDS
    - DirectDebitCapable=True
    - DirectCreditCapable=True
    - SortCode=404784
    - Valid=True

2. Sort code and account number is an invalid combination (Sort code is valid).

   When a valid sort code is combined with an invalid account number the response will show this by setting the valid attribute to False. However, the bank details are still displayed as the sort code is valid.

JSON
  AccountNumber = xxxxxxx
    - Address
        - Fax=
        - Line1=40 Wakefield Road
        - Line2=
        - Phone=03456 100100
        - PostCode=LS98 1FD
        - Town=Leeds
    - BankName= HSBC BANK PL
    - Branch= FIRSTDIRECT LEEDS
    - DirectDebitCapable=True
    - DirectCreditCapable=True
    - SortCode=404784
    - Valid=False

3. Sort code is invalid.

   When the sort code is invalid and is combined with an account number the response will show this by setting the valid attribute to False. No bank details are displayed and will show DirectDebitCapable and DirectCreditCapable as False.

JSON
  AccountNumber = xxxxxxx
    - DirectDebitCapable=False
    - DirectCreditCapable=False
    - SortCode=938999
    - Valid=False

4. Sort code does not exist

When the sort code does not exist in our database and is combined with an account number the response will show this by setting the valid attribute to True. This may look confusing, but at the time the API call is run we cannot be sure if the combination is valid so it is shown as a valid combination. Note, because the sort code does not exist in our database no bank details are displayed and will show DirectDebitCapable and DirectCreditCapable as False.

JSON
  AccountNumber = xxxxxxx
    - DirectDebitCapable=False
    - DirectCreditCapable=False
    - SortCode=444444
    - Valid=True

Sort Code Lookup

This API call is similar to the modulus check, except no account number needs to be provided.

API URL format:

GET https://<APIHost>/AllpayApi/BankAccounts/?sortcode=000000

This sort code API is used to return the bank name, branch name, address and whether the sort code is Direct Credit and Direct Debit enabled. If the sort code supplied is invalid the valid field returned will be set to false.

A valid response:

JSON
    - Address
        - Fax=
        - Line1=130-132 Cumbernauld Rd
        - Line2=MUIRHEAD
        - Phone=0141 779 2175
        - PostCode=G69 9DY
        - Town=Glasgow
    - BankName=AIRDRIE SAVINGS BANK
    - Branch=GLASGOW ,MUIRHEAD
    - DirectDebitCapable=True
    - DirectCreditCapable=True
    - SortCode=803606
    - Valid=True

An invalid response:

JSON
    - DirectDebitCapable=False
    - DirectCreditCapable=False
    - SortCode=454545
    - Valid=False

API Validation Rules

Schedules

Address

• All mandatory data fields must contain data
• Empty string fields should be sent as " "
• No field should exceed its maximum length
• All API requests must adhere to their structure defined in API Request Details

• JSON string entries of " or \ must be preceeded by the backslash escape (\) i.e.

  "ClientReference": "\"abc\\123\"" would be stored as "abc\123"

• Identical PUT or POST calls should not be submitted concurrently; an attempt to do this could result in data duplication

Example API Request Details

Create Mandate: POST

Create mandate with payment schedule:

{
    "Customer": {
        "MobileNumber": "07700900000",
        "Email": "test@test.com",
        "TitleInitials": "MR A",
        "Address": {
            "Line1": "123 Anystreet",
            "Line2": "Test",
            "Town": "AnyTown",
            "County": "test",
            "PostCode": "AB12 3CD"
        },
        "SchemeCode": "TEST",
        "ClientReference": "121002D",
        "LastName": "Smith"
    },
    "Schedules": [{
        "ScheduleDate": "2016-05-29",
        "Amount": 16000,
        "Frequency": "M",
        "TotalPayments": 0
    }],
    "BankAccount": {
        "BankDetails": {
            "AccountName": "Mr Account",
            "SortCode": "666666",
            "AccountNumber": "66666666"
    },
    "Address": {
        "TitleInitials": "Mr",
        "LastName": "Account",
        "County": "A County",
        "Line1": "test line 1",
        "Line2": "test line 2",
        "Town": "My Town",
        "PostCode": "My Postcode"
        }
    }
}

Create mandate without payment schedule:

{
    "Customer": {
        "MobileNumber": "07700900000",
        "Email": "test@test.com",
        "TitleInitials": "MR A",
        "Address": {
            "Line1": "123 Anystreet",
            "Line2": "Test",
            "Town": "AnyTown",
            "County": "test",
            "PostCode": "AB12 3CD"
        },
        "SchemeCode": "TEST",
        "ClientReference": "121002D",
        "LastName": "Smith"
},
"BankAccount": {
    "BankDetails": {
        "AccountName": "Mr Account",
        "SortCode": "666666",
        "AccountNumber": "66666666"
    },
    "Address": {
        "TitleInitials": "Mr",
        "LastName": "Account",
        "County": "A County",
        "Line1": "test line 1",
        "Line2": "test line 2",
        "Town": "My Town",
        "PostCode": "My Postcode"
        }
    }
}

Create variable mandate with payment schedule:

{
    "Customer": {
        "MobileNumber": "07700900000",
        "Email": "test@test.com",
        "TitleInitials": "MR A",
        "Address": {
            "Line1": "123 Anystreet",
            "Line2": "Test",
            "Town": "AnyTown",
            "County": "test",
            "PostCode": "AB12 3CD"
        },
        "SchemeCode": "TEST",
        "ClientReference": "121002D",
        "LastName": "Smith"
    },
    "Schedules": [{
        "ScheduleDate": "2016-05-29",
        "Amount": 16000
    }],
    "BankAccount": {
        "BankDetails": {
            "AccountName": "Mr Account",
            "SortCode": "666666",
            "AccountNumber": "66666666"
        },
        "Address": {
            "TitleInitials": "Mr",
            "LastName": "Account",
            "County": "A County",
            "Line1": "test line 1",
            "Line2": "test line 2",
            "Town": "My Town",
            "PostCode": "My Postcode"
        }
    }
}

Create variable mandate without payment schedule:

{
    "Customer": {
        "MobileNumber": "07700900000",
        "Email": "test@test.com",
        "TitleInitials": "MR A",
        "Address": {
            "Line1": "123 Anystreet",
            "Line2": "Test",
            "Town": "AnyTown",
            "County": "test",
            "PostCode": "AB12 3CD"
        },
        "SchemeCode": "TEST",
        "ClientReference": "121002D",
        "LastName": "Smith"
    },
    "BankAccount": {
        "BankDetails": {
            "AccountName": "Mr Account",
            "SortCode": "666666",
            "AccountNumber": "66666666"
        },
        "Address": {
            "TitleInitials": "Mr",
            "LastName": "Account",
            "County": "A County",
            "Line1": "test line 1",
            "Line2": "test line 2",
            "Town": "My Town",
            "PostCode": "My Postcode"
        }
    }
}

Edit Mandate Details

Edit Allpay Account Holder Details: PUT

{
    "Address": {
        "TitleInitials": "MR N",
        "LastName": "TEST",
        "Line1": "123 Any street",
        "Line2": "Line 2",
        "Town": "Any Town",
        "County": "",
        "PostCode": "AB12 3CD"
    }
}

Example to change account holder name only:

{
    "Address": {
        "TitleInitials": "MR N",
        "LastName": "CHANGE",
        "Line1": "123 Any street",
        "Line2": "Line 2",
        "Town": "Any Town",
        "County": "",
        "PostCode": "AB12 3CD"
        }
}

Edit Bank Account Holder Details: PUT

{
    "Address": {
        "TitleInitials": "MR N",
        "LastName": "TEST",
        "Line1": "123 Any street",
        "Line2": "Line 2",
        "Town": "Any Town",
        "County": "",
        "PostCode": "AB12 3CD"
    }
}

Edit Email Address: PUT

{
    "Email": "email.address@allpay.net"
}

Edit Mobile Number: PUT

{
    "MobileNumber": "07700900000"
}

Immediate Payment Schedule: PUT

{
    "Schedules": [
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    },
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    }
]}

Immediate Renewal Payment Schedule (Suppress Notification)

{
    "Schedules": [
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    },
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    }
],
    "SuppressNotification": 1}

Add Payment Schedule

Add Payment Schedule: POST

{
    "Schedules": [
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    },
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    }
]}

Add Variable Payment Schedule: POST

{
    "Schedules": [
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>
    },
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>
    }
]}

Add Renewal Payment Schedule: POST (Suppress Notification)

{
    "Schedules": [
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    },
    {
        "ScheduleDate": "<YYYY-MM-DD>",
        "Amount": <Numeric Value>,
        "Frequency": "<1, W, F, 4, M, Q, 6, A>",
        "TotalPayments": <Numeric Value>
    }
],
"SuppressNotification": 1}

API Error Codes