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. For more information about the advanced integration, see About integration levels.
Prerequisites
Complete the steps in Register as a merchant.
Steps
Step 1. Generate an API key
- Go to the Mavis Store sandbox CMS or production CMS, 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 in the
X-API-KEYheader to authenticate requests from Mavis Store in your backend.
Step 2. Contact Sky Mavis to enable personalized items
Advanced integration allows you to personalize item availability for each buyer based on criteria like their rank or progress. To enable this feature, contact your Sky Mavis point of contact.
Step 3. Set up the API endpoints in your backend
Deliver paid order
POST https://<merchant-server.hostname>/deliver-items
After the user makes payment for an order, Mavis Store sends a receipt to your server, allowing your game to distribute the items to the user in-game. The receipt includes the user's in-game ID, the order code, the payment method, the transaction details, and the items purchased.
If the API returns a status code different from 200 or times out, Mavis Store retries the request up to three times at 1 second, 5 minutes, and 15 minutes intervals.
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}
Before creating an order, Mavis Store needs to verify the user's identity. Two verification methods exist:
- Sky Mavis Account user ID: if you use the Sky Mavis Account service for authentication, you can choose to verify the user's identity through this service.
- In-game user ID: if you use your own account service, the user can enter their in-game user ID for verification.
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 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 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 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 purchase.
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 purchase the item, 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 purchase 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 applies only to items marked as is_personalized.
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 purchase 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 with the items to cancel and the same transaction hash that you generated for the item during validation.
This feature applies only to items marked as is_personalized.
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 4. Implement error handling
To handle errors related to item validation to order delivery, return the HTTP status codes listed in Mavis Store API reference.
Example error response:
HTTP/1.1 404 USER_NOT_EXISTS
{
"code": "USER_NOT_EXISTS",
"message": "The user does not exist"
}
Step 5. Save the endpoints in your store settings
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.
