# Submerchant registration

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.

## Step 1: Registering a submerchant

You register a submerchant with the [`POST /flow/{flowServiceId}/submerchants`](/apis/flow/flowcreatesubmerchant) request.


```bash
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.** |


The Flow service must be active
You can register submerchants only after SimPay approves your Flow service. Otherwise, the API returns the `FLOW_SERVICE_NOT_ACTIVE` error.

### Response


```json
{
  "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](/en/simpay-flow/onboarding/redirect). |
| `provide_api` | Provide the submerchant data via the API. See [Onboarding via API](/en/simpay-flow/onboarding/api). |


## Step 2: Onboarding

The onboarding method depends on the role of your Flow service:

1. [Onboarding via SimPay Panel](/en/simpay-flow/onboarding/redirect) - 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.
2. [Onboarding via API](/en/simpay-flow/onboarding/api) - for regulated payment institutions (`role_payment_service_provider`). The procedure is simplified, and you provide the data.


## Identifying a submerchant

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.

## Submerchant statuses

| 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}`](/apis/flow/flowgetsubmerchant), but we recommend reacting to the `flow_submerchant:status_changed` [webhook](/en/simpay-flow/webhooks) instead of polling the API.