Marketplace API Integration Guide (Beta)

In this guide, we'll show you all the information you need to get started, from obtaining access tokens to making API calls and handling callbacks.

Begin development in the staging environment to test and debug the integration. Once testing is successful, promote the integration to the production environment for live usage.

Getting Started

Here's a simplified overview of how the integration works: !The overview of checkout flow

Noted: integrate the marketplace API with signature

To integrate the marketplace API with signature, you need to generate an RSA keypair by following this manual How to Generate an RSA Keypair.

Obtain Credentials

First, obtain the necessary credentials from the organization owner. You'll need the the following information to authenticate your requests.

Client ID
Client secret

Request Token

Next, make an API call to request a token for authentication.

Obtain Credentials

curl --location '{abc-auth-url}/realms/partner/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={your-client-id}' \
--data-urlencode 'client_secret={you-client-secret}' \
--data-urlencode 'grant_type=client_credentials'

Call the API to retrieve listing list on marketplace

Once you have the token, you can use it to call listing information list that sell on marketplace.

Call Get Listing API

curl --location --request GET '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/products?tokenType={token-type}&status={status}&limit={limit}&skip={skip}&sort={sorting}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access-token}'

Key	Type	Required	Description	Example
marketplace-baseurl	string	Y	The base URL of the marketplace.	https://api-stg.abc-dev.network/latitude/marketplaces (opens in a new tab)
org-id	string	Y	The ID of organization.	762ab685-70b7-4bf4-9ae3-bbd4e59c9ce2
marketplace-address	string	Y	The marketplace contract address.	0xd987F18f0e7BdaAfBD8F0628084Ca353A8905AEb
token-type	string	N	The type of token. `Deals` - coupon or lucky draw, `Caper` - cashback	Deals Caper
status	string	N	The status of the listing	live scheduled end sold_out
limit	int	N	The number of items to return. Default=10, Min=1, Max=1000	10
skip	int	N	The amount of skipped items to return. Default=0, Min=0	0
sorting	string	N	The sorting order of the listing.	startTimestamp:asc startTimestamp:desc
access-token	string	N	The access token obtained from the previous step.	-

Response

Get Listing Response

