Integrate with Mavis Store API

Overview

To integrate with Mavis Store, set up the following Mavis Store API endpoints on your server:

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

After the implementation, your backend can verify the identity of the buyer and deliver their order.

Prerequisites

Register as a merchant. For more information, see Register as a merchant.

Verify user

GET https://<merchant-server.hostname>/user?<user_id>

Before Mavis Store can create an order, the user needs to provide their identity, such as the in-game user ID, Mavis ID, or Ronin Wallet address that receives the item after a successful purchase.

On-chain vs off-chain items

• If you sell on-chain items, you don't need to implement this endpoint. Since buyers must provide their Ronin addresses at the storefront to purchase these items, user verification is managed by Sky Mavis.
• If you sell off-chain items, implement the endpoint still, because Mavis Store makes API requests 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 offers two user verification methods:

• Verification through 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 that receives the in-game items is the same as the user ID in the player's Sky Mavis account.
• Verification through an 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.

For example, the following verifies the user with the ID adam_jensen_sarif:

GET https://example-merchant.com/user?user_id=adam_jensen_sarif
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": "adam_jensen_sarif",
    "name": "Adam Jensen"
}

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.

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

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

{
    "user_id": "adam_jensen_sarif",
    "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"
}

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"
}

See also

Mavis Store API reference