Skip to content

SoyCap.io API Reference

This document provides a complete reference for SoyCap.io’s API endpoints, which are divided into two main types:

  • Offchain API Endpoints – These endpoints are used to manage merchant-related data outside the blockchain, such as merchant and campaign details, conversion metadata, and other offchain data.
  • Onchain API Endpoints – These endpoints help construct properly formatted Solana transaction details, including SoyCap.io Solana Program serialized data. The transaction details are then used to create and sign Solana transactions using the campaign owner’s keypair.

Offchain API Endpoints Overview

Merchant Authentication

Authenticates the merchant using an API key and returns an auth_token for secure access to other API endpoints.

Endpoint: GET /merchants/authenticate

Headers:

  • X-API-Key (string, required): Your merchant API key.

Responses:

Http CodeResponse
200{ "token": "auth_token_here" }
401{"error":"Unauthorized", "message": "Invalid API key"}
500{"error":"Server Error"}

Code Sample:

const authenticateMerchant = async (apiUrl, apiKey) => {
  const response = await fetch(`${apiUrl}/merchants/authenticate`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey,
    },
  });


  if (!response.ok) {
    const errorResponse = await response.json();
    throw new Error(`Error: ${errorResponse.error} - ${errorResponse.message}`);
  }


  const data = await response.json();
  return data.token;
};

Update Conversion

Endpoint: /conversions/offchain/:conversionId
Method: PATCH
Description: Updates conversion metadata off-chain, such as adding a business value for ROI tracking.

Parameters (URL path):

  • conversionId (string, required): The ID of the conversion to update.

Request Body:

  • campaignId (string, optional): The campaign ID associated with the conversion.
  • referralId (string, optional): The referral ID associated with the conversion.
  • businessValue (number, optional): The monetary value attributed to this conversion.

Headers:

  • Authorization (string, required): Bearer token (auth_token) obtained from merchant authentication.

Code Sample:

const updateConversion = async (conversionId, metadata, token) => {
  const requestUrl = `${apiUrl}/conversions/offchain/${conversionId}`;


  const response = await fetch(requestUrl, {
    method: 'PATCH',
    body: JSON.stringify(metadata),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
  });


  if (!response.ok) {
    const errorResponse = await response.json();
    throw new Error(`Error: ${errorResponse.error} - ${errorResponse.message}`);
  }


  const data = await response.json();
  return data;
};

Get Register Conversion Transaction Details

Endpoint: /conversions/onchain/create/:referralId/:publicKey/:amount
Method: GET
Description: Retrieves transaction details necessary for creating a new conversion. This information is used to build and sign a transaction on the SoyCap.io Solana program.

Parameters (URL path):

  • referralId (string, required): The referral ID for which the conversion is being registered.
  • publicKey (string, required): The public key of the merchant’s keypair.
  • amount (number, required): The reward amount in USDC to be distributed to the affiliate.

Headers:

  • Authorization (string, required): Bearer token (auth_token) obtained from merchant authentication.

Code Sample:

const getRegisterConversionTransactionInstruction = async (referralId, amount, publicKey, token) => {
  const requestUrl = `${apiUrl}/conversions/onchain/create/${referralId}/${publicKey}/${amount}`;


  const response = await fetch(requestUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
  });


  if (!response.ok) {
    const errorResponse = await response.json();
    throw new Error(`Error: ${errorResponse.error} - ${errorResponse.message}`);
  }


  const data = await response.json();
  return data;
};

Get Distribute Reward Transaction Details

Endpoint: /distributions/onchain/create
Method: POST
Description: Retrieves transaction details necessary for distributing a reward for a specific conversion. This data is used to build and sign a transaction for the SoyCap.io Solana program.

Request Body:

  • campaignId (string, required): The campaign ID associated with the reward distribution.
  • referralId (string, required): The referral ID associated with the conversion.
  • conversionId (string, required): The ID of the conversion being rewarded.
  • owner (string, required): The public key of the campaign owner.

Headers:

  • Authorization (string, required): Bearer token (auth_token) obtained from merchant authentication.

Code Sample:

const getDistributeRewardTransactionInstruction = async (campaignId, referralId, conversionId, publicKey, token) => {
  const requestUrl = `${apiUrl}/distributions/onchain/create`;


  const response = await fetch(requestUrl, {
    method: 'POST',
    body: JSON.stringify({
      campaignId,
      referralId,
      conversionId,
      owner: publicKey,
    }),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
  });


  if (!response.ok) {
    const errorResponse = await response.json();
    throw new Error(`Error: ${errorResponse.error} - ${errorResponse.message}`);
  }


  const data = await response.json();
  return data;
};

Get Merchant Details

Get Campaign Details

Get Campaign Conversions

Get Unpaid Campaign Conversions