{
    "items": [
        {
            "status": "live",
            "stock": 92,
            "price": 1,
            "discountedPrice": 1,
            "productStartDate": "2024-09-18T05:00:00Z",
            "productEndDate": "2024-09-29T17:00:00Z",
            "listingId": "121",
            "contractId": "0xcbecb5389e677953685b7d7611fb2d4bf5712a10",
            "tokenId": "7",
            "owner": "0x92258317dD9b7087B170DaDEEbfD697a09eCBC24",
            "assetContractId": "0xf54ec3459840ce27ff87af366422c0f3db9d677d",
            "currency": {
                "contractAddress": "0xd2243378630beb69175355199b287817ddcc2a28",
                "symbol": "TMC",
                "name": "TrueMoney Coin"
            },
            "tokenType": "Caper",
            "asCaper": {
                "id": "0xf54ec3459840ce27ff87af366422c0f3db9d677d_7",
                "metadata": [
                    {
                        "id": "QmaJ1mfajv938n9qvcKFCEzjNRe68HjCurHXGL8yCnvw2w/metadata-th.json",
                        "locale": "th",
                        "name": "แคลช-20240712-2129",
                        "description": "แคลช-20240712-2129",
                        "image": "/reward-callbacks/579bd5d9-3a7f-4d6c-af93-7744504bae4d/6371386a72706439707063646337736768673730.jpeg",
                        "prefix": "ABC",
                        "campaignId": "1513177",
                        "campaignName": "ABC_CB_01",
                        "shortDescription": "แคลช-20240712-2129",
                        "tnc": "แคลช-20240712-2129",
                        "value": "10"
                    },
                    {
                        "id": "QmaJ1mfajv938n9qvcKFCEzjNRe68HjCurHXGL8yCnvw2w/metadata.json",
                        "locale": "en",
                        "name": "cashback-20240712-2129",
                        "description": "cashback-20240712-2129",
                        "image": "/reward-callbacks/579bd5d9-3a7f-4d6c-af93-7744504bae4d/6371386a72706439707063646337736768673730.jpeg",
                        "prefix": "ABC",
                        "campaignId": "1513177",
                        "campaignName": "ABC_CB_01",
                        "shortDescription": "cashback-20240712-2129",
                        "tnc": "cashback-20240712-2129",
                        "value": "10"
                    }
                ]
            },
            "userLimit": 0
        },
        {
            "status": "live",
            "stock": 1,
            "price": 10,
            "discountedPrice": 10,
            "productStartDate": "2024-09-05T12:12:00Z",
            "productEndDate": "2024-11-06T17:00:00Z",
            "listingId": "114",
            "contractId": "0xcbecb5389e677953685b7d7611fb2d4bf5712a10",
            "tokenId": "4",
            "owner": "0x92258317dD9b7087B170DaDEEbfD697a09eCBC24",
            "assetContractId": "0x9eec777557be96ecf18792b80add54cbb27ceed9",
            "currency": {
                "contractAddress": "0xd2243378630beb69175355199b287817ddcc2a28",
                "symbol": "TMC",
                "name": "TrueMoney Coin"
            },
            "tokenType": "Deals",
            "asDeal": {
                "id": "0x9eec777557be96ecf18792b80add54cbb27ceed9_4",
                "metadata": [
                    {
                        "id": "QmS3TQU1k9fNVDyn7UVfVtxDpfo3iZdwe7kL5ETa2qoSDV/metadata-th.json",
                        "locale": "th",
                        "name": "ดีล-20240826-1527",
                        "description": "ดีล-20240826-1527",
                        "image": "https://vms-light-sto-dev.abc.abc-dev.network/ba5ff802cd17821e528322a63864257b.png",
                        "startDateTime": "2024-08-25T17:00:00Z",
                        "endDateTime": "2025-12-31T17:00:00Z",
                        "tagline": "ดีล-20240826-1527",
                        "value": "10000",
                        "redemptionCTA": "กรุณาแสดงรหัสนี้แก่เจ้าหน้าที่เพื่อแลกรับสิทธิ์",
                        "dealStatus": "Published",
                        "tnc": "ดีล-20240826-1527",
                        "thumbnail": "https://vms-light-sto-dev.abc.abc-dev.network/ba5ff802cd17821e528322a63864257b.png",
                        "bgPicture": "https://vms-light-sto-dev.abc.abc-dev.network/a3a79f0f9f35d856d19ad1f1c5bb6964.png",
                        "dealType": "rewards_catalogue",
                        "categoryName": "อาหารและเครื่องดื่ม",
                        "categorySequence": "1",
                        "merchantName": "พ่อค้า-20240814-0923",
                        "merchantImage": "https://vms-light-sto-dev.abc.abc-dev.network/d350b314daf2e7d634983683be65ee70.jpeg"
                    },
                    {
                        "id": "QmS3TQU1k9fNVDyn7UVfVtxDpfo3iZdwe7kL5ETa2qoSDV/metadata.json",
                        "locale": "en",
                        "name": "deal-20240826-1527",
                        "description": "deal-20240826-1527",
                        "image": "https://vms-light-sto-dev.abc.abc-dev.network/ba5ff802cd17821e528322a63864257b.png",
                        "startDateTime": "2024-08-25T17:00:00Z",
                        "endDateTime": "2025-12-31T17:00:00Z",
                        "tagline": "deal-20240826-1527",
                        "value": "10000",
                        "redemptionCTA": "Please show this code to the staff to redeem your privilege.",
                        "dealStatus": "Published",
                        "tnc": "deal-20240826-1527",
                        "thumbnail": "https://vms-light-sto-dev.abc.abc-dev.network/ba5ff802cd17821e528322a63864257b.png",
                        "bgPicture": "https://vms-light-sto-dev.abc.abc-dev.network/a3a79f0f9f35d856d19ad1f1c5bb6964.png",
                        "dealType": "rewards_catalogue",
                        "categoryName": "F\u0026B",
                        "categorySequence": "1",
                        "merchantName": "merchant-20240814-0923",
                        "merchantImage": "https://vms-light-sto-dev.abc.abc-dev.network/d350b314daf2e7d634983683be65ee70.jpeg"
                    }
                ]
            },
            "userLimit": 0
        }
    ],
    "limit": 10,
    "skip": 0
}

Upon making the API call with any option, you will receive one of the following HTTP responses:

HTTP	Message	Description
200	OK	The API request has been successfully, and the listing information is returned.
400	Invalid Request	Your request contains invalid parameters. Ensure all parameters are correct and try again.
401	Access Denied	Your request lacks sufficient scope permissions. Make sure your authentication credentials have the necessary access rights.
403	Access Forbidden	Your client is not authorized to access this resource. Check your client credentials and ensure they are properly authenticated.
500	Internal Server Error	An internal server error occurred. Please try your request again later. If the issue persists, contact support for assistance.

