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:
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.
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 the GET /orgs/{org}/marketplaces/{marketplace}/products endpoint to retrieve listing information from the marketplace.
To use whitelist/blacklist filter, send userId in query params. Please see detail in openapi file.
curl --location --request GET '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/products?tokenType={tokenType}&status={status}&limit={limit}&skip={skip}&sort={sort}&userId={userId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access-token}'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. Please see openapi for more detail. POST /orgs/{org}/marketplaces/{marketplace}/order
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. Please see openapi for more detail. POST /orgs/{org}/marketplaces/{marketplace}/order
Here's an example of it:
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.
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.
{
"error": "reach_user_limit_to_buy"
}| Error Code | Description |
|---|---|
checkout_listing_denied | User is not allowed to purchase this listing due to permission restrictions (whitelist/blacklist) |
reach_user_limit_to_buy | User has reached their purchase limit for this item |
user_wallet_not_found | User wallet address was not found in the system |
Response
In case of created order successful (http status 200), you will get this information.
{
"orderId": "{order-id}",
"workflowId": "{order-id}"
}| Key | Type | Description | Example |
|---|---|---|---|
| order-id | string | The ID of order. | KN3mXlP |
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.
curl --location '{marketplace-baseurl}/orgs/{org-id}/marketplaces/{marketplace-address}/order/{workflowId}' \
--header 'Authorization: Bearer {access-token}'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:
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.