Payment Session API Integration Guide

This document explains how to initiate a payment session by making a POST request to /api/session. It covers the necessary JSON payload and the significance of each parameter.

POST Request Payload

To create a payment session, send a JSON payload with the following structure in your POST request to /api/session:

          {
            "accountRefId": "string (optional)",
            "fromAmount": number (optional),
            "toAmount": number (optional),
            "toCurrency": "string" ["USDT", "USDT-TRON", "USDT-AVALANCHE"],
            "fromCurrency": "string",
            "address": "string" (optional) Blockchain address to receive the funds,
            "amountDirection": "sending" or "receiving",
            "webhookRef": "string (optional)"
            "returnUrl": "string (optional)"
          }
        

Parameter Explanation

• accountRefId: (Optional) A unique identifier for the user's account in your system.
  Note: To find your accountRefId you can click here !make sure you are logged in.
• fromAmount: (Optional) The amount of currency being sent. This is required if 'amountDirection' is set to 'sending'.
• toAmount: (Optional) The amount of currency to be received. This is required if 'amountDirection' is set to 'receiving'.
• toCurrency: The type of currency to convert to. Should be a valid currency code.
• fromCurrency: The type of currency being sent. Should be a valid currency code.
• address: If the address is specified it will be locked to the specific address
• amountDirection: Specifies the direction of the amount; can be either 'sending' or 'receiving'. Determines which amount (fromAmount or toAmount) needs to be specified.
• webhookRef: (Optional) A reference value you provide. This value will be included in the webhook callback (which you set in dashboard), allowing you to identify which session corresponds to.
• returnUrl: (Optional) The URL to redirect the user to after the payment session is completed. If set on receipt there will be a button "Return to store" which will redirect the user to the specified URL.

Understanding 'Sending' and 'Receiving'

If 'amountDirection' is set to 'sending', you must specify 'fromAmount', 'fromCurrency', and 'toCurrency'. The 'toAmount' will be calculated automatically. This is useful for cases where you want to send a specific amount of currency, like sending a fixed amount of fiat currency.

If 'amountDirection' is set to 'receiving', you must specify 'toAmount', 'fromCurrency', and 'toCurrency'. The 'fromAmount' will be calculated automatically. This is particularly useful when you want to lock a specific amount in a currency, like receiving an exact amount of cryptocurrency (e.g., 10 USDT).

Using the Session ID

After successfully creating a session, use the returned session ID to construct the iframe link as follows:

// Constructing the iframe link
const iframeLink = `/embed/${sessionId}`;
        

Embed this link in your webpage to integrate the payment session interface for your users.

Understanding Webhooks and 'webhookRef'

Webhooks provide a mechanism for your system to receive real-time notifications about payment session events. When a session is completed (either successfully or unsuccessfully), a webhook notification will be sent to the URL you configured in your dashboard.

The `webhookRef` parameter allows you to include a custom reference value within this webhook notification. This helps you associate the received webhook with a specific session, user, or other relevant data within your own system. Here's how it works:

1. When creating a payment session, include a meaningful `webhookRef` value in the POST request payload.
2. Once the payment session is completed, your configured webhook URL will receive a notification.
3. This notification will include the `webhookRef` value you originally provided, enabling you to easily identify the context of the payment session event.

Webhook Response Structure

Here's a breakdown of the data you might receive in a webhook from InstaXchange:

{
  "webhookId": "clpl4f5560006f2bunxsdadas", // Unique webhook event ID
  "reference": "useremail@gmail.com",      // Your provided webhookRef
  "createdAt": "2023-12-14T16:35:32.067Z", // Timestamp
  "data": {
    "amountInFiat": 10,
    "amountInCrypto": 6.618183975739509,
    "status": "completed",
    "walletAddress": "0x86fc93B0d881C780...",
    "additionalData": {
      "estCompleteTime": "12/15/2023, 12:28:55 AM",
      "state": "Pending withdrawal",
      "txId": "",
      "wdId": "133076593"
    }
  }
}
        

Security: Using a Secret Key

For additional security, you can set up a secret key in your InstaXchange dashboard. This key is included in the headers of webhook requests (as `X-Instaxwh-Key`) to verify that the webhook is authentic and originated from InstaXchange.

To match the key we send in the header you have to encode the payload you receive, order it by key and hash it with the secret key you set in your dashboard.

// Typescript code example
          const sortedObjectByKey = {};
  sortedKeys.forEach((key) => {
    sortedObjectByKey[key] = body[key];
  });

  const key = createHash("md5")
    .update(`${JSON.stringify(sortedObjectByKey)}:${webhook.secret}`)
    .digest("hex");

  const headers = {
    "Content-Type": "application/json",
    "X-InstaXWH-KEY": key,
  };

// PHP code example

// Assuming $body is your associative array and $webhookSecret is your secret
$body = ...; // Payload from webhook
$webhookSecret = ...; // Your secret

// Sort the array by key
ksort($body);

// JSON encode the sorted array and append the secret
$stringToHash = json_encode($body, JSON_UNESCAPED_SLASHES) . ':' . $webhookSecret;

// Generate the MD5 hash
$key = md5($stringToHash);

echo $key;

        

Important: You'll need to configure your webhook URL and set up your secret key within your InstaXchange dashboard to start receiving webhook notifications.