Skip to main content

Mavis Store API reference

Overview​

The Mavis Store API allows you to integrate your game with Mavis Store, enabling players to purchase in-game items with RON tokens. The API includes two types of endpoints:

  • Outbound endpoints: used to send requests from Mavis Store to your server, such as delivering paid orders and verifying users
  • Inbound endpoints: used to send requests from your server to Mavis Store, such as retrieving order statuses.

Authentication​

The authentication process differs for outbound and inbound requests.

Outbound authentication​

For outbound requests (from Mavis Store to your server), you authenticate using an API key generated in the Mavis Store CMS:

  1. Go to the Mavis Store sandbox CMS or production CMS.
  2. Log in with your Sky Mavis account used for merchant registration.
  3. Navigate to Store Settings > Settings and scroll to the Set up your API key section.
  4. Create a new API key and use it in the X-API-KEY header for requests sent by Mavis Store.

Inbound authentication​

For inbound requests (from your server to Mavis Store), you authenticate using an API key generated in the Developer Console:

  1. Go to the Developer Console.
  2. Log in with your Sky Mavis Account used for merchant registration.
  3. Select the app created for Mavis Store integration.
  4. Copy your key from the KEY field on the Information tab, and use it in the X-API-KEY header for requests sent to Mavis Store.

Example authentication header:

-H 'X-API-KEY: {OUTBOUND_API_KEY}'
-H 'X-API-KEY: {INBOUND_API_KEY}'

Endpoints​

Deliver paid order​

After a user pays for an order, Mavis Store sends a request to your server to deliver the purchased items.

Retry mechanism: if the API returns a non-200 status or times out, Mavis Store retries the request up to three times, at intervals of 1 second, 5 minutes, and 15 minutes.

HTTP request:

POST https://{host}/deliver-items

Request body:

{
    "user_id": "0x9fce82995479fa41cc6f4aa1366f8df9eb574569",
    "order_code": "ADBS5C7EOS",
    "created_at": "2024-11-20T06:42:39.407535Z",
    "payment_method": "ronin",
    "transaction": {
        "type": "purchase",
        "code": "e47a7f97-2879-482f-a5b5-7e9c697ded35",
        "external_id": "0x7c238981e23fae19bc584c9d98159ff3306c2b6e2659901a53d40346b99985f9",
        "paid_by": "0x8E81aa0eA0455F6daAb482acdacEF30e5423A13c",
        "price": {
            "currency": "ron",
            "token_address": "0x0000000000000000000000000000000000000000",
            "amount": "1000000000000000000",
            "decimals": 18
        },
        "created_at": "2024-11-20T06:42:56.911954Z"
    },
    "items": [
        {
            "sku": "onchain_item",
            "quantity": 1,
            "price": {
                "currency": "ron",
                "token_address": "0x0000000000000000000000000000000000000000",
                "amount": "1000000000000000000",
                "decimals": 18
            }
        }
    ]
}

Parameters:

ParameterTypeDescription
user_idStringUser's Ronin address that receives the NFT. The user can manually enter this address in the storefront.
order_codeStringUnique order identifier created by Mavis Store.
created_atStringOrder creation timestamp in ISO 8601 format.
payment_methodStringPayment method used, always set to ronin.
items[index].skuStringUnique SKU of the item as defined in the Mavis Store CMS.
items[index].quantityIntegerQuantity of the purchased item.
items[index].price.currencyStringCurrency of the item's price.
items[index].price.amountStringItem's price in the specified currency.
items[index].price.decimalsIntegerNumber of decimals for the token used in the item's price.
items[index].price.token_addressStringContract address for the token used in the item's price.
transaction.typeStringTransaction type, always set to purchase.
transaction.codeStringTransaction UUID generated by the Mavis Store server.
transaction.external_idStringBlockchain transaction hash on the Ronin chain.
transaction.paid_byStringUser's Ronin address that made the payment.
transaction.price.currencyStringCurrency used for the transaction.
transaction.price.amountStringAmount of currency used for the transaction.
transaction.price.decimalsIntegerNumber of decimals for the token used in the transaction.
transaction.price.token_addressStringContract address for the token used in the transaction.
transaction.created_atStringTransaction creation timestamp in ISO 8601 format.

Response:

HTTP/1.1 200 OK

{
    "message": "success"
}

Verify user​

When the user views an item before placing an order, the storefront sends a GET request to this endpoint to verify whether the user ID entered by the user is valid.

HTTP request:

GET https://{host}/user?user_id={user_id}

Query parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.

Response:

If the user exists, the API responds with the user's details:

HTTP/1.1 200 OK

{
    "user_id": "12345",
    "name": "Player12345"
}

Get personalized items​

Checks whether a user is eligible to purchase specific items. It validates purchase criteria defined in merchant's system, such as stock availability or user-specific restrictions.

HTTP request:

GET https://{host}/items?user_id={user_id}&sku={sku}

Query parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.
skuString arrayList of SKUs for the items as defined in the Mavis Store CMS.

Response:

HTTP/1.1 200 OK

