Each of your Customers who is to accept payments through SimPay Flow must be registered as a submerchant of your Flow service and then complete onboarding.
You register a submerchant with the POST /flow/{flowServiceId}/submerchants request.
curl -X POST "https://api.simpay.pl/flow/{flowServiceId}/submerchants" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"customId": "user-123",
"email": "john.smith@example.com",
"name": "John Smith"
}'| Field | Description |
|---|---|
customId | Required. Your own submerchant ID, e.g. the user ID in your system. Max. 36 characters (a-z, A-Z, 0-9, -, _), unique within the Flow service, cannot start with flsm_. |
email | Required. Submerchant email address, unique within the Flow service. |
name | Submerchant (company) name. |
service | Submerchant's Online Payments service data (name, URL, terms, MCC, contact details). Required for payment institutions. |
You can register submerchants only after SimPay approves your Flow service. Otherwise, the API returns the FLOW_SERVICE_NOT_ACTIVE error.
{
"success": true,
"message": "Submerchant successfully registered",
"data": {
"submerchantId": "flsm_aaaabbbb",
"customId": "user-123",
"onboarding": {
"action": "redirect_user",
"redirectUrl": "https://panel.simpay.pl/..."
}
}
}Save submerchantId in your database. The onboarding object tells you what to do next:
action | What you do |
|---|---|
redirect_user | Redirect the submerchant to redirectUrl - onboarding takes place in the SimPay Panel. See Onboarding via SimPay Panel. |
provide_api | Provide the submerchant data via the API. See Onboarding via API. |
The onboarding method depends on the role of your Flow service:
- Onboarding via SimPay Panel - for marketplace platforms and products that do not intermediate in the transfer of funds (
role_non_financial_provider). The submerchant goes through full verification at SimPay. - Onboarding via API - for regulated payment institutions (
role_payment_service_provider). The procedure is simplified, and you provide the data.
In all SimPay Flow endpoints (and in the x-sim-flow-submerchant header) you can identify a submerchant in two ways:
- by SimPay ID -
flsm_aaaabbbb, - by your
customId-user-123.
This way you don't have to store the SimPay ID if it's more convenient for you to use your own identifiers.
| Status | Meaning |
|---|---|
flow_submerchant_pending | Submerchant registered, waiting for onboarding. |
flow_submerchant_in_verification | Data has been submitted, SimPay verification in progress. |
flow_submerchant_active | Submerchant active - can accept payments. |
flow_submerchant_inactive | Submerchant inactive (e.g. rejected or blocked). |
Most operations (payment channels, creating transactions, requesting withdrawals) are available only for submerchants with the flow_submerchant_active status. For others, the API returns the FLOW_SUBMERCHANT_NOT_ACTIVE error.
You can check the current status with GET /flow/{flowServiceId}/submerchants/{submerchantId}, but we recommend reacting to the flow_submerchant:status_changed webhook instead of polling the API.