### Install Dependencies and Run Server (Bash)

Source: https://ironixpay.com/blog/accept-usdt-payments

This Bash command installs the necessary Node.js packages, `express` and `dotenv`, using npm. Following the installation, it shows how to start the server by running the `server.js` file.

```bash
npm install express dotenv
node server.js
```

--------------------------------

### Full Server Example: Create Checkout and Receive Webhook (JavaScript)

Source: https://ironixpay.com/blog/accept-usdt-payments

This comprehensive JavaScript example integrates IronixPay checkout session creation and webhook handling within a single Express.js server. It requires `dotenv` for environment variables and `express` for server setup. The code defines routes for creating checkout sessions and processing incoming webhooks, including signature verification.

```javascript
require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

const SECRET_KEY = process.env.IRONIXPAY_SECRET_KEY;
const WEBHOOK_SECRET = process.env.IRONIXPAY_WEBHOOK_SECRET;
const API_BASE = 'https://sandbox.ironixpay.com';

// --- Create Checkout Session ---
app.use('/public', express.static('public'));
app.use(express.json());

app.post('/create-checkout', async (req, res) => {
  const response = await fetch(`${API_BASE}/v1/checkout/sessions`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: req.body.amount || 10000000,
      currency: 'USDT',
      network: 'TRON',
      success_url: `http://localhost:3000/public/success.html`,
      cancel_url: `http://localhost:3000/public/cancel.html`,
      client_reference_id: req.body.orderId,
    }),
  });
  const session = await response.json();
  res.json({ id: session.id, url: session.url });
});

// --- Webhook Receiver ---
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-signature'];
  const ts = req.headers['x-timestamp'];
  const body = req.body.toString();

  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Bad signature');
  }

  const event = JSON.parse(body);
  console.log(`[Webhook] ${event.event_type}:`, JSON.stringify(event.data, null, 2));

  if (event.event_type === 'session.completed') {
    // ✅ Payment confirmed — fulfill the order
    console.log(`💰 Order paid: ${event.data.amount_received / 1e6} USDT`);
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log('🚀 http://localhost:3000'));
```

--------------------------------

### Create Checkout Session Example

Source: https://ironixpay.com/guide/networks

An example cURL command demonstrating how to create a checkout session, specifying the amount, currency, and network.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a new checkout session for processing payments.

### Method
`POST`

### Endpoint
`/v1/checkout/sessions`

### Request Body
- **amount** (integer) - Required - The amount to be paid in the smallest currency unit (e.g., cents for USD, or the smallest unit for USDT).
- **currency** (string) - Required - The currency of the payment (e.g., "USDT").
- **network** (string) - Required - The blockchain network to use for the payment (e.g., "BSC", "TRON").

### Request Example
```bash
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 10500000, "currency": "USDT", "network": "BSC", ...}'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout session.
- **amount** (integer) - The amount of the session.
- **currency** (string) - The currency of the session.
- **network** (string) - The network used for the session.
- **status** (string) - The current status of the session (e.g., "pending", "paid").

#### Response Example
```json
{
  "id": "sess_12345abcde",
  "amount": 10500000,
  "currency": "USDT",
  "network": "BSC",
  "status": "pending"
}
```
```

--------------------------------

### Install IronixPay SDK (npm/CDN)

Source: https://ironixpay.com/guide/integration

Commands and HTML snippet to install the IronixPay SDK. Use 'npm install @ironix-pay/sdk' for Node.js projects or include the provided script tag for CDN usage.

```bash
npm install @ironix-pay/sdk
```

```html
<script src="https://unpkg.com/@ironix-pay/sdk@0.1.0/dist/ironix-pay.umd.js"></script>
```

--------------------------------

### Create Checkout Session (API)

Source: https://ironixpay.com/guide/quickstart

Initiates a payment session by making a POST request to the IronixPay API. Requires an API key for authentication and specifies payment details like amount, currency, network, and redirect URLs. Returns a session object containing a unique URL for customer redirection.

```bash
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10500000,
    "currency": "USDT",
    "network": "TRON",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'
