Skip to content
Last updated

Payments on behalf of a submerchant

You create transactions for submerchants through the standard Online Payments API - 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} response.

Example: creating a transaction

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

ValueSubmerchant ID (flsm_...) or its customId
When requiredIn every /payment/{serviceId}/... request when serviceId is the parent service of your active Flow service
When ignoredWhen 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 codeerrorCodeCause
422SIMPAY_FLOW_VALIDATION_ERRORMissing header for the Flow parent service or invalid value.
404FLOW_SUBMERCHANT_NOT_FOUNDThe submerchant does not exist within your Flow service.
403FLOW_SUBMERCHANT_NOT_ACTIVEThe submerchant has not completed onboarding or is not active.
400FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND / FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVEThe 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.

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.

Previous page
Next page