Skip to main content

Integrate with Mavis Store API

Overview

To integrate with Mavis Store, build an endpoint in your backend system that Mavis Store can use to deliver items to users who purchase them:

  • Deliver paid order: https://<merchant-server.hostname>/deliver-items

If you sell off-chain items, you also need to handle user verification by building an endpoint that Mavis Store can use to verify the user's identity:

  • Verify user: https://<merchant-server.hostname>/user (not required for on-chain items)

Prerequisites

Complete the steps in Register as a merchant.

Steps

Step 1. Generate an API key

  1. Go to Mavis Store CMS sandbox.
  2. Log in with your Mavis account.
  3. Click Store Settings > Settings, then scroll down to the Set up your API key section.
  4. 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 an update to your server, allowing your game to distribute the items to the user.

If the item is an on-chain NFT, the user_id is the Ronin address of the buyer that you should deliver the item to, such as 0x6fda69632c0393c6f740323bd402993d933a7b2b. If the item is an off-chain asset, then the user_id is the in-game ID of the user, such as Lunacian_007.

The request body is in the JSON format. The following example shows a delivery request for user Lunacian_007:

POST https://example-merchant.com/deliver-items
Content-Type: application/json
X-API-KEY: "abcde12345"

{
"user_id": "Lunacian_007" // Player ID for off-chain items or Ronin address for on-chain items
"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:

{
"message": "success"
}

Verify user

GET https://<merchant-server.hostname>/user?<user_id>
On-chain vs off-chain items
  • For on-chain items like NFTs, implementing this endpoint is not required. Sky Mavis handles user verification because the buyer must provide their Ronin address at the storefront to purchase on-chain item.
  • For off-chain items, you need to implement this endpoint. Mavis Store will send an API request to your server to verify the user's identity.

Whether an item is on-chain or off-chain is defined during item creation in the Mavis Store CMS. For more information, see Manage items.

Mavis Store needs to verify the user's identity before creating an order. Two user verification methods exist:

  • Through player's Mavis account: If your game uses the Mavis Account service for player authentication, you can choose to verify the user's identity through this service. In this case, the user ID is their Mavis ID specified in the player's Mavis account dashboard, such as 1eda5fc0-76e1-6de4-8449-b3a0fde29125.
  • Through player's in-game user ID: If your game uses its own authentication system, you can allow the player to provide their identity by entering their in-game user ID.

The following example shows a user verification request for the ID Lunacian_007:

GET https://example-merchant.com/user?user_id=Lunacian_007
Content-Type: application/json
X-API-KEY: "abcde12345"

For a successful response, return a 200 HTTP status code. Along with the status code, return the same user ID and the user's real name:

{
"user_id": "Lunacian_007",
"name": "Axie Player"
}

Handle errors

To handle errors related to item validation to order delivery, return the HTTP status codes listed in Mavis Store API reference.

This example shows an error response for verifying a user that doesn't exist:

HTTP/1.1 404 USER_NOT_EXISTS

{
"code": "USER_NOT_EXISTS",
"message": "The user does not exist"
}

Step 3. Save the endpoints in Mavis Store CMS

After implementing the endpoints, go back to Store Settings > Settings in the Mavis Store CMS sandbox, and paste the endpoint URL in the Deliver items field. Click Update to save the changes.

If you also implemented the Verify user endpoint, paste the URL in the User profile field and click Update.

Next steps

Add items to your store using the CMS. For more information, see Manage items.

Was this page helpful?
Happy React is loading...