Call the API to checkout listing on marketplace

Once you have the token and listing information, you can use it to make API calls to checkout asynchronously. We provide two options for making the API call, with or without signing.

Call the API to checkout listing on marketplace without Signing

If your system does not support signing, you can make the API call without the signature. Here's an example of it:

Call Checkout API

curl --location '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access-token}' \
--data '{
    "userId": "{user-id}",
    "currencyAddr": "{point-address}",
    "items": [
        {
            "listingId": "{listing-id}",
            "quantity": {quantity},
            "price": {price},
            "subTotal": {subtotal}
        },
        {
            "listingId": "{listing-id}",
            "quantity": {quantity},
            "price": {price},
            "subTotal": {subtotal}
        }
    ],
    "requestId": "{your-request-id}",
    "callbackUrl": "{your-callback-url}"
}'

Key	Type	Required	Description	Example
marketplace-baseurl	string	Y	The base URL of the marketplace.	https://api-stg.abc-dev.network/latitude/marketplaces (opens in a new tab)
org-id	string	Y	The ID of organization.	762ab685-70b7-4bf4-9ae3-bbd4e59c9ce2
marketplace-address	string	Y	The marketplace contract address.	0xd987F18f0e7BdaAfBD8F0628084Ca353A8905AEb
user-id	string	Y	User ID.	tmn.10003227577
point-address	string	Y	The point contract address that that used to exchange for checkout process.	0x85aabefbd40be95c9dec4938598d3faf6a7adb27
listing-id	string	Y	The ID of listing.	1
quantity	int	Y	The quantity of listing. Min=1	5
price	int	N	The price of the listing.	10
subtotal	int	N	The result of price multiply with quantity.	50
requestId	string	Y	Your request ID.	req-123456
callbackUrl	string	N	The URL to receive the callback result.	-
access-token	string	N	The access token obtained from the previous step.	-

Call the API to checkout listing with Signature on marketplace

If you would like to make the call more secure, you can make the API call with the signature by using this example:

To send a request with a signature (algorithm RSA-SHA256), you need to include the following headers: Note: To implement API call with Signature, Please send your Public Key and contact us to enable it for you.

Call Checkout with signature API

curl --location '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Digest: SHA-512={base64Hash}' \
--header 'Signature: keyId="${key}",algorithm="RSA-SHA256",created=${timestampInSec},headers="(created) digest (request-target)",signature="${sign}"' \
--data '{
    "userId": "{customer-user-id}",
    "currencyAddr": "{point-address}",
    "items": [
        {
            "listingId": "{listing-id}",
            "quantity": {quantity},
            "price": {price},
            "subTotal": {subtotal}
        },
        {
            "listingId": "{listing-id}",
            "quantity": {quantity},
            "price": {price},
            "subTotal": {subtotal}
        }
    ],
    "requestId": "{your-request-id}",
    "callbackUrl": "{your-callback-url}"
}'

Key	Type	Required	Description	Example
key	string	Y	The id of key.	Use this keyId for non-production: `762ab685-70b7-4bf4-9ae3-bbd4e59c9ce2-org-app6`
base64Hash (Digest)	string	Y	The hash of the request body. Use the appropriate hashing function SHA-512 to calculate it.	YnyHYeo9LprkBxoNlWydejXL/f7sQEZveNlfdpX18BafqgRD6yxLQN8zacdXNRtwploIsq+Vjkv6lc6Y/leg5w==
timestampInSec	number	Y	Current Unix timestamps in seconds.	1729033199
sign (Signature)	The digital signature for the HTTP request. This signature ensures the authenticity and integrity of the request by allowing the server to verify that the request has not been tampered with and that it comes from a trusted source by verifying the signature with the corresponding public key.	Y	User ID.	tmn.10003227577

Upon making the API call with any option, you will receive one of the following HTTP responses:

HTTP	Message	Description
200	OK	The checkout is accepted and processed. A callback will be sent to the specified callback URL with the processing result.
400	Invalid Request	Your request contains invalid parameters. Ensure all parameters are correct and try again.
401	Access Denied	Your request lacks sufficient scope permissions. Make sure your authentication credentials have the necessary access rights.
403	Access Forbidden	Your client is not authorized to access this resource. Check your client credentials and ensure they are properly authenticated.
500	Internal Server Error	An internal server error occurred. Please try your request again later. If the issue persists, contact support for assistance.

