Hybrid API

This page shows you how to integrate Merso using traditional payments for paying NFTs. This means that your players will pay the NFT using fiat money.

🎯 Integration Overview

The Merso API provides this core endpoints for game integration:

• /health - API health check

• /merso-buy-token-with-fiat - Purchase NFT using the Merso PNPL fiat option.

📋 Web2 API Endpoints

1. Health Check

Endpoint: GET /health

Purpose: Verify API connectivity and status

Request:

curl -X GET "https://api3.dev.merso.io/health"

Response:

{
  "success": true,
  "message": "Merso Backend is running",
}

JavaScript Example:

async function checkAPIHealth() {
  try {
    const response = await fetch(`https://api3.dev.merso.io/health`, {
      method: 'GET',
      headers: headers
    });
    
    const data = await response.json();
    console.log('API Status:', data.status);
    return data;
  } catch (error) {
    console.error('Health check failed:', error);
  }
}

2. Buy token with fiat

Endpoint: POST /merso-buy-token-with-fiat

Purpose: Send the fiat payment data to the player. Purchase NFT. You can choose between PNPL or Upfront payment. New optional param added.

Request :

curl -X POST https://api3.dev.merso.io/merso-buy-token-with-fiat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
    "tokenPriceInUSD": NFT_PRICE_IN_DOLLARS,
    "tokenId": NFT_ID,
    "tokenName": NFT_NAME,
    "userAddress": "0x1234567890123456789012345678901234567890",
    "userEmail": "[e-mail],
    "collectionAddress": "YOUR_GAME_ERC721_ADDRESS",
    "paymentMode: "DESIRED_PAYMENT_MODE"
  }'

Parameters:

• tokenPriceInUSD (number): The price of the NFT in USD.

• tokenId (number): NFT token ID to purchase.

• tokenName (string): The name of the NFT.

• userAddress (string): The user's wallet address.

• userEmail (string): User's in-game email.

• collectionAddress (string): The smart contract address of the NFT collection.

OPTIONAL:

• paymentMode (string): Desired way to pay the asset. Values must be: "BNPL" or "UPFRONT". Default in case you dont want/need it to send is set as "BNPL".

Response:

Depending on the payment mode selected we give concrete response to each request:

• BNPL payment response:

{
  "paymentIntentId":"STRIPE_PAYMENT_INTENT_ID",
  "clientSecret":"STRIPE_CLIENT_SECRET",
  "firstPaymentAmount": "HALF_OF_THE_TOTAL_NFT_PRICE",
  "weeklyPaymentAmount": "WEEKLY_PAYMENT_AMOUNT",
  "totalAmount": "NFT_TOTAL_PRICE",
  "message":"BNPL setup completed"
}

• Upfront/full payment response:

{
  "paymentIntentId":"STRIPE_PAYMENT_INTENT_ID",
  "clientSecret":"STRIPE_CLIENT_SECRET",
  "totalAmount": "NFT_TOTAL_PRICE",
  "message":"UPFRONT payment setup completed"
}

JavaScript Example:

async function buyTokenWithFiat(tokenPriceInUSD, tokenId, tokenName, userAddress, userEmail, collectionAddress) {
  try {
	const response = await fetch(
        `https://api3.dev.merso.io/merso-buy-token-with-fiat`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${jwtToken}`,
          },
          body: JSON.stringify({
            tokenPriceInUSD: tokenPriceInUSD,
            tokenId: tokenId,
            tokenName: tokenName,
            userAddress: userAddress,
            userEmail: userEmail,
            collectionAddress: collectionAddress,
            paymentMode: paymentMode
          }),
        }
      );
    
      if (!response.ok) {
        throw new Error("Failed to process card payment");
      }
      
      const responseData = await response.json();

      // Your function to show the payment form
      if(paymentMode === "BNPL"){
      showStripePanel(responseData.paymentIntentId, responseData.clientSecret, responseData.firstPaymentAmount, responseData.weeklyPaymentAmount)
      } else if( paymentMode === "UPFRONT"){
        showStripePanel(responseData.paymentIntentId, responseData.clientSecret, responseData.totalAmount)
      }
  } catch (error) {
    console.error('Failed to process card payment:', error);
    throw error;
  }
}