Points Bank API

Use these APIs to leverage the qiibee blockchain as the single source of truth that keeps track of all your loyalty transactions (reward, redeem& exchange) and customer point balances.

Get User Balances

GET /users/:auth_id/balances

The id and auth_id are 2 different fields and are not interchangeable.

When using our Loyalty API, if you want to take an action on a user’s account, you need to use the auth_id.

The auth_id can be set by you if you register users using our Loyalty API. So, for example, you could set it to the primary key you have for the user in your own systems. This saves you the trouble of creating another column to map users in your system to the user profile with qiibee.

However, if you prefer qiibee that generates a new unique identifier for every new user registration, simply leave the auth_id field empty when creating the user and we will generate a UUID-v4 and return it to you so you can save it in your system. The user_id shown in the Loyalty Whitelabel App (LWA) frontend is different from the auth_id and is used exclusively for the LWA frontend.

Will return an array of balances with the token type (erc20 or erc721).

Token types

erc20 is a regular token
erc721 is an NFT token
fiat represents fiat currencies
miles represents the miles tokens
crypto represents cryptocurrencies
donation represent donation campaigns
gift_card represent gift cards

Token countries

AAA represents that the token is operational worldwide.

eg.

{
    "data": [
        {
            "balance": 100,
            "token": {
                "id": "23421",
                "address": "0x..924",
                "name": "My Token Name",
                "countries": ["USA", "IND"]
                "symbol": "MTN",
                "onramp": "2.42",
                "offramp": "2.35",
                "estimated_member_count_lower": 1000,
                "estimated_member_count_higher": 5000,
                "status": null | "pending" | "approved" | "rejected",
                "type": "erc20",
                "metadata": { "key": "value" }
            }
        },
        {
            "nft_ids": ["0", "1"],
            "token": %{
                "address": "0x..924",
                "id": 150,
                "metadata": {"key": "value"},
                "name": "My NFT Token",
                "onramp": null,
                "offramp": null,
                "symbol": "TKNN",
                "type": "erc721"
            }
        }
    ]
}

Responses

Success: HTTP 200 with an array of balances
Bad data: HTTP 404 with error message
- eg. not found

Get user engravings

GET /nfts

This endpoint retrieves all of the user's personalised data. The user's auth_id must be sent with the user_auth_id query param - this is mandatory in order to get the user's data. The data is returned for all of your NFTs.

{
    "data": [
        {
            "nfts": [
                %{
                    "personalised_data": { "key": "value" },
                    "status": null | "pending" | "approved" | "rejected",
                    "user_nft_id": 86
                },
                %{
                    "personalised_data": { "key": "value" },
                    "status": null | "pending" | "approved" | "rejected",
                    "user_nft_id": 87
                }
            ],
            "token": %{
                "address": "0x..924",
                "id": 150,
                "metadata": {"key": "value"},
                "name": "My NFT Token",
                "onramp": null,
                "offramp": null,
                "symbol": "TKNN",
                "type": "erc721"
            }
        }
    ]
}

Responses

Success: HTTP 200 with an array of NFT data or empty array if no data present.

Credit/Debit Points

POST /transactions

The following transaction/loyalty event types are supported to perform points bank transactions:

credit_points - credit point's to a user's account
- eg. reward a user for spends
debit_points - debit points from a user's account
- eg. redeem points for a reward like a coupon

Based on the transaction type the body will differ.

All fields are mandatory.

If you try to debit more points than the user currently has you'll receive a 400.

Body:

amount can be an integer or string. Must be greater than 0.
send_email (optional) can be used only for type credit_points
- Defaults: false.
- To setup emails for your brand, please write to us at [email protected].

{
    "transaction": {
        "user_auth_id": "d0d15b76-1928-46bb-9927-8ffbf802455f",
        "type": "credit_points" | "debit_points",
        "amount": "100",
        "token_id": 12,
        "send_email": true | false
    }
}

Responses

Accepted: HTTP 202 If send_email has been set to true, the email will be sent to the registered email ID of the user with user_auth_id .
Bad Request: HTTP 400
- eg. unknown transaction type
Bad data: HTTP 404 with error message
- eg. not found

Transaction History

GET /transactions

This request returns paginated transaction history.

By default, it returns the last 100 transactions associated with your brand. The most recent transactions are returned first.

