Inviting users to the platform

With this option you’ll create the merchant account and invite a user to register for access to that account. The user will have their own credentials to log in directly to the Evolve Portal.

Create a merchant account.

When you create a new merchant using the /merchants endpoint of our Merchant API, you are asked to provide the following mandatory details:

• ISV ID – This is your organisation’s unique reference number. This will be provided to you along with your API Key. This can be alphanumeric and must be provided as a string.

• Merchant type – The type of onboarding process required for a merchant. These are predefined by Access PaySuite and can be classified by the type of organisation being registered, being either SCHOOL, SUPPLIER, or GENERIC.

Organisation details:

• Merchant’s Legal Name – The name by which the merchant is legally known.

There are further optional details which can be provided, any fields which are included at this stage will be pre-populated in the user interface when the merchant completes their own registration process, saving them time.

If the merchant is a subscriber to your system, and you hold an ID for their record, then you should consider externalId to also be a mandatory parameter.

Example request body

The following is an example JSON request to create a merchant including example data for each possible field:

{
    "isvId": "{{isvId}}",
    "type": "GENERIC",
    "subtype": "PROFESSIONAL_SERVICES",
    "businessClassificationCode": "8911-003",
    "organizationDetails": {
        "legalName": "ABC Finance and Accounts",
        "tradeName": "ABC Finance and Accounts",
        "ownershipType": "LIMITED_COMPANY",
        "companyNo": "34534534599",
        "vatNumber": "345345377",
        "registrationAddress": {
            "line1": "15 High Street",
            "zipCode": "B26 3QJ",
            "city": "Birmingham",
            "countryCode": "GBR"
        },
        "tradingWebsite": "www.abcfinanceandaccountsco.uk",
        "phone": "00443458548736"
    },
    "externalId": "isvref008"
}

If the process is successful, the Merchant API will provide the following example response containing a merchant ID. This ID needs to be recorded in order to continue the onboarding process:

{
    "id": "11014469",
    "status": "ONBOARDING",
    "isvId": "11012312",
    "isvName": "Pay360 1.62 Net Settlement Schools",
    "mcc": "8911",
    "businessClassification": "Engineering / Surveying",
    "businessClassificationCode": "8911-003",
    "type": "GENERIC",
    "subtype": "PROFESSIONAL_SERVICES",
    "createdAt": "2024-01-16T16:23:19.693Z",
    "createdBy": "Pay360:apikey_11012312@pay360evolve.com",
    "externalId": "isvref008",
    "organizationDetails": {
        "legalName": "ABC Finance and Accounts",
        "tradeName": "ABC Finance and Accounts",
        "ownershipType": "LIMITED_COMPANY",
        "companyNo": "34534534599",
        "vatNumber": "345345377",
        "registrationAddress": {
            "line1": "15 High Street",
            "zipCode": "B26 3QJ",
            "city": "Birmingham",
            "countryCode": "GBR"
        },
        "tradingWebsite": "www.abcfinanceandaccountsco.uk",
        "phone": "00443458548736"
    }
}

The header section of the response will also include an E-Tag, this acts as the version number of the merchant record and should be recorded.

1. Create a user invitation.

From release 1.32 the invitationToken will be masked as "****" in the response. If you do not collect or use the Invitation Token, then your integration will not be affected by this change.

Then, using the https://docs.pay360evolve.com/apiref/#operation/createUserAccountUsingPOST endpoint, you will need to make a request containing the following data:

The request will also contain an invitation parameter within the query itself, whether this parameter is set to true or false will determine the process by which the user account is created. The invitation parameter should be set to TRUE for this process, so your query will look like https://api.test.pay360evolve.com/demo/pf-api-gateway/apiGateway/user-account/user-account/userAccounts?invitation=true

An email is sent to the user, giving them a link to use to log in to the portal and configure their account.

The user accesses the email and follows the link to set their password and log into the Evolve Portal. Create an application in order to track the status of the merchant’s registration

The following is an example JSON request to create an application including example data for each possible field:

{

"merchantId": "12345678",

"type": "ONBOARDING"

}

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

{

"merchantId": "12345678",

"id": "11112222",

"status": "NEW",

"type": "ONBOARDING",

"createdAt": "2020-06-25T14:53:35.777Z",

"createdBy": "10000000:test.user\@email.com",

"lastStatusChangeAt": "2020-06-25T14:53:35.777Z",

"onboardingUrl":
<https://portal.test.pay360evolve.com/demo/mp-fe-portal/#/?merchantId=12345678&applicationId=11011982>

}

Checking the application record for status changes

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.

• Applications with a status of NEW, are successfully created merchant records.

• Applications with a status of SUBMITTED have completed onboarding and are awaiting validation. Similarly PENDING applications have been successfully submitted, but supporting documentation is required.

• EXPIRED applications were made successfully, but deadlines related to checks have not been met.

• Applications with a status of REFERRED or REJECTED may require further checks for risk management and compliance purposes.

• Applications with a status of APPROVED and PREAPPROVED can continue to the next step of adding bank accounts for payments and refunds.