Skip to main content

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={user_id}

Query parameters:

ParameterTypeDescription
user_idStringIn-game user ID.

Response:

If successful, the response body contains the profile 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={user_id}&sku={sku}

Query parameters:

ParameterTypeDescription
user_idStringIn-game user ID.
skuString arrayList 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>"
}
]
}

Parameters:

ParameterTypeDescription
user_idStringIn-game user ID.
item[index].skuStringUnique alphanumeric ID of the item.
item[index].stockIntegerRemaining amount of stock the user can purchase.
item[index].reasonStringIf 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>"
}
]
}

Parameters:

ParameterTypeDescription
user_idStringIn-game user ID.
items[index].skuStringUnique 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].quantityIntegerItem quantity.

Response:

HTTP/1.1 200 OK

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

Parameters:

ParameterTypeDescription
user_idStringIn-game user ID.
items[index].skuStringUnique alphanumeric ID of the item.
items[index].tx_hashStringUnique 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>"
}
]
}

Parameters:

ParameterTypeDescription
user_idStringIn-game user ID.
items[index].skuStringUnique 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_hashStringYour 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>"
}
}
]
}

Parameters:

ParameterTypeDescription
user_idStringUser ID on the game's server.
order_codeStringUnique order code created for this order.
created_atStringOrder creation date that adheres to the ISO 8601 standard.
payment_methodStringPayment method used by the buyer. The only accepted value is ronin.
items[index].skuStringUnique 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].quantityIntegerItem quantity.
items[index].tx_hashStringYour transaction hash.
items[index].price.currencyStringCurrency of the item's price.
items[index].price.amountStringPrice of the item in the specified currency.
items[index].price.decimalsIntegerDecimals of the token used for the item's price. For example, 18 for RON.
items[index].price.token_addressStringToken address on the chain correspondent to the currency.
transaction.typeStringTransaction type set to purchase.
transaction.codeStringTransaction UUID code generated by the store's server, used to determine a payment transaction for an order.
transaction.external_idStringTransaction hash on the Ronin chain, such as 0x043cdf980d3eaedf48b3058c42e9eacc3ff467662b8525071568eb583c26facb.
transaction.price.currencyStringCurrency with which the buyer paid.
transaction.price.amountStringTransaction amount correspondent to the currency with which the buyer paid.
transaction.price.decimalsIntegerDecimals correspondent to the currency with which the buyer paid.
transaction.price.token_addressStringToken address correspondent to the currency with which the buyer paid.
transaction.created_atStringTransaction 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 statusUser-facing statusDescription
newUnpaidOrder is just created in the Mavis Store system.
payingPendingBuyer is making a payment for the order.
paidPaidBuyer successfully paid for the order.
completedCompletedOrder is delivered to the merchant and the system responded with a success.
delivered_failedPaidMavis Store is unable to receive a response from the merchant.
delivered_rejectedPaidOrder is rejected by the merchant.
cancelledCancelledOrder 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:

Status codeError codeDescription
200-Success.
400INVALID_PARAMETERInvalid parameter
400ITEM_OUT_OF_STOCKItem is out of stock
400ITEM_EXPIREDItem validation time is expired
400INVALID_PURCHASING_AMOUNTUser cannot buy the item with the quantity in the order
401UNAUTHORIZEDInvalid authentication credentials
404USER_NOT_EXISTSUser does not exist
404ITEM_NOT_FOUNDItem is not available in the system
500INTERNAL_SERVERInternal server error
503SERVICE_UNAVAILABLEService is not available

Error response example:

HTTP/1.1 400 ITEM_OUT_OF_STOCK

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