Skip to main content

Integrate your backend with the Mavis Store API for basic integration

Overview​

To enable the basic integration with Mavis Store, implement the API endpoints listed in this document in your backend.

Prerequisites​

Steps​

Step 1. Generate an API key​

  1. Go to Mavis Store CMS sandbox or production, and log in with your Sky Mavis Account used for merchant registration.
  2. Click Store Settings > Settings, then scroll down to the Set up your API key section.
  3. 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. If the item is an NFT, then when you receive a receipt from Mavis Store, your backend server must handle NFT minting and transfer the NFT to the user's address.

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.

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}
On-chain vs off-chain items
  • For on-chain items like NFTs, implementing this endpoint is not required. Sky Mavis handles user verification when the buyer provides their Ronin Wallet address at the storefront to purchase the on-chain item.
  • For off-chain items, you need to implement this endpoint. Mavis Store sends 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 Add items.

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. In this case, the user ID is the UUID specified in the their account management dashboard, such as 1eda5fc0-76e1-6de4-8449-b3a0fde29125.
  • 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.

The following example shows a user verification 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"
}

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.

  1. Go to Store Settings > Settings in the Mavis Store CMS.
  2. Paste the endpoint URL in the Deliver items field.
  3. If you also implemented the Verify user endpoint, paste the URL in the User profile field.
  4. Click Update.

store-settings-api

Next steps​

Add items to your store using the CMS