Incase user reach the limit of the listing, you will get 400 http status code with this response.

Checkout Response

{
  "error": "reach_user_limit_to_buy"
}

Response In case of created order successful (http status 200), you will get this information.

Checkout Response

{
  "orderId": "{order-id}",
  "workflowId": "{workflow-id}"
}

Key	Type	Description	Example
order-id	string	The ID of order.	KN3mXlP
workflow-id	string	The workflow ID of checkout, you can use it to get current status of order.	mkp-order-buy-0x54aad8d0FAC1bD1B2b2A1a36522F92e6dB20F419-309

Check Order Status

After the order created, It will not be accomplished immediately. But it will be fulfilled in order. You can use this endpoint to get current status of order. Or wait for callback result if you provide callbackUrl in checkout API.

Check Order Status

curl --location '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/order/{wofkflow-id}' \
--header 'Authorization: Bearer {access-token}'

Response

Check Order Status Response

{
  "status": "{status}",
  "error": "{error-message}"
}

Key	Type	Description	Example
status	string	The order status, possible value `Completed` - order fulfullied, `Failed` - order failed to fulfill	Completed, Failed
error-message	string	error message in case order failed

Handling Callback Results

After making the API call to checkout listing on marketplace, you'll receive a callback with the processing result.

Completed

{
  "orderId": "{order-id}",
  "clientId": "{your-client-id}",
  "userId": "{user-id}",
  "requestId": "{your-request-id}",
  "timestamp": "2024-04-12T07:41:26.633135053Z",
  "status": "Completed"
}

orderId: Order ID from our system.
clientId: Your client ID.
userId: User ID.
requestId: Your request ID.
timestamp: Finish timestamp of the order.
status: Status of the order (Completed or Failed).

Failed

{
  "orderId": "{order-id}",
  "clientId": "{your-client-id}",
  "userId": "{user-id}",
  "requestId": "{your-request-id}",
  "timestamp": "2024-04-12T07:41:26.633135053Z",
  "status": "Failed",
  "error": "insufficient_balance"
}

error: The error code for failure.

error	Description
listing_out_of_stock	The listing is out of stock.
insufficient_balance	Not enough points to redeem.
invalid_currency	Invalid currency.
listing_not_start	The listing is not started yet.
listing_expired	The listing is expired.
listing_not_found	The listing is not found.
price_mismatch	The price of the listing is mismatch.
internal_server_error	Internal server error.

Handling Callback Results with Signature

If you send the checkout request with a signature, you will receive a callback with Signature headers. You can use public key to verify the signature and ensure the authenticity of the callback result. Here's an example of the callback result:

Checkout callback with signature

curl --location '{callbackURL}' \
--header 'Content-Type: application/json' \
--header 'Digest: SHA-512={base64Hash}' \
--header 'Signature: keyId="${key}",algorithm="RSA-SHA256",created=${timestampInSec},headers="(created) digest (request-target)",signature="${sign}"' \
--data '{
  "orderId": "{order-id}",
  "clientId": "{your-client-id}",
  "userId": "{user-id}",
  "requestId": "{your-request-id}",
  "timestamp": "2024-04-12T07:41:26.633135053Z",
  "status": "Completed"
}'

Key	Type	Required	Description	Example
key	string	Y	The id of key.	Use this keyId for non-production: `762ab685-70b7-4bf4-9ae3-bbd4e59c9ce2-org-app6`
base64Hash (Digest)	string	Y	The hash of the request body. Use the appropriate hashing function SHA-512 to calculate it.	YnyHYeo9LprkBxoNlWydejXL/f7sQEZveNlfdpX18BafqgRD6yxLQN8zacdXNRtwploIsq+Vjkv6lc6Y/leg5w==
timestampInSec	number	Y	Current Unix timestamps in seconds.	1729033199
sign (Signature)	The digital signature for the HTTP request. This signature ensures the authenticity and integrity of the request by allowing the server to verify that the request has not been tampered with and that it comes from a trusted source by verifying the signature with the corresponding public key.	Y	User ID.	tmn.10003227577

Additional Resources

To access URLs for staging or production environments, please refer to the API Overview.

API Integration Guide How Generate Rsa Keypair