Create Merchant

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

Endpoint

POST /api/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
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.
customerLegalName	string	required	Legal name of the customer business.
stripePlatformAccountId	string max(100)	required	A Stripe Platform account Id. This will be provided to the SoftCo during SoftCo registration
country	string max(2)	required	ISO 3166-1 alpha-2 country code (supported country codes are GB, IE, NZ, AU)
redirectUrl	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.
stripePriceGroupId	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.
stripeTosAcceptanceDate	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.
stripeTosAcceptanceIp	string	optional	IP address from which the account representitive accepted the service agreement (required if stripeTosAcceptanceDate provided). E.g. 127.0.0.1
evoOrganizationId	uuid	optional	Evo organization identifier. This is only applicable if the customer is using the PaySuite Pay Hub to manage payments

Payload example

{
  "customerId": "customer_123",
  "customerLegalName": "Example Business Ltd",
  "stripePlatformAccountId": "acct_platform123",
  "country": "GB",
  "redirectUrl": "https://example.com/onboarding/complete",
  "stripePriceGroupId": "price_group_456",
  "stripeTosAcceptanceDate": "2024-01-15T09:00:00Z",
  "stripeTosAcceptanceIp": "192.168.1.1",
  "evoOrganizationId": "org_789"
}

Response parameters

Status Code: 201 Created

Parameter	Type	Description
merchantId	uuid	A unique identifier for the customer created by the Merchant API.
customerId	string	A unique identifier for the customer in the SoftCo product.
sessionId	string	A unique identifier to track the session.
action	object	Object containing the action to be performed by the SoftCo product.
→ redirectUrl	string	(conditional) The URL to redirect the customer to being the onboarding journey. Note: this will only be returned if there is further data to be collected from the customer and the integration is via a redirect onboarding
→ stripeConnectAccountId	string	(conditional) The Stripe Connect identifier for the customer. Note: this will only be returned if the integration is via embedded onboarding.
→ stripeClientSecret	string	(conditional) The Stripe Connect identifier for the customer. Note: this will only be returned if the integration is via embedded onboarding

Payload redirect example

{
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "customer_123",
  "sessionId": "66c0df2ec03d8a3b582e615b83274816",
  "action": {
    "redirectUrl": "https://creditRiskAssessmentUrl.com"
  }
}

Payload embedded example

{
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "customer_123",
  "sessionId": "66c0df2ec03d8a3b582e615b83274816",
  "action": {
    "stripeConnectAccountId": "acct_12345"
    "stripeClientSecret": "client_secret_67890",
  }
}