Mavis Store API reference

Overview

This is the reference documentation for the Mavis Store API—a server-side API.

Authentication

We suggest that you authenticate API requests from Mavis Store to your server using an API key passed in the X-API-KEY header:

headers = {
    "X-API-KEY": <merchant_api_key>
}

Verify user

Verifies a user's identity before creating an order. Attempting to verify a non-existent user returns a USER_NOT_EXISTS error.

HTTP request:

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

Query parameters:

Field	Type	Parameter
`user_id`	String	The in-game user ID.

Response:

If successful, the response body contains the name of the user:

HTTP/1.1 200 OK

{
    "user_id": "<string>",
    "name": "<string>"
}

Get personalized items

Verifies whether a user is eligible for purchasing an item, according to the criteria defined in your game's logic. These criteria can be anything you set: minimum player rank, purchase limits per season, or some unique conditions based on game progress. If the item is not eligible for purchase, your server includes the reason in the response.

HTTP request:

GET https://<merchant-server.hostname>/items?user_id=<string>&sku=<string>&sku=<string>

Query parameters:

Field	Type	Parameter
`user_id`	String	The in-game user ID.
`sku`	String array	List of unique alphanumeric IDs of each item, referred to as a stock keeping unit (SKU). The SKUs must be an exact match with the item information metadata that you define when listing the item in the store.

Response body:

HTTP/1.1 200 OK

{
    "user_id": "<string>",
    "items": [
        {
            "sku": "<string>",
            "stock": "<integer>"
        },
        { 
            "sku": "<string>",
            "stock": "<integer>",
            "reason": "<string>"
        }
    ]
}

Fields:

Field	Type	Parameter
`user_id`	String	User ID on the game's server.
`item[index].sku`	String	Unique alphanumeric ID of the item.
`item[index].stock`	Integer	Remaining amount of stock the user can purchase.
`item[index].reason`	String	If the user can't purchase the SKU, return the reason in the response. Mavis Store displays the value of the `reason` field in the user interface, so ensure that the message is clear.

Validate items before checkout

Verifies whether a user can buy an item before processing the payment.

HTTP request:

POST https://<merchant-server.hostname>/validate-items

Request body:

{
    "user_id": "<string>",
    "items": [
        {
            "sku": "<string>",
            "quantity": "<integer>"
        },
        {
            "sku": "<string>",
            "quantity": "<integer>"
        }
    ]
}

Fields:

Field	Type	Parameter
`user_id`	String	User ID on the game's server.
`items[index].sku`	String	Unique alphanumeric ID of the item. The SKU must be an exact match with the item information metadata that you define when listing the item in the store.
`items[index].quantity`	Integer	Item quantity.

Response:

HTTP/1.1 200 OK

{
    "user_id": "<string>",
    "items": [
        {
            "sku": "<string>",
            "tx_hash": "<string>"
        },
        {
            "sku": "<string>",
            "tx_hash": "<string>"
        }
    ]
}

Fields:

Field	Type	Parameter
`user_id`	String	User ID on the game's server.
`items[index].sku`	String	Unique alphanumeric ID of the item.
`items[index].tx_hash`	String	Unique string generated by your server. You can lock and prevent the user from buying more than the allowed quantity.

Cancel pre-validation

Requests cancellation of an order.

HTTP request:

POST https://<merchant-server.hostname>/cancel-pre-validation

Request body:

{
    "user_id": "<string>",
    "items": [
        {
            "sku": "<string>",
            "tx_hash": "<string>"
        },
        {
            "sku": "<string>",
            "tx_hash": "<string>"
        }
    ]
}

Fields:

Field	Type	Parameter
`user_id`	String	User ID on the game's server.
`items[index].sku`	String	Unique alphanumeric ID of the item. The SKU must be an exact match with the item information metadata that you define when listing the item in the store.
`items[index].tx_hash`	String	Your transaction hash.

Response:

HTTP/1.1 200 OK

{
    "message": "success"
}

Deliver paid order

After a user pays for an order, Mavis Store sends an update to your server, allowing your game to distribute the items to the user.

HTTP request:

POST https://<merchant-server.hostname>/deliver-items

Request body:

