Integrate with Mavis Store API (legacy)

caution

This is legacy documentation used by existing Mavis Store clients. New users should refer to this guide: Integrate with the Mavis Store API.

Overview

To integrate with Mavis Store, you need to implement a number of Mavis Store API endpoints on your server. The required endpoints vary based on your chosen integration level:

• Basic integration: Provides essential functionality for user verification and order delivery.
• Advanced integration: In addition to the basic integration features, offers personalized item listings based on predefined criteria, as well as item validation and order cancellation.

Below is a table outlining the endpoints you need to implement for each integration level:

Endpoint	Basic integration	Advanced integration	Documentation
https://<merchant-server.hostname>/user	Required	Required	Verify user
https://<merchant-server.hostname>/items	Not required	Required	Get personalized items
https://<merchant-server.hostname>/validate	Not required	Required	Validate items before checkout
https://<merchant-server.hostname>/cancel-pre-validation	Not required	Required	Cancel pre-validation
https://<merchant-server.hostname>/deliver-items	Required	Required	Deliver paid order

For more information, see About integration levels.

Prerequisites

Create at least one item in your store. For more information, see List items.

Verify user

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

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

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

Get personalized items

GET https://example-merchant.com/items?user_id={user_id}&sku={sku1}&sku={sku2}

You can have granular control over who can purchase your items. Define eligibility criteria, such as minimum player 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 is part of the advanced integration and applies only to items marked as is_personalized.

The sku values are unique SKUs (stock keeping units) of each item that the user wants to buy. In the following example, user adam_jensen_sarif tries to purchase items gems_welcome and gems_001:

GET https://example-merchant.com/items?user_id=adam_jensen_sarif&sku=gems_welcome&sku=gems_001
Content-Type: application/json
X-API-KEY: "abcde12345"

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 buy an item for some reason, indicate the reason in the response as well. For more information about these parameters, see Mavis Store API reference.

The following example shows the response:

{
    "user_id": "adam_jensen_sarif",
    "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 buy 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 is part of the advanced integration level and applies only to items marked as is_personalized.

The request body is in the JSON format. It contains the SKUs of the items along with their quantity. In the following example, user adam_jensen_sarif is buying items gems_welcome and gems_001:

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

{
    "user_id": "adam_jensen_sarif",
    "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 buy the item in the requested quantity. For more information about these parameters, see Mavis Store API reference.

The following example shows the response:

{
    "user_id": "adam_jensen_sarif",
    "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, using the same transaction hashes that you returned after validating the item. This feature is part of the advanced integration level and applies only to items marked as is_personalized.

The request body is in the JSON format. It contains the item that the user wants to cancel, along with the transaction hash that you generated for this item during validation. For more information about these parameters, see Mavis Store API reference.

In the following example, user adam_jensen_sarif cancels items gems_welcome and gems_001:

POST https://example-merchant.com/cancel-pre-validation
Content-Type: application/json
X-API-KEY: "abcde12345"

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

{
    "message": "success"
}

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