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 (mandatory)",
            "fromAmount": number (optional),
            "toAmount": number (optional),
            "toCurrency": "string" ["USDT", "USDT-TRON", "USDT-AVALANCHE"],
            "fromCurrency": "string" ["EUR", "USD", "AUD", ...],
            "address": "string" (mandatory) Blockchain address to receive the funds,
            "amountDirection": "sending" or "receiving",
            "webhookRef": "string (optional *has to be unique)",
            "returnUrl": "string (optional)",
            "method": "string" (optional ["card *default", "sepa", "pix", "interac"]),
          }

Parameter Explanation

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 = `https://instaxchange.com/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.

Getting blockchain hash

After the payment session is completed, you can get the blockchain hash by making a GET request to https://instaxchange.com/utils/blockchain-status?txId={withdrawTxId} with the withdraw tx ID.

Webhook Response Structure

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

{
  "webhookId": "testcompleteddwebhook",
  "transactionId": "*****",
  "reference": "your_reference",
  "data": {
    "amountInFiat": 3.74,
    "fiatCurrency": "USD",
    "amountInCrypto": 0.0421399418187522,
    "cryptoCurrency": "LTC",
    "status": "completed",
    "statusReason": null,
    "walletAddress": "****",
    "additionalData": {
      "wdId": "123"
    },
    "sessionId": "*****",
    "createdAt": "2024-05-22T19:58:54.097Z"
  },
  "invoiceData": {
    "Email": "[email protected]",
    "Name": "Name Name",
    "Credit_card_number": "4****1111",
    "Invoice_ID": "****",
    "Status": "completed",
    "Wallet_address": "*****",
    "Details": "3.74 USD => 0.043 LTC",
    "Invoice_date": "22nd May, 2024",
    "Deposit_tx_ID": "*****",
    "Deposit_tx_amount": "3.74 USD",
    "Deposit_tx_status": "completed",
    "Withdraw_tx_ID": "*****",
    "Withdraw_tx_amount": "0.0421399418187522 LTC",
    "Withdraw_tx_status": "completed"
  },
  "createdAt": "2024-05-22T19:59:05.913Z"
}

Failed callback example

          {
  "webhookId": "testfailedwebhook",
  "transactionId": "*****",
  "reference": null,
  "data": {
    "amountInFiat": 5,
    "fiatCurrency": "USD",
    "amountInCrypto": 4.78,
    "cryptoCurrency": "USDT-AVALANCHE",
    "status": "failed",
    "statusReason": "Do Not Honor",
    "walletAddress": "****",
    "additionalData": null,
    "sessionId": "****",
    "createdAt": "2024-05-24T06:48:39.279Z"
  },
  "invoiceData": {
    "Email": "[email protected]",
    "Name": "Name Name",
    "Credit_card_number": "4****1111",
    "Invoice_ID": "****",
    "Status": "failed",
    "Wallet_address": "*****",
    "Details": "5 USD => 4.78 USDT-AVALANCHE",
    "Invoice_date": "24th May, 2024",
    "Deposit_tx_ID": "*****",
    "Deposit_tx_amount": "5 USD",
    "Deposit_tx_status": "completed",
    "Withdraw_tx_ID": "****",
    "Withdraw_tx_amount": "4.78 USDT-AVALANCHE",
    "Withdraw_tx_status": "failed"
  },
  "createdAt": "2024-05-24T06:53:29.503Z"
}

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.