Overview

The Product Catalog API allows retrieval of a list of products that can be used for placing orders with the Flow1st API. This API uses GET to retrieve the product information and returns a JSON response containing details about each product.

Integrating this will enable Flow1st Products to be shown on the Flow1st Partner’s frontend screens.

Pre Requisites

An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)

API Description

Headers

Header	Description/Value
AccessToken	This is the Access Token field returned from the Authentication - Generate Access Token response. This should be in the format `Bearer <AccessToken>`
Content-Type	`application/vnd.carry1st.products.distributorproduct+json`

URL Format

To retrieve a list of available payment methods, make a GET request to the following endpoint:

GET /api/distributors/products/:externalId

Response

The API will respond with a JSON object containing an array of products

{
    "externalId": "258a026b-1287-4e04-a52c-5ecf145d82c8",
    "name": "Asphalt 9: Legends",
    "imageLocation": "https://img.carry1st.com/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6IjI0YzJmMjU2LTE5NWItNGI2Mi1hMzU5LWExOTI1MDA5OWNlNC5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
    "vatRate": 7.5,
    "withholdingTaxRate": 0,
    "playerIdLabel": "Player ID",
    "inStock": true,
    "maxItemsAllowed": 0,
    "status": "ACTIVE",
    "productFulfilmentType": "DIRECT_TOPUP",
    "createdDate": "2026-02-13 08:51:50",
    "lastModifiedDate": "2026-02-13 08:51:50",
    "bundles": [
        {
            "name": "3000 Tokens",
            "sku": "SWARMIO_3000_Tokens",
            "retailPrice": 98.72,
            "distributorPrice": 97.72,
            "currencyCode": "USD",
            "imageLocation": "https://img.carry1st.com/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6IjI0YzJmMjU2LTE5NWItNGI2Mi1hMzU5LWExOTI1MDA5OWNlNC5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
            "inStock": true,
            "maxItemsAllowed": 1,
            "status": "SUSPENDED",
            "createdDate": "2026-02-13 08:51:50",
            "lastModifiedDate": "2026-02-13 08:51:50",
            "fields": [
                {
                    "id": 10701,
                    "productBundleId": 13243,
                    "name": "player-id",
                    "type": "input",
                    "label": "Player ID",
                    "multiline": false,
                    "placeholder": "Please enter Player ID",
                    "prefix": "",
                    "position": 1
                },
                {
                    "id": 10702,
                    "productBundleId": 13243,
                    "name": "player-platform-select",
                    "type": "select",
                    "label": "player-platform",
                    "multiline": false,
                    "placeholder": "",
                    "prefix": "",
                    "position": 2,
                    "options": [
                        {
                            "label": "Windows",
                            "value": "Windows"
                        },
                        {
                            "label": "Android",
                            "value": "Android"
                        },
                        {
                            "label": "IOS",
                            "value": "IOS"
                        }
                    ]
                }
            ]
        }
    ]
}

Product Fields

Name	Type	Description
createdDate	String	The timestamp when the product was created
externalID	String	The identifier that can be used for this Product.
inStock	Boolean	True if this product is in stock
imageLocation	String	The HTTP location of the Product image
lastModifiedDate	String	The timestamp when the product was updated
maxItemsAllowed	Number	(Ignore for now) Indicates the maximum quantity that can be bought from this product
name	String	The name of the product
playerIdLabel	String	The UI label that can be used for the `recipientIdentifier`
productFulfilmentType	String	The type of fulfilment. Possible values are `DIRECT_TOPUP, VOUCHER_CODE, REDIRECT_LINK`
status	String	The Status of this Product. Valid statuses are `ACTIVE, SUSPENDED, DELETED`
vatRate	Number	If this is a Pay1st Business Product, this is the VAT Rate applied when calculating the `distributorPrice`
withholdingTaxRate	Number	If this is a Pay1st Business Product, this is the WithHolding Tax Rate applied when calculating the `distributorPrice`
bundles	Array[ProductBundle]	An array of bundles

Product Bundle Fields

Name	Type	Description
currencyCode	String	The currency code for the price
createdDate	String	The timestamp when the product was created
distributorPrice	Number	The price that will be deducted from the Distributor’s account balance
imageLocation	String	The HTTP location of the ProductBundle image
inStock	Boolean	True if this product is in stock
lastModifiedDate	String	The timestamp when the product was updated
maxItemsAllowed	Number	(Ignore for now) Indicates the maximum quantity that can be bought from this product bundle
name	String	The name of the product bundle
retailPrice	Number	For a Retail Business Product, this is the suggested retail price For a Pay1st Business Product, this is the amount to charge customers
sku	String	The string identifier of the product to use for Completing Orders
status	String	The Status of this Product. Valid statuses are `ACTIVE, SUSPENDED, DELETED`
fields	Array[Fields]	If a product bundle requires extra fields to be sent in user validation, they will be specified here. Fields should be considered to be dynamic content.

"Fields" Properties

These are the properties of the Fields Object. Partners need to assume that "Field" objects will be different per product. Fields are considered to be dynamic content and can be updated based on the context of the Product (e.g. A direct topup product could migrate from playerID to playerID + serverOption).

Name	Type	Description
id	Number	A numeric identifier of the field
productBundleId	Number	A numeric identifier of a product bundle
name	String	The name of the field to use in User Validation APIand Order Completion API
type	String	The type of the field. Possible values are `input` and `select`
label	String	This is the suggested frontend label that can be used for customers
multiline	Boolean	Allows multiple lines
options	Array[Option]	If the `type=select`, then this will be populated with options
placeholder	String	Input placeholder text. This can be used on the frontend
prefix	String	Text prefix for input
position	Number	Display order position. This is used for frontend purposes

Options Properties

Name	Type	Description
label	Number	The frontend label to display to the customer
value	Number	The field value to use in User Validation API and Order Completion API

HTTP Response Codes

The List Payment Method API may return the following HTTP Response Codes:

HTTP Status Code	Name	Description
200	Success	This indicates that the request has been successful
401	Unauthorized	The Access Token might be missing or invalid (see Authentication - Generate Access Token)
403	Forbidden	The credentials provided might not have access to the resources required

Error Handling

See Handling Error Codes for more details on handling error responses.

Query Single Product Catalog API