Evolve offers a level of flexibility whereby third-party bank accounts, such as those belonging to Local Authorities or Academy Trusts, can be used, however these require the same level of validation as merchant owned accounts. These are referred to as supplier accounts, as they generally provide services or products to the merchants.

The merchant API gives users the ability to manage their bank accounts in the following ways:

• Add a bank account.

• View the status of all bank accounts on the system. The available statuses are UNVERIFIED, FAILED_VERIFICATION, REQUESTED, REQUEST_DECLINED, APPROVED and CLOSED.

• Retire bank accounts. If a merchant closes a certain bank account, they may prefer to close or deactivate it on the system. Verified bank accounts cannot be deleted, however they can be deleted at any time before completing verification.

Adding a Bank Account

The following steps are required each time a new bank account is added to the system:

• Create a new bank account record.

• Provide valid supporting documents, for example a bank statement.

• Check status of bank account.

Using the bankAccounts endpoint on the Merchant API, you need to provide the following mandatory details:

• Merchant ID – The merchant ID provided by Evolve when the merchant was created.

• Usages – The purpose(s) of this bank account. The available types of usage are REMITTANCE and REFUNDS. A remittance account will be used to accept credits, while a refund account will be used to process refunds. It is likely that software providers will only need to set up merchants for remittance accounts.

• Type of Account Ownership – The owner of the bank account. It can either be owned by the merchant or a third party.

• Account Holder – The name of the organisation that owns the account.

• Sort Code – The six-digit sort code of the branch at which the bank account is held.

• Account Number – The eight-digit bank account number.

If the account is not owned by a supplier rather than a merchant, you will also be required to supply the following details of a representative of the third-party/supplier who will be responsible for approving the new bank account details.

• Contact email – the email address of the organisation’s representative who can be contacted by Access PaySuite to get the new bank account authorised.

• Contact name – The name of the representative.

• Supplier Name – The name of the third-party company or organisation who owns the bank account.

There are further optional details which can be provided.

Example request body

The following is an example JSON request to create a new bank account for refunds, using the Merchant API:

{

"merchantId": "12345678",

"merchantOwned": true,

"displayName": "Test Account",

"accountHolder": "Test High School",

"sortCode": "089230",

"accountNumber": "61492987",

"usages": [

"REMITTANCE"

]

}

The following example response you receive from the Merchant API will contain a bank account ID in the first line, this ID needs to be recorded:

{

"id": "43fb6c7a-62e9-4a76-b0f5-ba2a0c793f7c",

"merchantId": "12345678",

"status": "UNVERIFIED",

"usages": [

"REMITTANCE"

],

"merchantOwned": true,

"displayName": "Test Account",

"accountHolder": "Test High School",

"sortCode": "089230",

"accountNumber": "61492987",

"lastStatusChangeAt": "2020-06-25T15:41:07.003Z"

}

Uploading supporting documents

You will now need to upload any supporting documents to the system using the Document API. This is done using the documents endpoint. The only parameter required for this request is the file location of the document to be uploaded.

Example request body

The following is an example JSON request to add a new document to the system, using the Document API:

{

"file": "C:\\bank_accounts\\bank_statement.pdf"

}

The id in the following response you receive from the Document API is the document ID, this must be recorded:

{

"id": "517f524d-772b-4e15-85f0-4ebdc5dce860"

}

To associate this document with the bank account record you have created you need to create a document record in the Merchant API using the documents endpoint. You are required to provide the following mandatory details:

• Merchant ID – The merchant ID provided by Evolve when the merchant was created.

• Document Type – The purpose of the document e.g. PROOF_OF_BANK_ACCOUNT.

• External Document ID – This is the ID returned by the Document API above when you uploaded the document.

There are further optional details which can be provided.

Example request body

The following is an example JSON request to associate a document previously uploaded with the Document API with a merchant record, using the Merchant API:

{

"merchantId": "12345678",

"subEntityType": "BANK_ACCOUNT",

"subEntityId": "43fb6c7a-62e9-4a76-b0f5-ba2a0c793f7c",

"type": "PROOF_OF_BANK_ACCOUNT",

"subtype": "BANK_STATEMENT",

"classification": "PUBLIC",

"description": "Redacted bank statement",

"externalDocumentId": "517f524d-772b-4e15-85f0-4ebdc5dce860"

}

When the document record has been created, you will receive the following response from the Merchant API containing an ID:

{

"id": "7765d0eb-4806-494a-a437-edd7feb82351",

"merchantId": "12345678",

"subEntityType": "BANK_ACCOUNT",

"subEntityId": "43fb6c7a-62e9-4a76-b0f5-ba2a0c793f7c",

"type": "PROOF_OF_BANK_ACCOUNT",

"subtype": "BANK_STATEMENT",

"externalDocumentId": "517f524d-772b-4e15-85f0-4ebdc5dce860",

"description": "Redacted bank statement",

"classification": "PUBLIC",

"uploadedAt": "2020-06-25T16:07:31.155Z",

"uploadedBy": "10000000:test.user\@email.com"

}

Checking the status of the bank account

Your system will need to poll the bank account record in the Merchant API to confirm the status of the bank account using the bankAccounts endpoint.

Once the bank account has a status of VERIFIED, it is considered validated for the system.

Enabling refunds for schools

In order for the merchant to enable refunds using Evolve, they must first set up a direct debit agreement. Your system must ensure that the user who is trying to enable refunds has the required permissions and has been validated. We provide a user interface via the merchant portal where users can enable refunds, and users are authenticated using the Authentication API.

In order to enable refunds, you must complete the following tasks:

• Create a Refund application.

• Log the user in to the onboarding portal to set up refunds

• Check for application status updates.

Creating an Application

In this case the application type would be REFUNDS.

The merchant API will provide a response containing an application ID, and a URL. The application ID should be recorded in order to continue the process.

Your system should now poll the application record to check the status of the application. The following statuses are available: NEW, SUBMITTED , PENDING, EXPIRED, REFERRED, PREAPPROVED, APPROVED, REJECTED and CANCELLED.

Once an application is approved, refunds can be authorised on the system.