You can query transactions using the following query parameters:

limit: (optional) sets the required limit of transaction history to be requested.
- Defaults: 100
- Maximum: 100
offset: (optional) number of transactions to offset when getting the remaining transactions.
- Default: 0
user_auth_id: (optional) Use this parameter to query transactions for a particular user of your brand. If not passed returns all the transactions for your brand. Can be used along with limit and offset.
types: (optional) Use this parameter to query transactions for specific loyalty event types. The events must be sent in a list.
- Defaults: List of all loyalty event types
token_id: (optional) This will let you query the transactions for a specific token ID.
- Defaults: All tokens that belong to the brand.
from_time: (optional) queries for transactions that begin from the specified datetime.
- Defaults: The datetime at which the brand was created in the qiibee database.
to_time: (optional) queries for transactions until the specified datetime.
- Defaults: The current datetime.

Time parameters

In the time parameters, the date and time must be expressed according to ISO 8601.

eg: The datetime for 06 June 2022 at 11:23:23 AM will be expressed as 2022-06-01T11:23:23Z

The params, limit and offset, work exactly as they’re used in SQL.

Token types

erc20 is a regular points bank token
erc721 is an NFT token
external is a non points bank token
fiat represents fiat currencies
miles represents the miles tokens
crypto represents cryptocurrencies
donation represent donation campaigns

Token countries

AAA represents that the token is operational worldwide.

Responses

Success: HTTP 200 with data in the following format:

{
    "data": {
        "limit": 1,
        "offset": 0,
        "total_tx_count": 25,
        "transactions": [
            {
                "amount_received": "1.00000",
                "brand": null,
                "brand_to": {
                    "brand_config": null,
                    "id": "test_brand2",
                    "locations": [],
                    "name": "Test Brand 2"
                },
                "code": null,
                "exchange_provider": "etihad" | "miles_and_more",
                "id": 706,
                "inserted_at": "2021-09-27T14:31:10",
                "loyalty_event_type": "credit_points",
                "points_burned": null,
                "reward_id": null,
                "status": "success",
                "token": {
                    "id": "3276728",
                    "address": "033Bd49F3ace247112AA6D3d16d24L9Eb5533b17",
                    "metadata": {},
                    "name": "WORKING POINT TOKEN",
                    "estimated_member_count_lower": 1000,
                    "estimated_member_count_higher": 5000,
                    "symbol": "TKN",
                    "type": "erc20" | "erc721",
                    "countries": <list_of_ISO3166_country_codes>,
                    "onramp": "24.2" | null,
                    "offramp": "23.5" | null,
                    "status": "active" | "paused" | "pending"| "stopped" | null
                },
                "token_to": {
                    "id": "3276726",
                    "address": "056Bd49F3ace247112AA6D3d16d24L9Vb5533b17",
                    "metadata": {},
                    "name": "WORKING POINT TOKEN 2",
                    "estimated_member_count_lower": 1000,
                    "estimated_member_count_higher": 5000,
                    "symbol": "TKN",
                    "type": "erc20" | "erc721",
                    "countries": <list_of_ISO3166_country_codes>,
                    "onramp": "24.2" | null,
                    "offramp": "23.5" | null,
                    "status": "active" | "paused" | "pending"| "stopped" | null
                },
                "tx_hash": "0x..xx26",
                "user": {
                    "auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
                    "country_ISO": "usa",
                    "email": "[email protected]",
                    "first_name": "Jane",
                    "second_name": "Doe",
                    "id": "NH3HQ==-87b7-2bcd-46ac-b426-0bb81",
                    "language": "en",
                    "metadata": null | {
                        "opts_newsletter": true | false
                     }
                },
                "user_to": {
                    "auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
                    "country_ISO": "usa",
                    "email": "[email protected]",
                    "first_name": "John",
                    "second_name": "Doe",
                    "id": "NH3HQ==-8745-2bcd-46ac-b426-0bb81",
                    "language": "en",
                    "metadata": null | {
                        "opts_newsletter": true | false
                     }
                }

            }
        ]
    }
}

If there are no transactions, an empty transactions list will be returned. total_tx_count is the total number of transactions available for the given params.

Bad data: HTTP 404 with error message
- eg. not found

PreviousPoints Exchange API NextPoints Engine API

Last updated 1 year ago

Was this helpful?