{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/en/simpay-flow/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Payments on behalf of a submerchant","description":"Znajdziesz tutaj wszystkie niezbędne informacje dotyczące integracji i obsługi systemu płatności SimPay.pl","siteUrl":"https://docs.simpay.pl","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payments-on-behalf-of-a-submerchant","__idx":0},"children":["Payments on behalf of a submerchant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You create transactions for submerchants through the standard ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/payment"},"children":["Online Payments API"]}," - the same endpoints as in a regular integration. Only two things differ:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["in the path you pass the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}," of the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["parent service"]}," (the Online Payments service linked to your Flow service),"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-sim-flow-submerchant"]}," header you indicate the submerchant on whose behalf you make the request."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll find the parent service ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentService.id"]}," field of the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/flow/flowgetservice"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /flow/{flowServiceId}"]}]}," response."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-creating-a-transaction","__idx":1},"children":["Example: creating a transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.simpay.pl/payment/{parentServiceId}/transactions\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json\" \\\n  -H \"x-sim-flow-submerchant: user-123\" \\\n  -d '{\n    \"amount\": 49.99,\n    \"description\": \"Order #1001\",\n    \"control\": \"order-1001\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transaction will be created in the service of submerchant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user-123"]},", and the funds will go to its wallet (or - for payment institutions - will be settled with the PI)."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-x-sim-flow-submerchant-header","__idx":2},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-sim-flow-submerchant"]}," header"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant ID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flsm_..."]},") or its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["In every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payment/{serviceId}/..."]}," request when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}," is the parent service of your active Flow service"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When ignored"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}," is a regular Online Payments service not linked to Flow"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /payment/{serviceId}/transactions"]}," returns only that submerchant's transactions."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Don't use the submerchant service directly"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each submerchant has its own Online Payments service, but it cannot be used directly. Passing its ID as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}," returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," error. Always use the parent service and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-sim-flow-submerchant"]}," header."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"possible-errors","__idx":3},"children":["Possible errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP code"},"children":["HTTP code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"errorCode"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SIMPAY_FLOW_VALIDATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing header for the Flow parent service or invalid value."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SUBMERCHANT_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The submerchant does not exist within your Flow service."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SUBMERCHANT_NOT_ACTIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The submerchant has not completed onboarding or is not active."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The submerchant's Online Payments service does not exist or is not active."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-notifications","__idx":4},"children":["Payment notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["IPN notifications about submerchant transactions work the same as in a regular integration - see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/notifications/payment"},"children":["Payment notifications"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In payment notifications for submerchants:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_id"]}," contains the parent service ID,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.flow"]}," object identifies the submerchant (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submerchant_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submerchant_custom_id"]},") and the Flow service - in all events except ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ipn:test"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction:status_changed"]},", the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount.commission_flow"]}," field contains your Flow commission."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Details and example: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/webhooks#payment-webhooks-ipn-in-simpay-flow"},"children":["Payment webhooks in SimPay Flow"]},"."]}]},"headings":[{"value":"Payments on behalf of a submerchant","id":"payments-on-behalf-of-a-submerchant","depth":1},{"value":"Example: creating a transaction","id":"example-creating-a-transaction","depth":2},{"value":"The x-sim-flow-submerchant header","id":"the-x-sim-flow-submerchant-header","depth":2},{"value":"Possible errors","id":"possible-errors","depth":3},{"value":"Payment notifications","id":"payment-notifications","depth":2}],"frontmatter":{"seo":{"title":"Payments on behalf of a submerchant"}},"lastModified":"2026-10-01T15:18:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/en/simpay-flow/payments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}