```

--------------------------------

### Example: Create Checkout Session with Idempotency

Source: https://ironixpay.com/guide/idempotency

This example demonstrates how to create a checkout session using `curl`. The first request includes an `Idempotency-Key`. A subsequent retry with the exact same key and body will return the cached response, preventing a duplicate session.

```bash
# First request — creates the session
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345_v1" \
  -d '{"amount": 10500000, "currency": "USDT", "network": "TRON", "success_url": "https://example.com/success", "cancel_url": "https://example.com/cancel"}'

# Retry with same key — returns the same session (no duplicate created)
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345_v1" \
  -d '{"amount": 10500000, "currency": "USDT", "network": "TRON", "success_url": "https://example.com/success", "cancel_url": "https://example.com/cancel"}'
```

--------------------------------

### Webhook: session.completed

Source: https://ironixpay.com/guide/quickstart

Handles the webhook notification sent by IronixPay when a payment session is completed on-chain. This event allows you to verify payment and fulfill customer orders.

```APIDOC
## Webhook: session.completed

### Description
Handles the webhook notification sent by IronixPay when a payment session is completed on-chain. This event allows you to verify payment and fulfill customer orders.

### Method
POST (typically, to your webhook endpoint)

### Endpoint
Your configured webhook URL

### Parameters
#### Request Body
- **id** (string) - The unique identifier for the webhook event.
- **event_type** (string) - The type of event, which will be "session.completed".
- **created** (integer) - The Unix timestamp when the event was created.
- **data** (object) - Contains details about the completed session:
  - **session_id** (string) - The ID of the completed checkout session.
  - **livemode** (boolean) - Indicates if the session was in live mode.
  - **status** (string) - The final status of the session (e.g., "Paid").
  - **amount_expected** (integer) - The total amount expected for the payment.
  - **amount_received** (integer) - The total amount received for the payment.
  - **currency** (string) - The currency of the transaction.
  - **pay_address** (string) - The payment address used for the transaction.
  - **tx_count** (integer) - The number of transactions associated with this payment.

### Request Example
```json
{
  "id": "evt_abc123...",
  "event_type": "session.completed",
  "created": 1739246160,
  "data": {
    "session_id": "cs_abc123def456",
    "livemode": false,
    "status": "Paid",
    "amount_expected": 10500000,
    "amount_received": 10500000,
    "currency": "USDT",
    "pay_address": "TQFEyGNzHZAJmebJUvsoZvJghHm2yNhXAD",
    "tx_count": 1
  }
}
```

### Response
#### Success Response (200)
Typically, a 200 OK response is expected to acknowledge receipt of the webhook. No specific JSON body is mandated by IronixPay for acknowledgment, but returning an empty object or a simple success message is common.

#### Response Example
```json
{}
```
```

--------------------------------

### POST /v1/checkout/sessions with Idempotency-Key

Source: https://ironixpay.com/guide/idempotency

This example demonstrates how to use the `Idempotency-Key` header with a POST request to create a checkout session. It shows both the initial request and a subsequent retry with the same key, illustrating how idempotency prevents duplicate creations.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a checkout session. By including an `Idempotency-Key` header, you can safely retry this request without creating duplicate sessions.

### Method
POST

### Endpoint
/v1/checkout/sessions

### Parameters
#### Headers
- **Idempotency-Key** (string) - Required - A unique key to ensure the request is processed only once.
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Specifies the request body format, typically `application/json`.

#### Request Body
- **amount** (integer) - Required - The amount for the checkout session.
- **currency** (string) - Required - The currency for the transaction (e.g., "USDT").
- **network** (string) - Required - The blockchain network for the transaction (e.g., "TRON").
- **success_url** (string) - Required - The URL to redirect to upon successful payment.
- **cancel_url** (string) - Required - The URL to redirect to if the payment is canceled.

### Request Example
```bash
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345_v1" \
  -d '{
    "amount": 10500000,
    "currency": "USDT",
    "network": "TRON",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'
