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. For more information about the basic integration, see About integration levels.

Prerequisites​

Steps​

Step 1. Generate an API key​

  1. Go to the Mavis Store sandbox CMS or production CMS, 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 in the X-API-KEY header to authenticate requests from Mavis Store in your backend.

Step 2. Set up the API endpoints in your backend​

Deliver paid order​

POST https://{merchant-server.hostname}/deliver-items

After the user pays for an 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 user. For off-chain items, the user_id is the in-game user ID.

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​

Not required for on-chain items

Don't implement this endpoint if you only sell on-chain items like NFTs. Instead, Sky Mavis handles the verification when the user provides their Ronin Wallet address at the storefront upon purchase. Whether an item is on-chain or off-chain is defined by you when adding the item in the Mavis Store CMS.

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 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.

Example error response:

HTTP/1.1 404 USER_NOT_EXISTS

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

Step 4. Save the endpoints in your store settings​

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