Integrate your backend with the Mavis Store API for advanced integration
Overview
To enable the advanced integration with Mavis Store, which includes personalized listings, implement the API endpoints listed in this document in your backend.
Prerequisites
Complete the steps in Register as a merchant.
Steps
Step 1. Generate an API key
- Go to Mavis Store CMS sandbox or production, and log in with your Sky Mavis Account used for merchant registration.
- Click Store Settings > Settings, then scroll down to the Set up your API key section.
- Create a new API key and use it to authenticate requests from Mavis Store.
Step 2. Implement API endpoints
Deliver paid order
POST https://<merchant-server.hostname>/deliver-items
After the user makes payment for the order, Mavis Store sends a receipt to your server, allowing your game to distribute the items to the user.
The user_id parameter in the request body is the Ronin address of the buyer. For off-chain items, the user_id is the in-game ID of the user.
If the API returns a status code different from 200 or times out, Mavis Store will retry the request up to three times at 1 second, 5 minutes, and 15 minutes intervals.
The request body is in the JSON format.
Example request:
POST https://example-merchant.com/deliver-items
Content-Type: application/json
X-API-KEY: "{YOUR_API_KEY}"
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"order_code": "order_007",
"created_at": "2024-01-11T05:46:08Z",
"payment_method": "ronin",
"transaction": {
"type": "purchase",
"code": "f7a3e5d1-4c8a-4e4b-9e8d-6e7f8a9b0c1d",
"external_id": "0x043cdf980d3eaedf48b3058c42e9eacc3ff467662b8525071568eb583c26facb",
"price": {
"currency": "RON",
"amount": "20000000000000000000",
"decimals": "18",
"token_address": "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4"
},
"created_at": "2024-01-11T05:55:24Z"
},
"items": [
{
"sku": "gems_welcome",
"quantity": "2",
"tx_hash": "merchant_tx_hash",
"price": {
"currency": "RON",
"amount": "5000000000000000000",
"decimals": "18",
"token_address": "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4"
}
},
{
"sku": "gems_001",
"quantity": "5",
"tx_hash": "merchant_tx_hash",
"price": {
"currency": "RON",
"amount": "2000000000000000000",
"decimals": "18",
"token_address": "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4"
}
}
]
}
For more information about these parameters, see Mavis Store API reference.
For a successful response, return a 200 HTTP status code along with a confirmation message.
Example response:
{
"message": "success"
}
Verify user
GET https://<merchant-server.hostname>/user?user_id={user_id}
Mavis Store needs to verify the user's identity before creating an order. Two user verification methods exist:
- User's Sky Mavis Account: if your game uses the Sky Mavis Account service for player authentication, you can choose to verify the user's identity through this service.
- User's in-game user ID: if your game uses its own authentication system, you can let the player provide their identity by entering their in-game user ID.
Example request:
GET https://example-merchant.com/user?user_id=1eda5fc0-76e1-6de4-8449-b3a0fde29125
Content-Type: application/json
X-API-KEY: "{YOUR_API_KEY}"
For a successful response, return a 200 HTTP status code along with the same user ID and the user's profile name.
Example response:
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"name": "Lunacian"
}
Get personalized items
GET https://<merchant-server.hostname>/items?user_id={user_id}&sku={sku}
You can have granular control over who can purchase your items. Define the eligibility criteria, such as minimum player rank, purchase limits per season, or even unique conditions based on game progress, in your game logic. Then, share these criteria with your solution engineer. Subsequently, when displaying an item to the user, Mavis Store communicates with your server to determine whether the user meets the defined criteria for purchasing the item.
This feature is part of the advanced integration and applies only to items marked as is_personalized.
The sku values represent unique SKUs (stock keeping units) of each item that the user wants to buy.
Example request:
GET https://example-merchant.com/items?user_id=1eda5fc0-76e1-6de4-8449-b3a0fde29125&sku=gems_welcome&sku=gems_001
Content-Type: application/json
X-API-KEY: "{YOUR_API_KEY}"
For a successful response, return a 200 HTTP status code. Along with the status code, return a JSON object with the items and their quantity. If the user can't buy an item for some reason, indicate the reason in the response as well. For more information about these parameters, see Mavis Store API reference.
Example response:
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"items": [
{
"sku": "gems_welcome",
"stock": 2
},
{
"sku": "gems_001",
"stock": 0,
"reason": "Reason why the user can't buy this item. If SKU is invalid, then return the reason in this field too."
}
]
}
Validate items before checkout
POST https://<merchant-server.hostname>/validate-items
Item validation ensures that the user can buy an item before processing the payment. This prevents double purchases, guarantees fulfillment of limited item offers, or enforces any custom criteria you set in your game logic. To use this feature, you generate a unique hash for each item in its requested quantity, while Mavis Store handles the validation. This feature is part of the advanced integration level and applies only to items marked as is_personalized.
The request body is in the JSON format. It contains the SKUs of the items along with their quantity.
Example request:
POST https://example-merchant.com/validate-items
Content-Type: application/json
X-API-KEY: "{YOUR_API_KEY}"
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"items": [
{
"sku": "gems_welcome",
"quantity": "2"
},
{
"sku": "gems_001",
"quantity": "5"
}
]
}
For a successful response, return a 200 HTTP status code. Along with the code, return a transaction hash that confirms that the user can buy the item in the requested quantity. For more information about these parameters, see Mavis Store API reference.
Example response:
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"items": [
{
"sku": "gems_welcome",
"tx_hash": "merchant_tx_hash"
},
{
"sku": "gems_001",
"tx_hash": "merchant_tx_hash"
}
]
}
Cancel pre-validation
POST https://<merchant-server.hostname>/cancel-pre-validation
When the user cancels an order, Mavis Store sends an update to your server, using the same transaction hashes that you returned after validating the item. This feature is part of the advanced integration level and applies only to items marked as is_personalized.
The request body is in the JSON format. It contains the item that the user wants to cancel, along with the transaction hash that you generated for this item during validation. For more information about these parameters, see Mavis Store API reference.
Example request:
POST https://example-merchant.com/cancel-pre-validation
Content-Type: application/json
X-API-KEY: "{YOUR_API_KEY}"
{
"user_id": "1eda5fc0-76e1-6de4-8449-b3a0fde29125",
"items": [
{
"sku": "gems_welcome",
"tx_hash": "merchant_tx_hash"
},
{
"sku": "gems_001",
"tx_hash": "merchant_tx_hash"
}
]
}
For a successful response, return a 200 HTTP status code along with a confirmation message.
Example response:
{
"message": "success"
}
Step 3. Implement error handling
To handle errors related to item validation to order delivery, return the HTTP status codes listed in Mavis Store API reference.
For example, if the user doesn't exist, return a 404 HTTP status code along with an error message.
HTTP/1.1 404 USER_NOT_EXISTS
{
"code": "USER_NOT_EXISTS",
"message": "The user does not exist"
}
Step 4. Save the endpoints in Mavis Store CMS
After setting up the API endpoints, save them in your store settings in the Mavis Store CMS.
- Go to Store Settings > Settings in the Mavis Store CMS.
- Paste the endpoint URLs in each of the five fields: Deliver items, User profile, Personalized items, Validate purchasable items, and Cancel pre validation.
- Click Update.