```

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier for the created checkout session.
- **status** (string) - The current status of the session.
- **... (other session details)**

#### Response Example
```json
{
  "session_id": "sess_abc123",
  "status": "pending",
  "amount": 10500000,
  "currency": "USDT",
  "network": "TRON",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel"
}
```

#### Error Response (409 Conflict)
- **error_code** (string) - Indicates `idempotency_conflict` if the key is reused with a different body.

### How It Works
- **Same key + same body**: Returns the cached response from the original request.
- **Same key + different body**: Returns `409 Conflict` with error code `idempotency_conflict`.
- **Keys expire after 24 hours**
```

--------------------------------

### Create Checkout Session with BSC Network (Bash)

Source: https://ironixpay.com/guide/networks

Example cURL command to create a checkout session using IronixPay API. It specifies the amount, currency (USDT), and the BSC network. Ensure to replace 'sk_live_...' with your actual live API key.

```bash
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 10500000, "currency": "USDT", "network": "BSC", ...}'
```

--------------------------------

### POST /v1/checkout/sessions

Source: https://ironixpay.com/demo

Creates a checkout session for redirecting customers to IronixPay's hosted checkout page. This is used in Redirect Mode.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a checkout session to initiate a payment process via redirect. This endpoint is part of the Redirect Mode integration.

### Method
POST

### Endpoint
/v1/checkout/sessions

### Parameters
#### Query Parameters
None

#### Request Body
- **amount** (integer) - Required - The amount to be paid in the smallest currency unit (e.g., satoshis for BTC, cents for USD). For USDT, this would be the smallest divisible unit.
- **currency** (string) - Required - The currency code (e.g., 'USDT').
- **network** (string) - Required - The blockchain network to use for the payment (e.g., 'TRON').
- **success_url** (string) - Required - The URL to redirect the customer to upon successful payment.
- **cancel_url** (string) - Required - The URL to redirect the customer to if they cancel the payment.

### Request Example
```json
{
  "amount": 5000000,
  "currency": "USDT",
  "network": "TRON",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout session.
- **url** (string) - The URL to redirect the customer to for completing the payment.

#### Response Example
```json
{
  "id": "cs_test_...".
  "url": "https://checkout.ironixpay.com/pay/cs_test_..."
}
```
```

--------------------------------

### Retrieve Payout Details using cURL

Source: https://ironixpay.com/guide/payouts

This example shows how to fetch the details of a specific payout using its unique ID via the IronixPay API. It utilizes a GET request with the payout ID appended to the endpoint and requires an Authorization header for authentication. This is useful for monitoring the status and details of a past transaction.

```bash
curl https://api.ironixpay.com/v1/payouts/po_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_..."
```

--------------------------------

### IronixPay SDK - Embed Mode

Source: https://ironixpay.com/demo

Integrates the IronixPay payment UI directly into your webpage using the provided SDK. This is used in Embed Mode.

```APIDOC
## IronixPay SDK - Embed Mode

### Description
Use the IronixPay SDK to embed the payment interface directly within your website, providing a seamless user experience. This is part of the Embed Mode integration.

### Method
N/A (Client-side JavaScript SDK)

### Endpoint
N/A (Client-side SDK)

### Parameters
#### Initialization Options
- **environment** (string) - Required - Specifies the environment ('sandbox' or 'production').

#### `createPaymentElement` Options
- **sessionId** (string) - Required - The ID of the checkout session created via the API.
- **theme** (string) - Optional - The visual theme for the payment element ('light' or 'dark'). Defaults to 'light'.
- **locale** (string) - Optional - The language for the payment element (e.g., 'en'). Defaults to 'en'.

### Usage Example
```javascript
import { IronixPay } from '@ironix-pay/sdk'

const ip = new IronixPay({ environment: 'sandbox' })
const el = ip.createPaymentElement({
  sessionId: 'cs_...',
  theme: 'light',
  locale: 'en'
})
el.mount('#checkout') // Mounts the payment element to an HTML element with id 'checkout'

el.on('payment_success', (result) => {
  console.log('Paid!', result.transactionHash)
})
```

### Events
- **payment_success**: Triggered when a payment is successfully completed. The event handler receives a `result` object containing details like `transactionHash`.
```

--------------------------------

### Webhook Signature Verification

Source: https://ironixpay.com/guide/webhooks

This section details the process of verifying webhook signatures using the provided headers and secret. It includes the algorithm, verification steps, and examples in multiple programming languages.

