Skip to main content

Integrate your backend with the Mavis Store API for basic integration

Overview​

To enable the basic integration with Mavis Store, implement the API endpoints listed in this document in your backend. For more information about the basic integration, see About integration levels.

Prerequisites​

Steps​

Step 1. Generate an API key​

  1. Go to the Mavis Store sandbox CMS or production CMS, and log in with your Sky Mavis Account used for merchant registration.
  2. Click Store Settings > Settings, then scroll down to the Set up your API key section.
  3. Create a new API key and use it in the X-API-KEY header to authenticate requests from Mavis Store in your backend.

Step 2. Set up the API endpoints in your backend​

  1. After the user pays for an order, Mavis Store sends a receipt to the /deliver-items endpoint in your system, allowing you to distribute the item to the wallet address the user entered in the storefront. Implement this endpoint in your backend to receive the receipt:

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

    Example request:

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

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

    For a successful response, return a 200 HTTP status code along with a confirmation message:

    HTTP/1.1 200 OK

    {
        "message": "success"
    }

    Retry mechanism: if the /deliver-items 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.

  2. After receiving the receipt, handle the minting and transfer of the NFT to the user's address.

For more information about these parameters, see Mavis Store API reference.

Step 3. Implement error handling​

To handle errors related to item validation to order delivery, return the HTTP status codes listed in Mavis Store API reference.

Example error response:

HTTP/1.1 404 USER_NOT_EXISTS

{
    "code": "USER_NOT_EXISTS",
    "message": "The user does not exist"
}

Step 4. Save the endpoints in your store settings​

After setting up the API endpoints, save them in your store settings in the Mavis Store CMS.

  1. Go to Store Settings > Settings in the Mavis Store CMS.
  2. Paste the endpoint URL in the Deliver items field.
  3. If you also implemented the Verify user endpoint, paste the URL in the User profile field.
  4. Click Update.

store-settings-api

Next steps​

Add items to your store using the CMS