This endpoint enables you to create a merchant, registration, and user record in a single request and associate them.

Response Data

Returns a compound JSON response containing the merchant record, registration data, user record, ephemeral bearer token, and action summary.

Single Request

Create and associate multiple records simultaneously to streamline the merchant enrollment process.

Key Features

Existing User Handling

If the specified user email already exists, the system will:

Associate the existing user record
Ignore the remaining user fields in the request
Throw an error if the email is associated with a Stax Connect level user (ephemeral tokens cannot be generated for such users)

Self-Registration Field Permissions

Simplify the self-registration process with automatic field management:

Automatic Field Hiding:

Set "hide_prefilled_fields": true in your payload
Fields passed with the enroll route will be hidden from the user during self-registration

Manual Control:

Use the field_permissions object within the registration parameter
Manually control which fields are visible or required during registration

In the payload of the enroll route and in any data passed with it, the null-field permission will be applied, causing the field to be hidden from the front end. For example, if we POST a value for business_dba, that field will be prepopulated, and the user will not see it during self-registration. These fields get stored in the field_permissions JSON column in the registrations table. If you wish to control the field_permissions manually, you can set them in the registration parameter of the enroll route. There are three possible options when setting a field permission: null, 'read', and 'write':

"registration": { "field_permissions": { "business_dba": null, // business_dba field will be hidden "business_website": 'read', // business_website field will read only "company_type": 'write' // company_type field will be writeable as normal } }

❗️
If all fields in a given section are marked as hidden and are passed in via the API, then the entire section/page and any horizontal bars will be hidden from the front end.
If all fields for a given page are provided, the page will be hidden and removed from the sidebar tracker.
For any fields marked as hidden and with a value passed in, they will not be visible on the review step.

Parameter Notes

skip_account_page: Set to true to skip the setPassword page for the user during login. inhide_prefilled_fields: (optional) boolean that toggles the hidden fields feature. Set to true to have fields automatically hide in self-registration based on fields captured during enrollment.

merchant object

company_name: (required)

contact_email: (required)

hosted_payments_token: Every merchant record will have a unique one of these, as it is used to facilitate using StaxJs. If you do not specify a unique record here, one will be generated, typically with the merchant's Company name prefix and a random string appended. You may update this later using the /put/merchant/{merchant_id} route.

plan: (required) - The plan which sets Stax Pay configuration. Use "premium" until another plan is needed.

currency (optional, array) e.g. ["USD"] or ["CAD"]The currency this merchant will process payments with. Defaults to ["USD"]. Despite this field being an array, only one currency is currently supported at a time.

registration object

pricing_plan: (required) Must be a valid pricing plan for the requesting user's Brand. Use "test-pricing" until you have an official pricing plan set up for your brand.

Next Steps

Continue Integration

Use the returned merchant.id, registration.id, or user.id to perform additional actions, such as uploading supporting documentation or configuring additional merchant settings.