Hybrid API (EVM) - API Integration

📋 Overview

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

🎯 Integration Overview

The Merso API provides these core endpoints for game integration:

→

/health

API health check
→

/merso-buy-token-with-fiat

Purchase NFT using the Merso PNPL fiat option

📋 Hybrid API Endpoints

1. Health Check

Endpoint: GET /health
Purpose: Verify API connectivity and status

Request:

cURL

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

Response:

JSON

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

JavaScript Example:

JavaScript

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

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": "user@email.com,
    "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 don't 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:

JSON

{
  "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:

JSON

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

JavaScript Example:

JavaScript

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;
  }
}