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:
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={page}&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 |
| page | int | N | The page number 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:
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}"
}'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. Or user is reach user limit to buy for item in body |
| 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. |
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
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
Failed
{
"orderId": "{order-id}",
"clientId": "{your-client-id}",
"userId": "{user-id}",
"requestId": "{your-request-id}",
"timestamp": "2024-04-12T07:41:26.633135053Z",
"status": "Failed",
"errorMessage": "insufficient_balance"
}- errorMessage: Reason for failure (e.g., insufficient_balance, listing_out_of_stock).
Additional Resources
To access URLs for staging or production environments, please refer to the API Overview.