Skip to content

Bulk sales transactions

This specification describes data structure for providing bulk sales transaction data for a set of eligible merchants.

Note

You need to provide data according to this specification to Flowpay in order to facilitate either Linkout flow or customer base pre-scoring option of Fully Embedded (Native), Embedded (iFrame) or Embedded (Mobile) flow.

Scope

Bulk sales transaction data containing individual sales transactions, e.g. orders or payments, for a set of eligible merchants

Pseudonymization

Identification of the end customer can be an arbitrary string, however, consistent identifier is required across multiple data files. This enables our scoring models to assess the retention by grouping all transactions coming from the same end customer and the same merchant.

Data specification

  • Data format: bulk file in CSV, JSON or XML format with UTF-8 encoding
Attribute Description
id mandatory, unique record identifier
merchantId mandatory, unique identifier of the merchant, must be the same in all future data files
tenantId optional, unique identifier of the merchant's branch/tenant/project, must be the same in all future data files
tenantName optional, human-readable name of the merchant's branch/tenant/project
country mandatory, country of merchant (company) registration (two-letter country code as defined by ISO 3166-1 alpha-2)
businessIdHash optional, sha256 hash of merchant company identifier from the respective country’s business registry
customerId mandatory, unique customer identifier (non PII)
status mandatory, PENDING (order is being processed, awaiting payment, etc), DELIVERED (order is paid, delivered and closed), CANCELED (order was cancelled by customer or merchant), REFUNDED (paid order was cancelled and customer was refunded)
delivery mandatory, delivery method: CARRIER (delivery company or postal service), PERSONAL (order picked up personally by end customer), ONLINE (digital goods delivered online)
payment mandatory, payment method: CASH, CARD, BANK
currency mandatory
createdAt mandatory, represents a timestamp when the order was placed by the end customer
updatedAt mandatory, represents a timestamp of the event resulting in specified order status (e.g. if current status is CANCELED the updatedAt corresponds to the timestamp when the order was cancelled)
totalPrice mandatory, represents total amount paid (or to be paid) by the end customer
totalDiscount optional attribute to provide additional details about the price structure
totalShipping optional attribute to provide additional details about the price structure
totalTax optional attribute to provide additional details about the price structure
items optional collection of items contained within the order or payment
productId only mandatory if items are specified
totalPrice only mandatory if items are specified
productName optional
quantity optional attribute to provide additional details about the price structure
unitPrice optional attribute to provide additional details about the price structure
discountAmount optional attribute to provide additional details about the price structure
taxAmount optional attribute to provide additional details about the price structure

Data distribution

  • Transport protocol: either you upload the file to Azure Blob Storage managed by Flowpay or you provide access for Flowpay to download the data from a storage managed by you (e.g., AWS S3, Azure Blob Storage, Google Cloud Storage, etc)
  • Periodicity: monthly

Upload to Flowpay storage

Flowpay creates a container for you and grants you access to it. At onboarding, Flowpay sends you these values.

Name Value
YOUR_CONTAINER_URL Address of your container, https://<storage-account>.blob.core.windows.net/<container>
YOUR_CONTAINER_TENANT_ID Entra tenant ID. Identifies the Azure directory you authenticate against
YOUR_CONTAINER_CLIENT_ID Client ID of the service principal that Flowpay issues to you
YOUR_CONTAINER_CLIENT_SECRET Client secret of that service principal. It is valid for 12 months

Your access covers your container only. You can list, read and upload files. You cannot delete files.

You upload to inbound/ and download from outbound/.

Container layout

YOUR_CONTAINER_URL/
  inbound/
    history/<filename>
    <YYYY-MM>/<filename>
  outbound/
    <offer files>

Cadence

  1. Upload the full available history to inbound/history/, as one or more files.
  2. Then upload one file per month to inbound/<YYYY-MM>/, within the first days of the next month. <YYYY-MM> is the month the data covers. The file holds every transaction of that month for every merchant.
  3. To correct a month, upload a new file to the same folder. Flowpay uses the newest file in each folder.

Offers appear in outbound/, in the format of Bulk offers.

Uploading

Use azcopy for automated and manual uploads.

export AZCOPY_SPA_CLIENT_SECRET="$YOUR_CONTAINER_CLIENT_SECRET"
azcopy login --service-principal --application-id "$YOUR_CONTAINER_CLIENT_ID" --tenant-id "$YOUR_CONTAINER_TENANT_ID"

azcopy copy <source> "$YOUR_CONTAINER_URL/inbound/<YYYY-MM>/"