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:

{

"type": "SCHOOL", #mandatory

"isvId": "19000000", #mandatory

"subtype": "SECONDARY",

"externalId": "99999",

"organizationDetails":

{

"legalName": "Test High School",

"foundationDate": "1920-02-10",

"ownershipType": "INDEPENDENT_SCHOOLS",

"jurisdiction": "ENGLAND",

"registrationNo": "888/9999",

"registrationAddress": {

"line1": "15 High Street",

"zipCode": "MK18 1AT",

"city": "Buckingham",

"region": "Bucks",

"countryCode": "GBR"

},

"websites": [

"highschool.org"

],

"phone": "001280111222"

}

}

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": "12345678",

"status": "NEW",

"isvId": "19000000",

"isvName": "SVCPROV",

"mcc": "8211",

"type": "SCHOOL",

"subtype": "SECONDARY",

"createdAt": "2020-06-25T13:59:34.335Z",

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

"externalId": "99999",

"organizationDetails": {

"legalName": "Test High School",

"foundationDate": "1920-02-10",

"ownershipType": "INDEPENDENT_SCHOOLS",

"jurisdiction": "ENGLAND",

"registrationNo": "888/9999",

"registrationAddress": {

"line1": "15 High Street",

"zipCode": "MK18 1AT",

"city": "Buckingham",

"region": "Bucks",

"countryCode": "GBR"

},

"websites": [

"highschool.org"

],

"phone": "001280111222"

}

}

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

Name	Description
authorities	A mandatory parameter which details the user account scope and the associated roles. The scope section includes the isvId of your organisation and the merchantId of the newly created Merchant account in the following format "scope": "{{isvId}}/{{merchantId}}". When using this process the roles should always be MERCHANT_ADMIN_PARTNER_INVITE
email	The user's email address. Mandatory
name	The user's full name
canGrant	A list of the roles the user can grant to other users.
externalUserIdentity	The unique identifier held by your organisation for this user.
redirectLoginUrl	The Login URL to which the user should be redirected.
idp	Specifies the identity provider. For this scenario, the setting must be set to Pay360

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://func.pay360.dev/e2eboportal/mp-fe-onboarding/#/?merchantId=12345678&applicationId=11112222>

}

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.