{
    "user_id": "12345",
    "items": [
        {
            "sku": "item001",
            "stock": 10
        },
        { 
            "sku": "item002",
            "stock": 0,
            "reason": "Out of stock"
        }
    ]
}

Response parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.
item[index].skuStringSKU of the item.
item[index].stockIntegerRemaining stock of the item that the user is eligible to purchase. If 0, the item can't be purchased.
item[index].reasonStringReason why the item isn't available for purchase, displayed in the Mavis Store UI. Ensure that the reason is user-friendly.

Validate order before checkout​

Verifies whether a user can purchase specified items before processing the payment. It ensures the requested quantity is available and meets your system's rules.

HTTP request:

POST https://{host}/validate-items

Request body:

{
    "user_id": "12345",
    "items": [
        {
            "sku": "item001",
            "quantity": 2
        },
        {
            "sku": "item002",
            "quantity": 1
        }
    ]
}

Parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.
items[index].skuStringSKU of the item as defined in the Mavis Store CMS.
items[index].quantityIntegerQuantity of the item requested by the user.

Response:

HTTP/1.1 200 OK

{
    "user_id": "12345",
    "items": [
        {
            "sku": "item001",
            "tx_hash": "8d9c5e61-10b8-4b8c-95b8-be2ae55a0631"
        },
        {
            "sku": "item002",
            "tx_hash": "ef181a49-cdc3-4256-aaf5-711f94b6c691"
        }
    ]
}

Parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.
items[index].skuStringUnique alphanumeric ID of the item.
items[index].tx_hashStringUUID generated by the merchant's server. You can lock and prevent the user from buying more than the allowed quantity.

Cancel pre-validation​

Request the cancellation of a pre-validated order.

HTTP request:

POST https://host/cancel-pre-validation

Request body:

{
    "user_id": "12345",
    "items": [
        {
            "sku": "item001",
            "tx_hash": "8d9c5e61-10b8-4b8c-95b8-be2ae55a0631"
        }
    ]
}

Parameters:

ParameterTypeDescription
user_idStringUser's unique identifier in the Sky Mavis Account service (if integrated) or in the merchant's system.
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_hashStringUUID generated by the merchant's server.

Response:

{
    "message": "success"
}

Get order by code​

Retrieve the status and details of an order from Mavis Store.

GET 
https://api-gateway.skymavis.com/store/v1/partner/order/{order_code}

Request parameters:

ParameterTypeDescription
order_codeStringUnique order code created for this order.

Response:

{
    "code": "AD3PHSPON7",
    "user_id": "0x210744c64eea863cf0f972e5aebc683b98fb1981",
    "status": "completed",
    "payment_method": "ronin",
    "transactions": [
        {
           "type": "purchase",
           "external_id": "0x1db7f5d5886f1f13ea321641f2e70f87624b18bf23149473a539a7c44e9ff4f1",
           "paid_by": "0x8E81aa0eA0455F6daAb482acdacEF30e5423A13c",
           "created_at": "2024-06-24T08:38:54.727921Z"
        }
    ]
    "items": [
        {
            "sku": "review-gem-008",
            "quantity": 1,
            "sub_total": "990000"
        }
    ],
    "expired_at": "2024-06-24T15:40:13.081613+07:00",
    "created_at": "2024-06-24T15:25:13.081613+07:00"
}

Response parameters:

ParameterTypeDescription
codeStringUnique order code created for this order.
user_idStringUser's Ronin address that receives the NFT.
statusStringOrder status.
payment_methodStringPayment method used.
transactionsArrayArray of transactions.
transactions[index].typeStringTransaction type as purchase.
transactions[index].external_idStringTransaction hash on the Ronin chain.
transaction[index].paid_byStringUser's Ronin address that made the payment.
transactions[index].created_atStringTransaction creation date.
itemsArrayArray of items in the order.
items[index].skuStringUnique alphanumeric ID of the item.
items[index].quantityIntegerItem quantity.
items[index].sub_totalStringSubtotal of the item (item price times quantity).
expired_atStringOrder expiration date.
created_atStringOrder creation date.

Order status flow​

BackendStorefrontDescription
newUnpaidOrder is created but not paid.
payingPendingUser is making payment for the order.
paidPaidOrder is paid for.
completedCompletedOrder is delivered successfully.
delivered_failedPaidDelivery failed due to server issues.
delivered_rejectedPaidOrder was rejected by the server.
cancelledCancelledOrder was cancelled by the user or system.

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_PARAMETERA parameter in the request is invalid.
400ITEM_OUT_OF_STOCKThe item is out of stock.
400ITEM_EXPIREDThe item validation time has expired.
400INVALID_PURCHASING_AMOUNTThe user can't buy the item with the requested quantity.
401UNAUTHORIZEDInvalid authentication credentials.
404USER_NOT_EXISTSThe user doesn't exist in the system.
404ITEM_NOT_FOUNDThe item isn't available in the system.
500INTERNAL_SERVERAn internal server error occurred.
503SERVICE_UNAVAILABLEThe service is not available.

Error response example:

{
    "code": "INVALID_PARAMETER",
    "message": "Invalid user_id provided."
}