Developer documentation

Add ITFair Pay to your website or store

Create a hosted payment, redirect your customer, then confirm the final status using a signed webhook or the status endpoint.

Open API settings WooCommerce

Quick start

Copy your private API key from the merchant panel.

Create a payment from your server and send the customer to checkout_url.

Only fulfil an order after a signed webhook or a paid status response.

Authentication

Send your API key as a Bearer token. Keep it on your server only—never place it in browser JavaScript, a mobile app bundle, a public repository or screenshots. Regenerating the key immediately invalidates the old one.

HTTP header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

POST /api/public/v1/payments

Required: amount (positive number) and order_id (1–80 characters). Optional: title, description and an HTTPS redirect_url.

cURL

curl -X POST https://YOUR-ITFAIR-PAY-DOMAIN/api/public/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "order_id": "ORDER-1001",
    "title": "Order #1001",
    "description": "Online store order",
    "redirect_url": "https://your-store.com/payment-complete"
  }'

Node.js

const response = await fetch(
  "https://YOUR-ITFAIR-PAY-DOMAIN/api/public/v1/payments",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 500,
      order_id: "ORDER-1001",
      redirect_url: "https://your-store.com/payment-complete",
    }),
  },
);

const payment = await response.json();
window.location.href = payment.checkout_url;

PHP

<?php
$ch = curl_init("https://YOUR-ITFAIR-PAY-DOMAIN/api/public/v1/payments");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 500,
    "order_id" => "ORDER-1001",
    "redirect_url" => "https://your-store.com/payment-complete"
  ])
]);
$payment = json_decode(curl_exec($ch), true);
header("Location: " . $payment["checkout_url"]);

201 response

{
  "payment_id": "5f3c0000-0000-4000-8000-000000000000",
  "order_id": "ORDER-1001",
  "amount": 500,
  "checkout_url": "https://YOUR-ITFAIR-PAY-DOMAIN/pay/api-abc123",
  "status": "unpaid",
  "transaction": null,
  "created_at": "2026-09-29T08:00:00Z"
}

GET /api/public/v1/payments/{payment_id}

Possible status values are unpaid, pending, paid and failed. Always use the payment_id returned by the create request, and verify order_id and amount before updating your order.

cURL

curl "https://YOUR-ITFAIR-PAY-DOMAIN/api/public/v1/payments/{payment_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Signed webhooks

Save your HTTPS webhook URL in the merchant panel. After verification, ITFair Pay sends a POST request. The X-ITFairPay-Signature header is the hexadecimal HMAC-SHA256 of the raw request body using your API key. Compare signatures in constant time, reject mismatches, and make order updates idempotent.

payment.verified

{
  "event": "payment.verified",
  "payment_id": "5f3c…",
  "transaction_id": "6a4d…",
  "order_id": "ORDER-1001",
  "amount": 500,
  "method": "bKash",
  "trxid": "BK12AB34CD",
  "sender": "01XXXXXXXXX",
  "status": "paid",
  "verified_at": "2026-09-29T08:05:00Z"
}

The customer redirect is not proof of payment. Trust only a valid signed webhook or an authenticated paid status response.

Errors and production safety

400: Malformed JSON.
401: Missing or invalid API key.
403: Merchant account is not active.
404: Payment not found for this merchant.
422: One or more input fields are invalid.
500: Temporary server error; retry safely with your order ID.

Use HTTPS and keep keys in server-side secrets.
Use a unique order_id and prevent duplicate fulfilment.
Log payment_id and order_id, but never log the API key.

WooCommerce

Install the plugin ZIP, activate ITFair Pay under WooCommerce payments, then add your API key and this site's base URL. Copy the plugin webhook URL into your merchant API settings. Test a small order before accepting live orders.

Download plugin