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) or Embedded (iFrame) 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 CANCELLED 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