Parameters
Complete reference of all parameters for configuring the modal via POST body or postMessage.
Modal URLs
Use these base URLs when embedding the modal in your application. All POST requests should be sent to /modal endpoint.
Development
DEV
Use this URL for testing and development environments.
https://modal.dev.merso.io/modalProduction
PROD
Use this URL for live production environments.
https://modal.merso.io/modal
Your form's action attribute or fetch request should target the appropriate URL based on your environment. See the Quick Start guide for complete examples.
General Parameters
jwtToken
string
Required*
JWT token for API authentication. Obtained from the /auth endpoint.
Example: jwtToken=eyJhbGciOiJIUzI1NiIs...
productType
string
Required*
The type of product being purchased.
Values: ITEM or NFT
paymentMode
string
Optional
Pre-select the payment mode to skip the payment type selection.
Values: BNPL or UPFRONT
gameName
string
Optional
Display name of the game (for display purposes only).
Example: gameName=My Awesome Game
Item Parameters (Web2)
Required when productType=ITEM or for Web2 payment flows.
itemPrice
float
Required
Price of the item in USD.
Example: itemPrice=29.99
itemId
integer
Required
Unique identifier for the item in your system.
Example: itemId=12345
itemName
string
Required
Display name of the item.
Example: itemName=Premium Sword
playerEmail
string
Required
Email address of the player making the purchase.
Example: playerEmail=player@example.com
playerLevel
integer
Required
Current level of the player in the game.
Example: playerLevel=42
playerCountry
string
Required
ISO country code of the player.
Example: playerCountry=US
NFT Parameters (Web3)
Required when productType=NFT or for Web3 payment flows.
walletAddress
string
Required
User's wallet address to receive the NFT.
Example: walletAddress=0x1234...abcd
collectionAddress
string
Required
Smart contract address of the NFT collection.
Example: collectionAddress=0xNFT...collection
tokenId
string
Required
ID of the specific token to mint.
Example: tokenId=42
tokenPrice
string
Required
Price of the token in native currency or USD (for card payments).
Example: tokenPrice=0.05 or tokenPrice=100
tokenName
string
Optional
Display name of the NFT.
Example: tokenName=Epic Dragon #42
userEmail
string
Optional
Email for receipts and notifications.
Example: userEmail=user@example.com
chainId
string
Optional
Blockchain network ID (defaults to collection's chain).
Example: chainId=1 (Ethereum), chainId=137 (Polygon)
tokenAddress
string
Optional
ERC-20 token address for payment (defaults to collection's token).
Example: tokenAddress=0xUSDC...
Example Body Payloads
These payloads can be sent via POST body (hidden form) or postMessage to the modal.
Item Purchase (Web2)
{
"jwtToken": "eyJhbGciOiJIUzI1NiIs...",
"productType": "ITEM",
"itemPrice": "29.99",
"itemId": "123",
"itemName": "Premium Sword",
"playerEmail": "player@example.com",
"playerLevel": "42",
"playerCountry": "US"
}NFT Purchase (Web3)
{
"jwtToken": "eyJhbGciOiJIUzI1NiIs...",
"productType": "NFT",
"walletAddress": "0x1234567890abcdef",
"collectionAddress": "0xNFTCollection",
"tokenId": "42",
"tokenPrice": "100",
"tokenName": "Epic Dragon",
"userEmail": "user@example.com",
"chainId": "1"
}Item with PNPL Pre-selected
{
"jwtToken": "eyJhbGciOiJIUzI1NiIs...",
"productType": "ITEM",
"paymentMode": "BNPL",
"itemPrice": "99.99",
"itemId": "456",
"itemName": "Legendary Armor",
"playerEmail": "hero@game.com",
"playerLevel": "50",
"playerCountry": "UK"
}