```APIDOC
## Webhook Signature Verification

Every webhook includes two headers:
```
X-Signature: <hex-encoded HMAC-SHA256>
X-Timestamp: <unix-timestamp>
```

### Algorithm 
```
signed_message = "{X-Timestamp}.{request_body_json}"
expected_sig   = HMAC-SHA256(webhook_secret, signed_message)
```

1. Check that `X-Timestamp` is within **5 minutes** of your server time (replay protection)
2. Concatenate `timestamp.body` as the signed message
3. Compute HMAC-SHA256 using your `whsec_...` secret
4. Compare the hex-encoded result against `X-Signature` using a **constant-time** comparison

### Verification Examples 

**Node.js**
```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  // 1. Replay protection: reject timestamps older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old — possible replay attack');
  }

  // 2. Reconstruct the signed message
  const message = `${timestamp}.${payload}`;

  // 3. Compute expected signature
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  // 4. Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const timestamp = req.headers['x-timestamp'];
  const payload = req.body.toString();

  if (!verifyWebhook(payload, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  // Handle event...
  res.status(200).send('OK');
});
```

**Python**
```python
import hmac
import hashlib
import time

def verify_webhook(payload: str, signature: str, timestamp: str, secret: str) -> bool:
    # 1. Replay protection: reject timestamps older than 5 minutes
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        raise ValueError("Timestamp too old — possible replay attack")

    # 2. Reconstruct the signed message
    message = f"{timestamp}.{payload}"

    # 3. Compute expected signature
    expected = hmac.new(
        secret.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    # 4. Constant-time comparison
    return hmac.compare_digest(signature, expected)
```
```

--------------------------------

### Initialize Payment Element (Embed Mode - JavaScript)

Source: https://ironixpay.com/demo

This snippet shows how to initialize and mount the IronixPay payment element for embeddable checkout. It uses the IronixPay SDK and requires a session ID. The element can be mounted to a specified DOM element and listens for payment success events.

```javascript
import { IronixPay } from '@ironix-pay/sdk'

const ip = new IronixPay({ environment: 'sandbox' })
const el = ip.createPaymentElement({
  sessionId: 'cs_...',
  theme: 'light',
  locale: 'en'
})
el.mount('#checkout')
el.on('payment_success', (result) => {
  console.log('Paid!', result.transactionHash)
})
```

--------------------------------

### Create Checkout Session (Redirect Mode - JavaScript)

Source: https://ironixpay.com/demo

This snippet demonstrates how to create a checkout session on the server-side using the IronixPay API. It requires an API key for authorization and specifies payment details like amount, currency, network, and return URLs. The response contains a URL to redirect the customer to.

```javascript
const res = await fetch('https://api.ironixpay.com/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000000,
    currency: 'USDT',
    network: 'TRON',
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel'
  })
})
const session = await res.json()

window.location = session.url
```

--------------------------------

### Environment Variables Configuration (Bash)

Source: https://ironixpay.com/blog/accept-usdt-payments

This Bash snippet shows the format for setting up environment variables required by the IronixPay integration. It includes placeholders for your secret API key and webhook signing secret, which should be stored securely.

```bash
# .env
IRONIXPAY_SECRET_KEY=sk_test_your_key_here
IRONIXPAY_WEBHOOK_SECRET=whsec_your_secret_here
```

--------------------------------

### Redirect Customer to Checkout URL (Server-side)

Source: https://ironixpay.com/guide/quickstart

Redirects the customer to the IronixPay checkout page using the URL obtained from the session creation response. This is typically done in a server-side handler after a successful API request.

```javascript
// Example: redirect in your server-side handler
res.redirect(303, session.url);
```

--------------------------------

### Handle Session Completed Webhook (API)

Source: https://ironixpay.com/guide/quickstart

Processes the 'session.completed' webhook sent by IronixPay when a payment is received on-chain. This event data includes session details and payment status, which should be verified and used to fulfill customer orders.

```json
{
  "id": "evt_abc123...",
  "event_type": "session.completed",
  "created": 1739246160,
  "data": {
    "session_id": "cs_abc123def456",
    "livemode": false,
    "status": "Paid",
    "amount_expected": 10500000,
    "amount_received": 10500000,
    "currency": "USDT",
    "pay_address": "TQFEyGNzHZAJmebJUvsoZvJghHm2yNhXAD",
    "tx_count": 1
  }
}
```

--------------------------------

### Initialize IronixPay SDK

Source: https://ironixpay.com/guide/integration

Instantiate the IronixPay SDK with configuration options. The `environment` option specifies whether to use production or sandbox API endpoints. The `publicKey` is reserved for future use, and `checkoutUrl` allows for custom self-hosted checkout pages.

```javascript
const ironixPay = new IronixPay({
  environment: 'sandbox',
  // publicKey: 'YOUR_PUBLIC_KEY',
  // checkoutUrl: 'https://your-custom-checkout.com'
});
```

--------------------------------

### IronixPay Initialization

Source: https://ironixpay.com/guide/integration

Initialize the IronixPay SDK with your desired options. The environment and public key are crucial for connecting to the correct API.

```APIDOC
## `new IronixPay(options)`

### Description
Initializes the IronixPay SDK. This is the first step to using the library.

### Method
`new`

### Parameters
#### Options
- **environment** (`'production' | 'sandbox'`) - Optional - Specifies the API environment. Defaults to `'production'`.
- **publicKey** (`string`) - Optional - Your public API key. Currently reserved for future use.
- **checkoutUrl** (`string`) - Optional - A custom URL for self-hosted checkout deployments.
```

--------------------------------

### Create Test Checkout Session (Bash)

Source: https://ironixpay.com/guide/testing

Creates a new checkout session in the IronixPay sandbox environment. Requires a test API key and specifies amount, currency, network, and return URLs.

```bash
curl -X POST https://api.ironixpay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "currency": "USDT",
    "network": "TRON",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'
```

--------------------------------

### Expose Local Server for Webhook Testing (Bash)

Source: https://ironixpay.com/guide/testing

Uses ngrok to create a secure tunnel to a local server, allowing external services like IronixPay to send webhooks to your local development environment. Assumes your server is running on port 3000.

```bash
# Using ngrok
ngrok http 3000

# Set your webhook URL to the ngrok URL
# https://abc123.ngrok.io/webhooks/ironixpay
```

--------------------------------

### Create Checkout Session API

Source: https://ironixpay.com/blog/accept-usdt-payments

This endpoint creates a checkout session, which generates a unique payment address and a hosted checkout URL for your customers.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a checkout session to facilitate USDT payments. This endpoint generates a unique payment address and a hosted checkout page URL.

### Method
POST

### Endpoint
`https://sandbox.ironixpay.com/v1/checkout/sessions`

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer YOUR_SECRET_KEY`
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **amount** (integer) - Required - The payment amount in micro-units (e.g., 10000000 for 10.00 USDT).
- **currency** (string) - Required - The currency of the payment, typically 'USDT'.
- **network** (string) - Required - The blockchain network for the payment (e.g., 'TRON', 'BSC', 'ETH').
- **success_url** (string) - Required - The URL to redirect the customer to after a successful payment.
- **cancel_url** (string) - Required - The URL to redirect the customer to if they cancel the payment.
- **client_reference_id** (string) - Optional - Your internal order ID for tracking purposes.

### Request Example
```json
{
  "amount": 10000000,
  "currency": "USDT",
  "network": "TRON",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "client_reference_id": "order_001"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique ID of the checkout session.
- **url** (string) - The URL of the hosted checkout page.

#### Response Example
```json
{
  "id": "cs_abc123...",
  "url": "https://checkout.ironixpay.com/pay/cs_abc123..."
}
```
```

--------------------------------

### How `network` Works

Source: https://ironixpay.com/guide/networks

Explains how the `network` parameter functions when creating a session and how it interacts with the API key to determine mainnet or testnet usage.

```APIDOC
## How `network` Works

The `network` parameter is used when creating a session to specify the desired blockchain. The API automatically selects between mainnet and testnet based on your provided API key:

*   `sk_live_` + `network: "TRON"` → TRON Mainnet
*   `sk_test_` + `network: "TRON"` → TRON Nile (testnet)
*   `sk_live_` + `network: "BSC"` → BSC Mainnet
```

--------------------------------

### Payout Webhook Payload Example

Source: https://ironixpay.com/guide/webhooks

This JSON payload represents a 'payout.completed' event. It contains details about the payout, including status, amounts, currency, network, and transaction hash. This is crucial for merchants to track successful fund disbursements.

```json
{
  "id": "evt_xyz789...",
  "event_type": "payout.completed",
  "created": 1739246200,
  "data": {
    "object": "payout",
    "id": "po_abc123def456",
    "merchant_id": "mer_abc123",
    "livemode": true,
    "status": "Completed",
    "amount": "5000000",
    "fee": "1500000",
    "net_amount": "3500000",
    "currency": "USDT",
    "decimals": 6,
    "network": "TRON",
    "to_address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
    "tx_hash": "7c72c45f...",
    "idempotency_key": "order_123",
    "description": "Vendor payment #1234",
    "metadata": { "internal_ref": "inv-2025-001" },
    "created_at": 1739246100,
    "completed_at": 1739246200
  }
}
```

--------------------------------

### Checkout Session Webhook Payload Example

Source: https://ironixpay.com/guide/webhooks

This JSON payload represents a 'session.completed' event for a checkout session. It includes details about the session, payment status, and transaction information. This is useful for backend systems to track payment confirmations.

```json
{
  "id": "evt_abc123...",
  "event_type": "session.completed",
  "created": 1739246160,
  "data": {
    "object": "checkout_session",
    "id": "cs_abc123def456",
    "merchant_id": "mer_abc123",
    "amount_expected": "10500000",
    "amount_received": "10500000",
    "currency": "USDT",
    "decimals": 6,
    "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "network": "TRON",
    "livemode": false,
    "status": "Paid",
    "pay_address": "TQFEyGNzHZAJmebJUvsoZvJghHm2yNhXAD",
    "client_reference_id": "order_20250227_001",
    "created_at": 1739246100,
    "paid_at": 1739246160,
    "tx_count": 1,
    "transactions": [
      {
        "tx_hash": "7c72c45f...",
        "amount": "10500000",
        "confirmations": 20,
        "from_address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
        "detected_at": 1739246140
      }
    ]
  }
}
```

--------------------------------

### Create Telegram Bot Payment Session (JavaScript)

Source: https://ironixpay.com/blog/accept-usdt-payments

This JavaScript code snippet illustrates how to create an IronixPay checkout session specifically for a Telegram bot. It uses the `fetch` API to make a POST request to the IronixPay API and then constructs an inline keyboard message with a payment URL to send to the user via the bot.

```javascript
bot.onText(//pay/, async (msg) => {
  const res = await fetch(`${API_BASE}/v1/checkout/sessions`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 5000000, // 5 USDT
      currency: 'USDT',
      network: 'TRON',
      success_url: 'https://t.me/your_bot',
      cancel_url: 'https://t.me/your_bot',
    }),
  });
  const session = await res.json();

  bot.sendMessage(msg.chat.id, `💳 Pay 5 USDT to complete your order:`, {
    reply_markup: {
      inline_keyboard: [[{ text: '🔗 Pay Now', url: session.url }]],
    },
  });
});
```

--------------------------------

### Example IronixPay Error JSON Response

Source: https://ironixpay.com/guide/errors

This JSON structure represents a typical error response from the IronixPay API. It includes the error type, a specific error code, a human-readable message, the parameter that caused the error (if applicable), and a URL to relevant documentation.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Amount must be at least 1 USDT (1000000 microunits)",
    "param": "amount",
    "doc_url": "https://ironixpay.com/guide/errors#parameter_invalid"
  }
}
```

