Documentation - Insoftx Pay

🚀 Getting Started

📋 Prerequisites: Basic knowledge of PHP and web development concepts.

Quick Start Guide

1

Create Account

Sign up as a merchant and get your API keys

2

Configure Methods

Set up your payment methods and account details

3

Integrate API

Use our API to accept payments in your application

👨‍💼 Merchant Account Setup

1. Registration Process

To start using Insoftx Pay, you need to create a merchant account:

Visit the Merchant Portal
Click on "Register" tab
Fill in your company details
Verify your email address
Log in to your dashboard

2. API Keys Generation

After registration, you'll receive your API keys automatically:

// Your API Keys will look like this:

API Key: ipk_7d9f8g3h2i1j5k6l7m8n9o0p1q2r3s4t

Secret Key: ips_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p

⚠️ Important: Keep your Secret Key confidential and never expose it in client-side code.

3. Profile Configuration

Configure your merchant profile:

Company Information: Update your business name, logo, and contact details
Website URL: Set your website for payment page branding
Communication Settings: Configure email preferences

💳 Payment Methods Configuration

Insoftx Pay supports all major Bangladeshi payment methods:

Available Payment Methods

bKash - Mobile Financial Service
Nagad - Digital Payment Platform
Rocket - DBBL Mobile Banking
Upay - United Commercial Bank
Bank Transfer - Direct bank transfers

Configuration Steps

Go to Payment Methods in your merchant dashboard
Enable the payment methods you want to accept
For each method, provide:
- Account number
- Account holder name
- Bank details (for bank transfer)
- Payment instructions for customers
Save your settings

💡 Tip: Provide clear payment instructions to help customers complete transactions successfully.

🔌 API Integration Guide

Official Support Status: Insoftx Pay currently supports two official checkout integrations: Redirect Checkout and Embedded Checkout (Popup/Iframe).

Official Integration Modes

Mode	How It Works	When to Use
`redirect` (default)	Customer is redirected to Insoftx Pay hosted checkout page, then returned to merchant callback URL.	Fastest integration and best for classic server-rendered checkout flows.
`embedded`	Merchant opens Insoftx hosted checkout in popup/iframe and receives result via `postMessage`.	Best when customer should stay on merchant site during payment.

Important Architecture Note

Embedded mode is not a direct card/mobile payment form API inside your DOM. Payment is still completed on Insoftx hosted checkout, displayed inside popup/iframe. This is intentional for security and verification consistency.

API Base URL

Base URL: https://pay.insoftx.com//api/

Authentication

All API requests must include your API key in the header:

// Required Header

API-Key: your_api_key_here

Content-Type: application/json

Request Format

All API requests should be in JSON format:

{
  "amount": 100.50,
  "order_id": "ORDER_12345",
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "customer_phone": "01712345678",
  "callback_url": "https://merchant-site.com/payment/callback",
  "checkout_mode": "redirect"
}

checkout_mode supports redirect (default) and embedded.

Redirect Checkout Flow (Official)

Call /api/init-payment.php from your backend with checkout_mode omitted or set to redirect.
Use returned payment_url to redirect the customer.
After payment attempt, customer returns to your callback_url with result parameters.
Verify status from your backend using /api/transaction-status.php before fulfilling the order.

Embedded Checkout Flow (Official)

Call /api/init-payment.php from your backend with checkout_mode: "embedded".
Open returned payment_url in popup or iframe.
Listen for postMessage event with source: "insoftx-pay" and type: "payment_result".
After receiving message, verify final transaction status from your backend via /api/transaction-status.php.

// Frontend listener for Embedded Checkout result

window.addEventListener('message', function (event) {

  const data = event.data || {};

  if (data.source !== 'insoftx-pay' || data.type !== 'payment_result') return;

  // data.status: success | failed

  // data.transaction_id, data.order_id, data.amount, data.trx_id

  // Call your backend to verify via /api/transaction-status.php before fulfillment

});

Response Format

API responses vary by endpoint. Most endpoints return status and message fields, and many include a data object.

{

  "status": "success",

  "message": "Operation completed successfully",

  "data": {

    "example": "payload"

  }

}

🌐 API Endpoints

1. Initialize Payment

POST https://pay.insoftx.com//api/init-payment.php