{
    "user_id": "<string>",
    "order_code": "<string>",
    "created_at": "<string>",
    "payment_method": "<string>",
    "transaction": {
        "type": "purchase",
        "code": "<string>",
        "external_id": "<string>",
        "price": {
            "currency": "<string>",
            "amount": "<string>", 
            "decimals": "<integer>",
            "token_address": "<string>"
        },
        "created_at": "<string>"
    },
    "items": [
        {
            "sku": "<string>",
            "quantity": "<integer>",
            "tx_hash" : "<string>",
            "price": {
                "currency": "<string>",
                "amount": "<string>",
                "decimals": "<integer>",
                "token_address": "<string>"
            }
        },
        {
            "sku": "<string>",
            "quantity": "<integer>",
            "tx_hash": "<string>",
            "price": {
                "currency": "<string>",
                "amount": "<string>",
                "decimals": "<integer>",
                "token_address": "<string>"
            }
        }
    ]
}

Fields:

Field	Type	Parameter
`user_id`	String	User ID on the game's server.
`order_code`	String	Unique order code created for this order.
`created_at`	String	Order creation date that adheres to the ISO 8601 standard.
`payment_method`	String	Payment method used by the buyer. The only accepted value is `ronin`.
`items[index].sku`	String	Unique alphanumeric ID of the item. The SKU must be an exact match with the item information metadata that you define when listing the item in the store.
`items[index].quantity`	Integer	Item quantity.
`items[index].tx_hash`	String	Your transaction hash.
`items[index].price.currency`	String	Currency of the item's price.
`items[index].price.amount`	String	Price of the item in the specified currency.
`items[index].price.decimals`	Integer	Decimals of the token used for the item's price. For example, `18` for RON.
`items[index].price.token_address`	String	Token address on the chain correspondent to the currency.
`transaction.type`	String	Transaction type set to `purchase`.
`transaction.code`	String	Transaction UUID code generated by the the store's server, used to determine a payment transaction for an order.
`transaction.external_id`	String	External ID of the transaction. For example, if the payment method is `ronin`, then `external_id` is the transaction hash on the Ronin chain, such as `0x043cdf980d3eaedf48b3058c42e9eacc3ff467662b8525071568eb583c26facb`. If the payment method is fiat, then `external_id` is the transaction ID from the payment provider.
`transaction.price.currency`	String	Currency with which the buyer paid.
`transaction.price.amount`	String	Transaction amount correspondent to the currency with which the buyer paid.
`transaction.price.decimals`	Integer	Decimals correspondent to the currency with which the buyer paid.
`transaction.price.token_address`	String	Token address correspondent to the currency with which the buyer paid.
`transaction.created_at`	String	Transaction creation date that adheres to the ISO 8601 standard.

Response:

HTTP/1.1 200 OK

{
    "message": "success"
}

Order statuses

A Mavis Store order has a corresponding order status reflecting its state. There are backend statuses and their user-facing counterparts.

Backend status	User-facing status	Description
`new`	Unpaid	Order is just created in the Mavis Store system.
`paying`	Pending	Buyer is making a payment for the order.
`paid`	Paid	Buyer successfully paid for the order.
`completed`	Completed	Order is delivered to the merchant and the system responded with a success.
`delivered_failed`	Paid	Mavis Store is unable to receive a response from the merchant.
`delivered_rejected`	Paid	Order is rejected by the merchant.
`cancelled`	Cancelled	Order is cancelled by Mavis Store or the user.

Status codes

The following table lists the HTTP status codes and corresponding error codes your server returns to Mavis Store:

Code	Error code	Message
`200`	-	Success.
`400`	INVALID_PARAMETER	Invalid parameter
`400`	ITEM_OUT_OF_STOCK	Item is out of stock
`400`	ITEM_EXPIRED	Item validation time is expired
`400`	INVALID_PURCHASING_AMOUNT	User cannot buy the item with the quantity in the order
`401`	UNAUTHORIZED	Invalid authentication credentials
`404`	USER_NOT_EXISTS	User does not exist
`404`	ITEM_NOT_FOUND	Item is not available in the system
`500`	INTERNAL_SERVER	Internal server error
`503`	SERVICE_UNAVAILABLE	Service is not available

Error response example:

HTTP/1.1 400 ITEM_OUT_OF_STOCK

{
    "code": "<string>",
    "message": "<string>"
}

Was this helpful?

Happy React is loading...

Overview​

Authentication​

Verify user​

Get personalized items​

Validate items before checkout​

Cancel pre-validation​

Deliver paid order​

Order statuses​

Status codes​

Overview

Authentication

Verify user

Get personalized items

Validate items before checkout

Cancel pre-validation

Deliver paid order

Order statuses

Status codes