--------------------------------

### Security Best Practices

Source: https://ironixpay.com/guide/authentication

Follow these security best practices to protect your IronixPay API keys and ensure the security of your account.

```APIDOC
## Security Best Practices

### Description
Adhering to these security guidelines is crucial for safeguarding your IronixPay API keys and maintaining the integrity of your account and transactions.

### Best Practices

1.  **Keep keys secret**: Store your API keys securely in environment variables. Avoid committing them directly into your version control system.
2.  **Use test keys for development**: Always use `sk_test_` keys for development and testing purposes. Only use `sk_live_` keys in your production environment.
3.  **Rotate regularly**: Periodically rotate your API keys. It is especially important to rotate them immediately if you suspect any compromise.
4.  **Restrict access**: Limit the number of team members who have access to view and manage API keys within your IronixPay account.
```

--------------------------------

### Verify IronixPay Webhook Signature - PHP (Laravel)

Source: https://ironixpay.com/guide/webhooks

Verifies the signature of an incoming IronixPay webhook request using PHP and Laravel. It includes replay protection by checking the timestamp and uses hash_hmac for signature calculation. The example shows how to integrate this into a Laravel route.

```php
<?php

function verifyWebhook(string $payload, string $signature, string $timestamp, string $secret): bool
{
    // 1. Replay protection: reject timestamps older than 5 minutes
    if (abs(time() - intval($timestamp)) > 300) {
        throw new Exception('Timestamp too old — possible replay attack');
    }

    // 2. Reconstruct the signed message
    $message = $timestamp . '.' . $payload;

    // 3. Compute expected signature
    $expected = hash_hmac('sha256', $message, $secret);

    // 4. Constant-time comparison
    return hash_equals($expected, $signature);
}

// Laravel example
Route::post('/webhook', function (Request $request) {
    $payload   = $request->getContent();
    $signature = $request->header('X-Signature', '');
    $timestamp = $request->header('X-Timestamp', '');

    if (!verifyWebhook($payload, $signature, $timestamp, config('services.ironixpay.webhook_secret'))) {
        abort(401, 'Invalid signature');
    }

    $event = json_decode($payload, true);
    // Handle event...
    return response('OK', 200);
});

```