Parameter	Type	Required	Description
amount	decimal	Yes	Payment amount (min: ৳10, max: ৳50,000)
order_id	string	Yes	Your internal order ID
customer_name	string	Yes	Customer's full name
customer_email	string	Yes	Customer's email address
customer_phone	string	Yes	Customer's phone number
callback_url	string	No	Merchant return URL for redirect flow
checkout_mode	string	No	`redirect` (default) or `embedded`

Response

{

  "status": "success",

  "transaction_id": "TXN202312011230451234",

  "payment_url": "https://pay.insoftx.com//payment/?store_id=1&amount=100.50&order_id=ORDER123",

  "checkout_mode": "redirect",

  "embedded_checkout_url": null,

  "message": "Payment initiated successfully"

}

2. SMS Capture & Auto Verification (Merchant Server Endpoint)

POST https://pay.insoftx.com//api/verify-payment.php

Parameter	Type	Required	Description
merchant_id	string	Yes	Merchant ID
api_key	string	Yes	Merchant API key
secret_key	string	Yes	Merchant secret key
amount	decimal	Yes	Detected payment amount
phone	string	Yes	Detected sender phone
trx_id	string	Yes	Detected transaction reference

Response

{

  "success": true,

  "message": "Payment verified successfully!",

  "transaction_id": "TXN202312011230451234",

  "action": "instant_verification"

}

3. Check Transaction Status

POST/GET https://pay.insoftx.com//api/transaction-status.php

Parameter	Type	Required	Description
transaction_id	string	No*	Transaction ID (either this or order_id required)
order_id	string	No*	Your order ID exact match (either this or transaction_id required)

🐘 PHP Integration Examples

1. Complete Payment Integration

<?php
// Configuration
$api_url = '<?php echo APP_URL; ?>/api/init-payment.php';
$api_key = 'your_actual_api_key_here'; // Get from merchant dashboard

// Payment data
$payment_data = [
  'amount' => 150.75,
  'order_id' => 'ORDER_' . time(),
  'customer_name' => 'John Doe',
  'customer_email' => '[email protected]',
  'customer_phone' => '01712345678'
];

// Initialize cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payment_data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'API-Key: ' . $api_key
]);

// Execute request
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Process response
if ($http_code === 200) {
  $result = json_decode($response, true);
  if ($result['status'] === 'success') {
    // Redirect to payment page
    header('Location: ' . $result['payment_url']);
    exit;
  } else {
    echo "Error: " . $result['message'];
  }
} else {
  echo "HTTP Error: " . $http_code;
}
?>

2. Embedded Checkout (Popup) Example

// 1) Create payment session from your backend with checkout_mode=embedded
$payment_data = [
  'amount' => 150.75,
  'order_id' => 'ORDER_' . time(),
  'customer_name' => 'John Doe',
  'customer_email' => '[email protected]',
  'customer_phone' => '01712345678',
  'callback_url' => 'https://merchant-site.com/payment/callback',
  'checkout_mode' => 'embedded'
];

// 2) On your frontend, open the returned payment_url in a popup
const popup = window.open(result.payment_url, 'insoftxPay', 'width=520,height=760');

// 3) Listen for completion message from Insoftx Pay window
window.addEventListener('message', async function (event) {
  if (!event.data || event.data.source !== 'insoftx-pay' || event.data.type !== 'payment_result') return;
  // event.data.status => success / failed
  // IMPORTANT: verify from backend using transaction-status API before confirming order
  console.log(event.data);
});

3. Payment Verification Script

<?php

function verifyPayment($transaction_id) {

  $api_url = '<?php echo APP_URL; ?>/api/verify-payment.php';

  $api_key = 'your_actual_api_key_here';

  $data = ['transaction_id' => $transaction_id];

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $api_url);

  curl_setopt($ch, CURLOPT_POST, true);

  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  curl_setopt($ch, CURLOPT_HTTPHEADER, [

    'Content-Type: application/json',

    'API-Key: ' . $api_key

  ]);

  $response = curl_exec($ch);

  curl_close($ch);

  return json_decode($response, true);

}

// Usage example

$verification = verifyPayment('TXN202312011230451234');

if ($verification['status'] === 'success') {

  $transaction = $verification['data'];

  if ($transaction['status'] === 'success') {

    // Payment successful - update your database

    echo "Payment completed successfully!";

  } else {

    // Payment pending or failed

    echo "Payment status: " . $transaction['status'];

  }

}

?>

4. Integration Modes Summary

Redirect mode: Merchant redirects customer to payment_url. Insoftx Pay redirects back after result.
Embedded mode: Merchant opens payment_url in popup/iframe and receives postMessage result.
Recommended: Always verify final status from your backend using transaction-status API before delivering products/services.

