Skip to content

Sales transactions API

This specification describes an API endpoint 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.

API endpoint

HTTP API endpoint accepting GET method with query parameters and responding with JSON message containing merchant's sales transaction data (typically orders or payments)

Request

  • Merchant specification
    • 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
  • Incremental replication (mandatory)
    • Query parameter updatedAt (format ISO-8601, example 2020-12-21T20:20:20.202020Z) enables to retrieve records created or updated after the specified timestamp.
  • Pagination (optional)
    • The API may support pagination to limit total number of objects returned by the server in a single request.
    • Query parameters
      • Maximum number of objects is specified by query parameter size
      • The page number is specified by query parameter page

Authentication

The API should support either long lived API key or OAuth 2.0 based JWT token 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 (JWT bearer) provided to API endpoint in HTTP hearer Authorization
  • Required configuration: CLIENT_ID, CLIENT_SECRET, API_AUDIENCE, API_TOKEN_URL

Error handling

  • HTTP 401 Unauthorized response is returned for requests with missing or invalid API key or token
  • HTTP 429 Too Many Requests response is returned if rate limiting was applied to the request with Retry-After header indicating required delay until another attempt

Response

  • JSON message in UTF-8 encoding
  • The response contains collection of objects wrapped in data attribute
  • 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)
Attribute Description
id mandatory, unique record identifier
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": [
    {
      "id": "Ay423ht8aAv3AHR4gRr3",
      "createdAt": "2024-01-21T19:19:19Z",
      "updatedAt": "2024-01-21T19:19:19Z",
      "status": "DELIVERED",
      "delivery": "CARRIER",
      "payment": "CASH",
      "customerId": "Bj60hk9kkPVAH9QBXr2a",
      "currency": "USD",
      "totalPrice": 59.99,
      "totalDiscount": 10,
      "totalShipping": 10,
      "totalTax": 10,
      "items": [
        {
          "productId": "YDrr2ND7H11M2h4dhrfe",
          "productName": "Product Title",
          "quantity": 1,
          "unitPrice": 49.99,
          "totalPrice": 49.99,
          "discountAmount": 10,
          "taxAmount": 10,
        }
      ]   
    }
  ]
}