Sales transactions API

This specification defines an API providing sales transaction data for a given merchant.

Note

You need to implement this API and expose it to Flowpay in order to facilitate either Fully Embedded (Native), Embedded (iFrame) or Linkout with individual customer activation flow.

Request

HTTP API endpoint accepting GET method with query parameters and responding with JSON message containing merchant's sales transaction data (typically orders or payments). HTTPS is required for all API requests.

Parameters

Merchant is specified by query parameter merchantId (mandatory)
If the merchant has multiple operations (restaurants, e-shops, projects, etc) the API may accept query parameter tenantId to provide separated data for individual operations (optional)

Example request:

GET https://api.example.com/v1/sales?merchantId=abc123&size=100&updatedAt=2024-01-01T00:00:00Z

Response Format

JSON message in UTF-8 encoding
The identifiers are arbitrary strings (may or may not be UUIDs)
Timestamps in ISO 8601 format
Currency codes according to ISO 4217 specification
Country codes according to ISO 3166-1 (either alpha-2 or alpha-3)
Monetary values and quantities as JSON numbers
Optional fields should be omitted when null or not available
Response must include Content-Type: application/json header

Response Structure

The response contains collection of order objects wrapped in data attribute
Empty response (no matching records) must return {"data": []}

DataExample (minimal)Example (full)

Attribute	Description
`data`	mandatory, array of order objects
`nextPage`	optional, pagination cursor for cursor-based pagination; if present it is used as `page` parameter for next request; if null or missing, no more pages available

Order attributes

Attribute	Description
`id`	mandatory, unique record identifier
`customerId`	mandatory, unique customer identifier (non PII)
`customerName`	optional, customer display name (non PII)
`status`	mandatory, PENDING (order is being processed, awaiting payment, etc), DELIVERED (order is paid, delivered and closed), CANCELED (order was canceled by customer or merchant), REFUNDED (paid order was canceled 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 canceled)
`totalPrice`	mandatory, represents total amount paid (or to be paid) by the end customer
`totalDiscount`	optional, total discount applied to the order
`totalShipping`	optional, total shipping cost
`totalTax`	optional, total tax amount
`billingAddress`	optional object containing billing address (line1, line2, line3, city, state, country, zip)
`shippingAddress`	optional object containing shipping address (line1, line2, line3, city, state, country, zip)
`items`	optional, collection of line items contained within the order

Item attributes (within items array)

Attribute	Description
`productId`	mandatory, unique product identifier
`productName`	optional, product display name
`quantity`	optional, number of units
`unitPrice`	optional, price per unit
`totalPrice`	mandatory, total price for this line item
`discountAmount`	optional, discount applied to this item
`taxAmount`	optional, tax amount for this item

{
  "data": [
    {
      "id": "Ay423ht8aAv3AHR4gRr3",
      "customerId": "Bj60hk9kkPVAH9QBXr2a",
      "status": "DELIVERED",
      "delivery": "CARRIER",
      "payment": "CASH",
      "currency": "USD",
      "createdAt": "2024-01-21T19:19:19Z",
      "updatedAt": "2024-01-21T19:19:19Z",
      "totalPrice": 59.99
    }
  ]
}

{
  "data": [
    {
      "id": "Ay423ht8aAv3AHR4gRr3",
      "customerId": "Bj60hk9kkPVAH9QBXr2a",
      "customerName": "John Doe",
      "status": "DELIVERED",
      "delivery": "CARRIER",
      "payment": "CASH",
      "currency": "USD",
      "createdAt": "2024-01-21T19:19:19Z",
      "updatedAt": "2024-01-21T19:19:19Z",
      "totalPrice": 59.99,
      "totalDiscount": 10,
      "totalShipping": 10,
      "totalTax": 10,
      "billingAddress": {
        "line1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zip": "10001"
      },
      "shippingAddress": {
        "line1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zip": "10001"
      },
      "items": [
        {
          "productId": "YDrr2ND7H11M2h4dhrfe",
          "productName": "Product Title",
          "quantity": 1,
          "unitPrice": 49.99,
          "totalPrice": 49.99,
          "discountAmount": 10,
          "taxAmount": 10
        }
      ]
    }
  ],
  "nextPage": "cursor_abc123"
}

Pagination

The API must support pagination to limit total number of objects returned by the server in a single request.

Query parameters:

size - maximum number of objects to return per request
page - page identifier (either numeric index or cursor token depending on pagination mode)

Timeout consideration

Flowpay's client implementation uses a request timeout of 300 seconds (5 minutes) per individual HTTP request. The API provider should configure the maximum allowed size value to ensure responses complete within this timeout.

Two pagination modes are supported:

Cursor-based paginationOffset-based pagination

The API response includes a nextPage attribute indicating the next page token or cursor.

If nextPage is present and non-null, its value is used for the next request's page parameter
If nextPage is null or missing, pagination stops

{
  "data": [{...}, {...}],
  "nextPage": "cursor_abc123"
}

The client determines if more pages exist based on response size.

If response contains fewer records than size, there are no more pages
If response contains exactly size records, the next page is requested by incrementing page

{
  "data": [{...}, {...}]
}

Incremental replication

Query parameter updatedAt (format ISO-8601, example 2020-12-21T20:20:20.202020Z) enables to retrieve records created or updated after the specified timestamp.
The filter is exclusive: returns records where updatedAt > {parameter value}
Comparison uses full timestamp precision (including microseconds if available)
If updatedAt parameter is omitted, all records are returned (full sync)

Sorting

Records must be sorted by updatedAt in ascending order (oldest first)
This ensures incremental replication captures all updates correctly
When paginating, sorting must be consistent across all pages

Authentication

Two authentication modes are supported:

API Key AuthenticationOAuth 2.0 based authentication

API key is provided in HTTP header X-API-Key
Required configuration: API_KEY

Client Credentials Flow to get access token from authorization server
Access token provided in HTTP header: Authorization: Bearer {token}
Required configuration: CLIENT_ID, CLIENT_SECRET, API_AUDIENCE, API_TOKEN_URL

Error handling

HTTP 400 Bad Request response is returned for invalid query parameters (e.g., malformed updatedAt timestamp)
HTTP 401 Unauthorized response is returned for requests with missing or invalid API key or token
HTTP 404 Not Found response is returned if the specified merchantId does not exist
HTTP 429 Too Many Requests response is returned if rate limiting was applied to the request with Retry-After header indicating required delay in seconds until another attempt

Retries

Flowpay's client implementation uses exponential backoff with jitter for retrying failed requests (429 and 5xx errors). Default is up to 5 retry attempts with increasing delays between attempts.