Payment Session API Integration Guide

Migration Notice: iframe-only checkout Required

We’re simplifying and hardening our integration. From September 16, 2025, only the iframe flow will be supported.

Legacy widget embeds will be turned off on the date above.
Load checkout exclusively via iframe.
Add the attributes below so we can safely verify the top-level URL and referrer.

<iframe
  src="{PAYMENT_SESSION_URL}"
  allow="clipboard-read; clipboard-write; fullscreen; payment"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  referrerpolicy="strict-origin-when-cross-origin"
  style="width: 100%; height: 100%; border: 0;"></iframe>

Important: set src from our Widget URL API at runtime. It validates your domain and issues a secure, time-bound URL.

Questions? Please contact us, we are happy to help.

This document explains how to initiate a payment session by making a POST request to https://instaxchange.com/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" ["USDC", "USDC_POLYGON"],
    "fromCurrency": "string" ["EUR", "USD", "AUD", ...],
    "address": "string" (mandatory) Your 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), 'ideal','bancontact','apple-pay','google-pay', 'interac', 'pix', 'blik']),
    "email": "string (optional)",
    "firstName": "string (optional)",
    "lastName": "string (optional)",
    "country": "string (optional, 2 letter ISO code)",
}

Parameter Explanation

accountRefId: A unique identifier for the user's account in your system (Provided by us).
fromAmount:Required if amountDirection is sending.
toAmount:Required if amountDirection is receiving.
toCurrency: Target currency code.
fromCurrency: Source currency code.
address: If set, the session is locked to this address (should also be set in dashboard).
amountDirection: sending or receiving, determines which amount you provide.
webhookRef: Echoed back in webhooks for correlation.
returnUrl: Auto redirects to, from receipt.
method: One of: card (default), ideal, bancontact, apple-pay, google-pay, interac, pix, blik.

Understanding 'Sending' and 'Receiving'

If amountDirection is sending, specify fromAmount, fromCurrency, and toCurrency. We compute toAmount.

If amountDirection is receiving, specify toAmount, fromCurrency, and toCurrency. We compute fromAmount.

Using the Session ID

After creating a session, build the iframe URL like:

const iframeLink = `https://instaxchange.com/order/${sessionId}`;

Embed this link to show the checkout.

Checking Session Status

You can check the status of a session at any time by making a GET request to:

GET https://instaxchange.com/api/session/{sessionId}/status

Authentication: Include your API key (provided by us) in the x-api-key header.

x-api-key: YOUR_API_KEY

The response includes the current status and transaction details:

{
  "sessionId": "string",
  "webhookRef": "string | null",
  "address": "string",
  "sessionStatus": "initiated" | "pending" | "processing" | "completed" | "failed",
  "depositId": "string | null",
  "depositStatus": "string | null",
  "withdrawalID": "string | null",
  "withdrawStatus": "string | null",
  "fromAmount": number,
  "toAmount": number,
  "fromCurrency": "string",
  "toCurrency": "string",
  "createdAt": "string (ISO 8601)",
  "updatedAt": "string (ISO 8601)"
}

Understanding Webhooks and `webhookRef`

We POST real-time events to your configured webhook URL. Include a custom webhookRef when creating the session to correlate events in your system.

Webhook Response Structure

status is completed or failed.
Check invoiceData.Deposit_tx_status to confirm the user’s payment status.

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

Set a secret key in your dashboard. We include an X-InstaXWH-KEY header on webhooks. Re-create the hash by JSON-encoding the payload sorted by keys and appending your secret, then MD5.

// TypeScript
const sortedKeys = Object.keys(body).sort();
const sorted: Record<string, unknown> = {};
for (const k of sortedKeys) sorted[k] = (body as any)[k];
const key = createHash("md5")
  .update(`${JSON.stringify(sorted)}:${webhook.secret}`)
  .digest("hex");

// PHP
ksort($body);
$key = md5(json_encode($body, JSON_UNESCAPED_SLASHES) . ':' . $webhookSecret);

Note: Configure your webhook URL and secret in the dashboard.