--------------------------------

### Create Payout using cURL

Source: https://ironixpay.com/guide/payouts

This snippet demonstrates how to initiate a USDT payout using the IronixPay API with a cURL command. It includes necessary headers like Authorization and Idempotency-Key, and a JSON payload specifying amount, currency, network, destination address, and an optional description. Ensure the 'Idempotency-Key' header is unique for each request to prevent duplicates.

```bash
curl -X POST https://api.ironixpay.com/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout_order_123" \
  -d '{
    "amount": "10000000",
    "currency": "USDT",
    "network": "TRON",
    "to_address": "TJn9bXhJMVn1Do3PfFHg5J3YNYN9hPQBqA",
    "description": "Affiliate commission for January"
  }'
```

--------------------------------

### Create Checkout Session API

Source: https://ironixpay.com/blog/accept-usdt-payments

This API endpoint allows you to create a new checkout session for processing payments. It can be used in web applications or Telegram bots.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a new checkout session for a payment. This endpoint returns a URL that the customer can use to complete the payment.

### Method
POST

### Endpoint
`/v1/checkout/sessions`

### Parameters
#### Request Body
- **amount** (integer) - Required - The amount to charge in the smallest currency unit (e.g., for USDT, 1,000,000 represents 1 USDT).
- **currency** (string) - Required - The currency of the payment (e.g., 'USDT').
- **network** (string) - Required - The blockchain network for the transaction (e.g., 'TRON').
- **success_url** (string) - Required - The URL to redirect the user to after a successful payment.
- **cancel_url** (string) - Required - The URL to redirect the user to if they cancel the payment.
- **client_reference_id** (string) - Optional - A unique identifier for the order or transaction on your platform.

