{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/en/simpay-flow/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Submerchant registration","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":"submerchant-registration","__idx":0},"children":["Submerchant registration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-registering-a-submerchant","__idx":1},"children":["Step 1: Registering a submerchant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You register a submerchant with the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/flow/flowcreatesubmerchant"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /flow/{flowServiceId}/submerchants"]}]}," request."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.simpay.pl/flow/{flowServiceId}/submerchants\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json\" \\\n  -d '{\n    \"customId\": \"user-123\",\n    \"email\": \"john.smith@example.com\",\n    \"name\": \"John Smith\"\n  }'\n","lang":"bash"},"children":[]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," Your own submerchant ID, e.g. the user ID in your system. Max. 36 characters (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a-z"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A-Z"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0-9"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]},"), unique within the Flow service, cannot start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flsm_"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," Submerchant email address, unique within the Flow service."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant (company) name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant's Online Payments service data (name, URL, terms, MCC, contact details). ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required for payment institutions."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"The Flow service must be active"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can register submerchants only after SimPay approves your Flow service. Otherwise, the API returns the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SERVICE_NOT_ACTIVE"]}," error."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":2},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"message\": \"Submerchant successfully registered\",\n  \"data\": {\n    \"submerchantId\": \"flsm_aaaabbbb\",\n    \"customId\": \"user-123\",\n    \"onboarding\": {\n      \"action\": \"redirect_user\",\n      \"redirectUrl\": \"https://panel.simpay.pl/...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submerchantId"]}," in your database. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onboarding"]}," object tells you what to do next:"]},{"$$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":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you do"},"children":["What you do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect the submerchant to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," - onboarding takes place in the SimPay Panel. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/onboarding/redirect"},"children":["Onboarding via SimPay Panel"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["provide_api"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide the submerchant data via the API. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/onboarding/api"},"children":["Onboarding via API"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-onboarding","__idx":3},"children":["Step 2: Onboarding"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The onboarding method depends on the role of your Flow service:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/onboarding/redirect"},"children":["Onboarding via SimPay Panel"]}," - for marketplace platforms and products that do not intermediate in the transfer of funds (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_non_financial_provider"]},"). The submerchant goes through full verification at SimPay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/onboarding/api"},"children":["Onboarding via API"]}," - for regulated payment institutions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_payment_service_provider"]},"). The procedure is simplified, and you provide the data."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identifying-a-submerchant","__idx":4},"children":["Identifying a submerchant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all SimPay Flow endpoints (and in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-sim-flow-submerchant"]}," header) you can identify a submerchant in two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SimPay ID"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flsm_aaaabbbb"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customId"]}]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user-123"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This way you don't have to store the SimPay ID if it's more convenient for you to use your own identifiers."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submerchant-statuses","__idx":5},"children":["Submerchant statuses"]},{"$$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":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant_pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant registered, waiting for onboarding."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant_in_verification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Data has been submitted, SimPay verification in progress."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant_active"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant active - can accept payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant_inactive"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submerchant inactive (e.g. rejected or blocked)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most operations (payment channels, creating transactions, requesting withdrawals) are available only for submerchants with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant_active"]}," status. For others, the API returns the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FLOW_SUBMERCHANT_NOT_ACTIVE"]}," error."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can check the current status with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/flow/flowgetsubmerchant"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /flow/{flowServiceId}/submerchants/{submerchantId}"]}]},", but we recommend reacting to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_submerchant:status_changed"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/en/simpay-flow/webhooks"},"children":["webhook"]}," instead of polling the API."]}]},"headings":[{"value":"Submerchant registration","id":"submerchant-registration","depth":1},{"value":"Step 1: Registering a submerchant","id":"step-1-registering-a-submerchant","depth":2},{"value":"Response","id":"response","depth":3},{"value":"Step 2: Onboarding","id":"step-2-onboarding","depth":2},{"value":"Identifying a submerchant","id":"identifying-a-submerchant","depth":2},{"value":"Submerchant statuses","id":"submerchant-statuses","depth":2}],"frontmatter":{"seo":{"title":"Submerchant registration"}},"lastModified":"2026-10-01T15:18:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/en/simpay-flow/onboarding","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}