Create Merchant

Create a new merchant in the system and initiate the onboarding process.

Endpoint

POST /api/v2/merchants

Header parameters

Header	Type	Required	Description
Ocp-Apim-Subscription-Key	string	required	Your PaySuite subscription key
Content-Type	string	required	application/json

Request parameters

Parameter	Type	Required	Description
divisionAccountId	string max(100)	required	A PaySuite created Account Id to identify the SoftCo. This will be provided to the SoftCo during the project setup
customerId	string max(100)	required	A unique identifier for the customer in the SoftCo product. This will be returned in the webhook events and should be used to identify the customer in the SoftCo product.
returnUrl	string	required	URL to redirect after onboarding completion. This redirect will happen trigger after the Stripe hosted onboarding flow has been completed (or cancelled) by the customer.
business	object	required	Object to provide the required details for a business type. See Business object
paymentGateway	object	required	Object to provide the required details for a payment gateway. See Payment Gateway object
evo	object	optional	Object to provide the required details for the Evo platform. See Evo object

Business Object

Parameter	Type	Required	Description
type	string	required	Identified business type. Supported values are soleProprietorship or organization.
soleProprietorship	object	conditional	Must be provided if type is soleProprietorship. See Sole Proprietorship object below
organization	object	conditional	Must be provided if type is organization. See Organization object below

Sole Proprietorship

Parameter	Type	Required	Description
country	string	required	Country of the merchant. Format: ISO 3166-1 alpha-2
firstName	string	required	Individual's first name
lastName	string	required	Individual's last name

Organization

Parameter	Type	Required	Description
country	string	required	Country of the merchant. Format: ISO 3166-1 alpha-2
legalName	string	required	Organization's legal name

Payment Gateway Object

Parameter	Type	Required	Description
type	string	required	The payment gateway to be onboarded. Supported values: stripe.
stripe	string	conditional	Required when type is stripe. Stripe payment gateway configuration. See Stripe object below

Stripe

Parameter	Type	Required	Description
priceGroupId	string max(100)	optional	Stripe pricing group identifier. This must be an active Stripe price group id obtained from PaySuite during project setup. If no value provided, the default pricing scheme will be applied to the customer.
tosAcceptanceDate	dateTime	optional	ISO 8601 date when the account representitive accepted the service agreement. This is only applicable if the Stripe service agreement are to be accepted by the customer outside of the Stripe hosted onboarded. If empty, then Stripe will require the customer to accept the terms during the hosted onboarding journey.
tosAcceptanceIp	string	optional	IP address from which the account representitive accepted the service agreement (required if stripeTosAcceptanceDate provided). E.g. 127.0.0.1
metadata	object	optional	Key-value pair. Can be provided to record miscellaneous data against the onboarded merchant. E.g. a reference to an existing Connect Account Id when migrating customers.

Evo Object

Parameter	Type	Required	Description
organizationId	uuid	optional	Evo organization identifier.
customerReference	string	optional	The customer code obtained from Access Group Finance and used to uniquely identify the customer across the whole of Access.

Payload example

Example with Business Type soleProprietorship

{
    "divisionAccountId": "<string>",
    "customerId": "<string>",
    "returnUrl": "<url>",
    "business": {
        "type": "organisation",
        "organisation": {
            "country": "<ISO 3166-1 2-alpha>",
            "legalName": "<string>"
        }
    },
    "paymentGateway": {
        "type": "stripe",
        "stripe": {
            "priceGroupId": "<string>",
            "tosAcceptanceDate": "2024-10-18T10:00:19Z",
            "tosAcceptanceIp": "<string>",
            "metadata": {
                "<key>": "<value>"
            }
        }
    },
    "evo": {
        "organisationId": "<GUID>",
        "customerReference": "<Finance CuCode>"
    }
}

Example minimum request

{
    "divisionAccountId": "<string>",
    "customerId": "<string>",
    "returnUrl": "<url>",
    "business": {
        "type": "organisation",
        "organisation": {
            "country": "<ISO 3166-1 2-alpha>",
            "legalName": "<string>"
        }
    },
    "paymentGateway": {
        "type": "stripe"
    }
}

Response parameters

Status Code: 201 Created

Parameter	Type	Description
divisionAccountId	string	As provided in the request.
customerId	string	As provided in the request.
merchantId	uuid	A PaySuite ID used for future queries to obtain the onboarding status.
sessionId	string	A unique identifier to track the session.
traceId	string	A unique trace identifier for the request.
action	object	Object containing the action to be performed by the SoftCo product.
→ type	string	Identifies the type of action to perform. Will either return redirect or embed based on the Soft Co settings
→ redirectUrl	string	(conditional) If type is redirect. The URL to redirect the customer to start the onboarding journey. Use this to initiate the Redirect MFE Onboarding journey.
→ stripe.connectAccountId	string	The Stripe Connect identifier for the customer.
→ stripe.clientSecret	string	(conditional) If type is embed. The Stripe Connect identifier for the customer. Use this to initiate the Stripe Onboarding component, see embedded onboarding

Payload redirect example

{
  "divisionAccountId": "<string>",
  "customerId": "<string>",
  "merchantId": "<string>",
  "sessionId": "<string>",
  "traceId": "<string>",
  "action": {
    "type": "redirect",
    "redirectUrl": "<URL>",
    "stripe": {
        "connectAccountId": "<string>"
    }
  }
}

Payload embedded example

{
  "divisionAccountId": "<string>",
  "customerId": "<string>",
  "merchantId": "<string>",
  "sessionId": "<string>",
  "traceId": "<string>",
  "action": {
    "type": "embed",
    "stripe": {
        "connectAccountId": "<string>",
        "clientSecret": "<string>"
    }
  }
}