### Request Example
```json
{
  "amount": 10000000,
  "currency": "USDT",
  "network": "TRON",
  "success_url": "http://localhost:3000/public/success.html",
  "cancel_url": "http://localhost:3000/public/cancel.html",
  "client_reference_id": "order_12345"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout session.
- **url** (string) - The URL for the customer to complete the payment.

#### Response Example
```json
{
  "id": "cs_test_abcdef12345",
  "url": "https://sandbox.ironixpay.com/pay/cs_test_abcdef12345"
}
```
```

--------------------------------

### Create Checkout Session with IronixPay (Node.js)

Source: https://ironixpay.com/blog/accept-usdt-payments

Backend code to create a checkout session with IronixPay. It sends a POST request to the IronixPay API with payment details and returns the session ID and checkout URL. Requires Node.js and the IronixPay secret key.

```javascript
// server.js
const express = require('express');
const app = express();
app.use(express.json());

const IRONIXPAY_SECRET = process.env.IRONIXPAY_SECRET_KEY; // sk_test_...

app.post('/create-checkout', async (req, res) => {
  const response = await fetch(
    'https://sandbox.ironixpay.com/v1/checkout/sessions',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${IRONIXPAY_SECRET}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount: 10000000, // 10.00 USDT (micro-units: 1 USDT = 1,000,000)
        currency: 'USDT',
        network: 'TRON',
        success_url: 'https://yoursite.com/success',
        cancel_url: 'https://yoursite.com/cancel',
        client_reference_id: req.body.orderId, // your internal order ID
      }),
    }
  );

  const session = await response.json();
  res.json({ id: session.id, url: session.url });
});

app.listen(3000, () => console.log('Server running on :3000'));
```

