Skip to main content

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, your server needs to accept API calls from Mavis Store. The required endpoints vary based on your chosen integration level:

  • Basic integration: provides essential flows for user verification and order delivery.
  • Advanced integration: offers personalized item listings based on predefined criteria, as well as item validation and order cancellation.

The following table outlines the endpoints merchants need to implement for each integration level:

EndpointBasic integrationAdvanced integrationDocumentation
https://<merchant-server.hostname>/userRequiredRequiredVerify user
https://<merchant-server.hostname>/itemsNot requiredRequiredGet personalized items
https://<merchant-server.hostname>/validateNot requiredRequiredValidate items before checkout
https://<merchant-server.hostname>/cancel-pre-validationNot requiredRequiredCancel pre-validation
https://<merchant-server.hostname>/deliver-itemsRequiredRequiredDeliver 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>

Mavis Store needs to verify the user's identity before creating an order. Two user verification methods exist:

  • Through player's Mavis account: If your game uses the Mavis Account service for player authentication, you can choose to verify the user's identity through this service. In this case, the user ID is their Mavis ID specified in the player's Mavis account dashboard, such as 1eda5fc0-76e1-6de4-8449-b3a0fde29125.
  • Through player's 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.

The following example shows a user verification request for the ID Lunacian_007:

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

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 represent unique SKUs (stock keeping units) of each item that the user wants to buy. The following example shows user Lunacian_007 buying items gems_welcome and gems_001:

GET https://example-merchant.com/items?user_id=Lunacian_007&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": "Lunacian_007",
"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 Lunacian_007 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": "Lunacian_007",
"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": "Lunacian_007",
"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 Lunacian_007 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": "Lunacian_007",
"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 shows a delivery request for user Lunacian_007:

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

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

Was this page helpful?
Happy React is loading...