Skip to content

Secure linkout

This specification describes an algorithm to construct a secure URL to navigate the merchant to myFlowpay web app.

Note

You need to implement navigation to the secure URL in order to facilitate the Linkout flow.

Each runtime environment includes its own configuration settings and is secured with separate credentials. As part of partner onboarding process we will provide you with YOUR_PARTNER_CODE and YOUR_URL_SECRET for all environments.

Secured URL is constructed as follows. 

https://test.my.flowpay.io/entry/{YOUR_PARTNER_CODE}?{queryString}

https://my.flowpay.io/entry/{YOUR_PARTNER_CODE}?{queryString}

where queryString contains following parameters:

Query string parameter Description
merchantId mandatory, identifier of the merchant as provided within the Sales transactions API or Bulk sales transactions data
tenantId optional, additional identifier of the merchant operation (branch, e-shop, project, etc) as provided within the Sales transactions API or Bulk sales transactions data
country mandatory, country of merchant company registration (two-letter country code as defined by ISO 3166-1 alpha-2)
regNum mandatory, merchant company identifier from the respective country’s business registry
createdAt mandatory, timestamp when URL was created in ISO 8601 format to enable Flowpay to calculate signature validity
signature mandatory, HMAC-SHA256 created from key = YOUR_URL_SECRET and message = single lower-cased string constructed as concatenation of following values in the specified order without any separator merchantId + tenantId + country + regNum + createdAt

Example

Given configuration

YOUR_PARTNER_CODE = "SomePartner"
YOUR_URL_SECRET = "SomeSecret"

and merchant identification 

merchantId = "d5c7a41a-bf5d-44cf-808c-a8accf14cd00"
tenantId = "976156b1-c5a2-4d70-a3cb-65d4d64f427c"
country = "CZ"
regNum = "123456"

the resulting signature and secure URL is as follows 

createdAt = "2025-03-25T09:03:33Z"
signature = "1d6ac6a29b9ba40d82b0b885b184d4c9099cb01ceb081b50560e10bb48227e1a"
https://my.flowpay.io/entry/SomePartner?merchantId=d5c7a41a-bf5d-44cf-808c-a8accf14cd00&tenantId=976156b1-c5a2-4d70-a3cb-65d4d64f427c&country=CZ&regNum=123456&createdAt=2025-05-01T14:21:14.766Z&signature=1d6ac6a29b9ba40d82b0b885b184d4c9099cb01ceb081b50560e10bb48227e1a

Authorization

Flowpay authorizes the request by validating the signature. The signature is valid for 60 minutes.