--------------------------------

### Retrieve Checkout Session using cURL

Source: https://ironixpay.com/guide/checkout

This snippet shows how to retrieve the current state of an existing checkout session using a cURL command. It sends a GET request to the /v1/checkout/sessions/:id endpoint, where :id is the unique identifier of the checkout session.

```bash
curl https://api.ironixpay.com/v1/checkout/sessions/cs_abc123 \
  -H "Authorization: Bearer sk_test_..."
```

--------------------------------

### Payment Exception Webhook Event Example

Source: https://ironixpay.com/guide/exceptions

This JSON object represents a webhook event triggered by IronixPay when a payment exception occurs. It includes details such as the event type, exception ID, type, amount, currency, transaction hash, and associated session ID.

```json
{
  "event_type": "payment.exception",
  "data": {
    "id": "exc_abc123...",
    "exception_type": "session_expired",
    "amount": 10500000,
    "currency": "USDT",
    "tx_hash": "abc123...",
    "session_id": "cs_def456..."
  }
}
```

--------------------------------

### Webhook Receiver

Source: https://ironixpay.com/blog/accept-usdt-payments

This endpoint receives and verifies webhook events from IronixPay, such as `session.completed` notifications.

```APIDOC
## POST /webhook

### Description
This endpoint is used to receive and verify webhook events sent by IronixPay. It is crucial for confirming payment status and fulfilling orders.

### Method
POST

### Endpoint
`/webhook`

### Parameters
#### Headers
- **x-signature** (string) - Required - The signature of the webhook payload for verification.
- **x-timestamp** (string) - Required - The timestamp of the webhook event for replay attack prevention.

#### Request Body
- **event_type** (string) - The type of the event (e.g., `session.completed`).
- **data** (object) - Contains details about the event, such as `session_id`, `amount_received`, and `status` for `session.completed` events.

### Request Example
```json
{
  "event_type": "session.completed",
  "data": {
    "session_id": "cs_test_12345",
    "amount_received": 10000000,
    "status": "completed",
    "currency": "USDT",
    "network": "TRON",
    "client_reference_id": "order_abc"
  }
}
```

### Response
#### Success Response (200)
- **OK** - Indicates that the webhook was received and processed successfully.

#### Error Response (401)
- **Invalid signature** - Returned if the `x-signature` header does not match the computed signature.
- **Timestamp expired** - Returned if the `x-timestamp` header is outside the acceptable time window.

### Response Example
```
OK
```
```

--------------------------------

### Managing API Keys

Source: https://ironixpay.com/guide/authentication

API keys can be generated and managed through the IronixPay Merchant Dashboard. Multiple keys can be active per environment, and keys can be rotated without downtime.

```APIDOC
## Managing API Keys

### Description
Generate and manage your API keys directly within your IronixPay Merchant Dashboard. You have the flexibility to maintain multiple active keys for each environment and can seamlessly rotate them by creating a new key before revoking an old one, ensuring uninterrupted service.

### Key Management Features

*   **Multiple Active Keys**: You can have several active keys simultaneously for each environment (production and sandbox).
*   **Key Rotation**: Implement key rotation without causing downtime by generating a new key prior to revoking the existing one.
*   **Security**: Never expose your secret API keys in client-side code.
```