Simultaneously create a merchant, registers the merchant, and creates a user record in a single request, associating them together.
This endpoint enables you to create a merchant, register the merchant, and create a user record in a single request.
Returns a compound JSON response containing the merchant record, registration data, user record, ephemeral bearer token, and action summary.
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": truein your payload - Fields passed with the enroll route will be hidden from the user during self-registration
Manual Control:
- Use the
field_permissionsobject within theregistrationparameter - 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 response fields
The following fields are returned in the registration object in the response. These are read-only and do not need to be sent in the request.
| Field | Type | Description |
|---|---|---|
user_id | string | The ID of the user associated with this registration. |
merchant_id | string | The ID of the merchant associated with this registration. |
created_at | string | Timestamp when the registration was created. |
updated_at | string | Timestamp when the registration was last updated. |
plan_txamnt | string | Per-transaction fee amount (e.g., ".15"). |
plan_dcamnt | string | Discount rate amount (e.g., "2.99"). |
plan_ach_txamnt | string | ACH per-transaction fee amount. |
plan_ach_dcamnt | string | ACH discount rate amount. |
plan_ach_cap | string | ACH transaction cap. |
cp_transaction_rate | string | Card-present transaction rate. |
cp_per_item_rate | string | Card-present per-item fee. |
cp_amex_rate | string | Card-present AMEX rate. |
cp_amex_per_item_rate | string | Card-present AMEX per-item fee. |
credit_qual_disc_rate | string | Credit qualified discount rate. |
credit_qual_trans_fee | string | Credit qualified transaction fee. |
credit_mid_disc_rate | string | Credit mid-qualified discount rate. |
credit_mid_trans_fee | string | Credit mid-qualified transaction fee. |
credit_non_disc_rate | string | Credit non-qualified discount rate. |
credit_non_trans_fee | string | Credit non-qualified transaction fee. |
amex_qual_disc_rate | string | AMEX qualified discount rate. |
amex_qual_trans_fee | string | AMEX qualified transaction fee. |
amex_mid_disc_rate | string | AMEX mid-qualified discount rate. |
amex_mid_trans_fee | string | AMEX mid-qualified transaction fee. |
amex_non_disc_rate | string | AMEX non-qualified discount rate. |
amex_non_trans_fee | string | AMEX non-qualified transaction fee. |
is_flat_rate | boolean | Whether the merchant is on a flat-rate pricing plan. |
cp_credit_surcharge_rate | string \| null | Card-present credit surcharge rate, if applicable. |
cnp_credit_surcharge_rate | string \| null | Card-not-present credit surcharge rate, if applicable. |
cp_debit_trans_fee | string \| null | Card-present debit transaction fee, if applicable. |
cnp_debit_trans_fee | string \| null | Card-not-present debit transaction fee, if applicable. |
cp_debit_discount_rate | string \| null | Card-present debit discount rate, if applicable. |
cnp_debit_discount_rate | string \| null | Card-not-present debit discount rate, if applicable. |
plus_card_rate | string \| null | Tiered pricing plus card rate, if applicable. |
premium_card_rate | string \| null | Tiered pricing premium card rate, if applicable. |
files | array | Array of file objects associated with the registration. |
brand | string | The brand associated with this registration (e.g., "fattmerchant"). |
underwriting_substatus | string \| null | Current underwriting sub-status, if any. |
empty_required_fields | array | List of registration field names that are still required but have not been provided. Use this to determine what data is missing before underwriting. |
latest_file_uploaded_at | string \| null | Timestamp of the most recently uploaded file, or null if no files have been uploaded. |
merchant | object | The full merchant object associated with this registration. |
user | object | The full user object associated with this registration. |
Next Steps
Use the returned merchant.id, registration.id, or user.id to perform additional actions, such as uploading supporting documentation or configuring additional merchant settings.