# Payments on behalf of a submerchant

You create transactions for submerchants through the standard [Online Payments API](/apis/payment) - the same endpoints as in a regular integration. Only two things differ:

1. in the path you pass the `serviceId` of the **parent service** (the Online Payments service linked to your Flow service),
2. in the `x-sim-flow-submerchant` header you indicate the submerchant on whose behalf you make the request.


You'll find the parent service `serviceId` in the `paymentService.id` field of the [`GET /flow/{flowServiceId}`](/apis/flow/flowgetservice) response.

## Example: creating a transaction


```bash
curl -X POST "https://api.simpay.pl/payment/{parentServiceId}/transactions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-sim-flow-submerchant: user-123" \
  -d '{
    "amount": 49.99,
    "description": "Order #1001",
    "control": "order-1001"
  }'
```

The transaction will be created in the service of submerchant `user-123`, and the funds will go to its wallet (or - for payment institutions - will be settled with the PI).

## The `x-sim-flow-submerchant` header

|  |  |
|  --- | --- |
| **Value** | Submerchant ID (`flsm_...`) or its `customId` |
| **When required** | In every `/payment/{serviceId}/...` request when `serviceId` is the parent service of your active Flow service |
| **When ignored** | When `serviceId` is a regular Online Payments service not linked to Flow |


The header works for all Online Payments endpoints - transactions, refunds, channels, currencies, subscriptions, BLIK Level 0 and BLIK aliases. Each of these requests is executed in the context of the given submerchant's service. For example, `GET /payment/{serviceId}/transactions` returns only that submerchant's transactions.

Don't use the submerchant service directly
Each submerchant has its own Online Payments service, but it cannot be used directly. Passing its ID as `serviceId` returns a `422` error. Always use the parent service and the `x-sim-flow-submerchant` header.

### Possible errors

| HTTP code | `errorCode` | Cause |
|  --- | --- | --- |
| `422` | `SIMPAY_FLOW_VALIDATION_ERROR` | Missing header for the Flow parent service or invalid value. |
| `404` | `FLOW_SUBMERCHANT_NOT_FOUND` | The submerchant does not exist within your Flow service. |
| `403` | `FLOW_SUBMERCHANT_NOT_ACTIVE` | The submerchant has not completed onboarding or is not active. |
| `400` | `FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND` / `FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVE` | The submerchant's Online Payments service does not exist or is not active. |


## Payment notifications

IPN notifications about submerchant transactions work the same as in a regular integration - see [Payment notifications](/notifications/payment).

By default, notifications for all submerchants are sent to the parent service IPN URL and signed with its key. You can set a separate URL for a selected submerchant.

In payment notifications for submerchants:

- `service_id` contains the parent service ID,
- the new `data.flow` object identifies the submerchant (`submerchant_id`, `submerchant_custom_id`) and the Flow service - in all events except `ipn:test`,
- in `transaction:status_changed`, the new `amount.commission_flow` field contains your Flow commission.


Details and example: [Payment webhooks in SimPay Flow](/en/simpay-flow/webhooks#payment-webhooks-ipn-in-simpay-flow).