5. Simple Payment Form

<!DOCTYPE html>
<html>
<head>
  <title>Payment Checkout</title>
  <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
  <div class="container mt-5">
    <div class="row justify-content-center">
      <div class="col-md-6">
        <div class="card">
          <div class="card-header">
            <h4>Complete Your Payment</h4>
          </div>
          <div class="card-body">
            <form action="process_payment.php" method="POST">
              <div class="mb-3">
                <label>Amount (BDT)</label>
                <input type="number" name="amount" class="form-control" value="100" step="0.01" required>
              </div>
              <div class="mb-3">
                <label>Full Name</label>
                <input type="text" name="customer_name" class="form-control" required>
              </div>
              <div class="mb-3">
                <label>Email</label>
                <input type="email" name="customer_email" class="form-control" required>
              </div>
              <div class="mb-3">
                <label>Phone Number</label>
                <input type="text" name="customer_phone" class="form-control" required>
              </div>
              <button type="submit" class="btn btn-primary w-100">Proceed to Payment</button>
            </form>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Webhooks

Current Status: Webhook events listed below are planned reference events. If your account is not provisioned for webhooks yet, use callback_url and /api/transaction-status.php for production verification.

Planned Webhook Events

payment.completed - When a payment is successfully verified
payment.failed - When a payment fails
payment.pending - When a payment is submitted but pending verification
payment.cancelled - When a payment is cancelled

Webhook Payload Example

{
  "event": "payment.completed",
  "data": {
    "transaction_id": "TXN202312011230451234",
    "amount": 100.50,
    "status": "success",
    "payment_method": "bkash",
    "customer_email": "[email protected]",
    "timestamp": "2023-12-01T12:30:45Z"
  }
}

🔒 Security Best Practices

API Key Security

Never commit API keys to version control
Store keys in environment variables or secure configuration files
Use different keys for development and production
Regenerate keys immediately if compromised

Data Validation

Always validate amount on your server before initiating payment
Sanitize all user inputs
Verify payment status on your server before fulfilling orders
Implement rate limiting to prevent abuse

SSL/TLS Requirements

Always use HTTPS in production to ensure secure data transmission.

Fraud Prevention

Monitor transactions for suspicious patterns
Implement IP whitelisting if needed
Set reasonable transaction limits
Keep your integration updated

🔧 Troubleshooting

Common Issues

Issue: API returns "Invalid API Key"

Solution:

Verify your API key in the merchant dashboard
Ensure the API key is correctly included in the header
Check for extra spaces or characters in the key

Issue: Payment page not loading

Solution:

Verify the store_id parameter is correct
Check if the merchant account is active
Ensure at least one payment method is enabled

Issue: Transaction status stuck at "pending"

Solution:

Check if the customer completed the payment process
Verify the transaction reference number
Contact the merchant to manually verify the payment

Error Codes Reference

Error Code	Description	Solution
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key and authentication
403	Forbidden	Check account status and permissions
404	Not Found	Verify endpoint URL and resource existence
500	Internal Server Error	Contact support if issue persists

Need Help? Contact our support team at [email protected] or visit the Merchant Dashboard for live chat support.

Insoftx Pay Docs

Insoftx Pay Documentation

🚀 Getting Started

Quick Start Guide

Create Account

Configure Methods

Integrate API

👨‍💼 Merchant Account Setup

1. Registration Process

2. API Keys Generation

3. Profile Configuration

💳 Payment Methods Configuration

Available Payment Methods

Configuration Steps

🔌 API Integration Guide

Official Integration Modes

Important Architecture Note

API Base URL

Authentication

Request Format

Redirect Checkout Flow (Official)

Embedded Checkout Flow (Official)

Response Format

🌐 API Endpoints

1. Initialize Payment

Response

2. SMS Capture & Auto Verification (Merchant Server Endpoint)

Response

3. Check Transaction Status

🐘 PHP Integration Examples

1. Complete Payment Integration

2. Embedded Checkout (Popup) Example

3. Payment Verification Script

4. Integration Modes Summary

5. Simple Payment Form

Webhooks

Planned Webhook Events

Webhook Payload Example

🔒 Security Best Practices

API Key Security

Data Validation

SSL/TLS Requirements

Fraud Prevention

🔧 Troubleshooting

Common Issues

Error Codes Reference