API Reference

Events — USDT

• payment.success — a payin order was matched and credited
• payment.expired — a payin order's 1-hour window closed unpaid
• payout.success — an admin-approved payout was signed and broadcast
• payout.rejected — an admin rejected a payout (already refunded to your ledger)

Events — INR / BDT / PKR channels

No expired equivalent — channel orders carry no Quropay-side expiry. Channel payouts settle synchronously with the provider rather than via manual admin approval, so success/failed covers the full outcome for each.

• channel_payment.success — a channel payin was confirmed paid and credited

  { "channel": "INR", "provider": "galepay", "out_trade_no": "chn_2b054aa2c12eb5c881bd955",
    "order_ref": "MERCHANT-ORDER-124", "amount": 1500, "pay_amount": 1500, "status": "completed" }

• channel_payment.failed — the provider reported the payin failed

  { "channel": "INR", "provider": "galepay", "out_trade_no": "chn_2b054aa2c12eb5c881bd955",
    "order_ref": "MERCHANT-ORDER-124", "amount": 1500, "status": "failed" }

• channel_payout.success — the provider confirmed the payout completed (amount is what the beneficiary received, total_debit is what left your channel balance)

  { "channel": "INR", "provider": "galepay", "out_trade_no": "chn_9f1c2a0e7b3d4568112a",
    "amount": 1000, "net_amount": 1000, "total_debit": 1050, "status": "completed" }

• channel_payout.failed — the provider reported the payout failed (the locked amount was already refunded to your channel ledger by the time this arrives)

  { "channel": "INR", "provider": "galepay", "out_trade_no": "chn_9f1c2a0e7b3d4568112a",
    "amount": 1000, "status": "failed" }

• channel_payout.reversed — rare: the provider had already told us this payout completed, then later reversed/clawed it back (the beneficiary evidently never actually received the funds). total_debit has been refunded to your channel balance by the time this arrives, same as channel_payout.failed

  { "channel": "INR", "provider": "galepay", "out_trade_no": "chn_9f1c2a0e7b3d4568112a",
    "amount": 1000, "total_debit": 1050, "status": "reversed" }

Verifying the signature

Every delivery includes:

X-Webhook-Event: payment.success
X-Webhook-Signature: sha256=<hex-encoded HMAC-SHA256 of the raw request body>

Compute the HMAC using your api_secret as the key, over the raw request body bytes — not a re-serialized/re-indented version of the JSON, which won't match.

<?php
$body = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $yourApiSecret);

if (!hash_equals($expected, $signatureHeader)) {
    http_response_code(401);
    exit('bad signature');
}

$payload = json_decode($body, true);
// $payload['event'], $payload['data'] ...
http_response_code(200); // anything else triggers a retry

Create a payin order (fetch)

Node 18+ has fetch built in — an axios.post(...) call with the same headers/body works identically if that's what your project already uses.

async function createPayin(amount, orderRef) {
  const res = await fetch('https://quropays.com/api/v1/payin/create.php', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer key_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount, order_ref: orderRef }),
  });
  if (!res.ok) throw new Error((await res.json()).error.message);
  return res.json(); // { payment_page_url, gateway_order_id, expected_amount, ... }
}

Create an INR payin (fetch)

Same endpoint, a channel field — see Multi-Channel Payments for the other channels and their required fields. The response shape differs from USDT's: redirect to checkout_url (the provider's own hosted page), and there's no status-polling endpoint for channel orders — listen for the channel_payment.success/channel_payment.failed webhook instead.

async function createInrPayin(amount, orderRef, phone, email) {
  const res = await fetch('https://quropays.com/api/v1/payin/create.php', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer key_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      channel: 'INR',
      amount,
      order_ref: orderRef,
      phone,  // optional — a placeholder is generated if omitted
      email,  // optional — a placeholder is generated if omitted
    }),
  });
  if (!res.ok) throw new Error((await res.json()).error.message);
  return res.json(); // { channel, out_trade_no, order_ref, amount, status, checkout_url, created_at }
}

Express webhook receiver + HMAC verification

The signature is computed over the raw request body bytes, so this route must read the raw body before any JSON body-parser touches it — express.raw(), scoped to just this route, does that.

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post(
  '/webhooks/quropay',
  express.raw({ type: 'application/json' }), // raw Buffer, not parsed JSON
  (req, res) => {
    const signatureHeader = req.get('X-Webhook-Signature') || '';
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.USDT_GATEWAY_API_SECRET)
      .update(req.body) // raw Buffer — must match byte-for-byte
      .digest('hex');

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

    const payload = JSON.parse(req.body.toString('utf8'));
    // payload.event, payload.data ...
    res.sendStatus(200); // anything else triggers a retry
  }
);

React: poll status & render the QR code

Building your own checkout UI instead of the hosted payment page? Poll payin/check.php — it needs no API key, since order_id itself is the capability (see Poll payin (public) above).

function PaymentStatus({ orderId, qrCodeUrl, expectedAmount }) {
  const [status, setStatus] = React.useState('pending');

  React.useEffect(() => {
    if (status !== 'pending') return;
    const poll = async () => {
      const res = await fetch(
        `https://quropays.com/api/v1/payin/check.php?order_id=${orderId}`
      );
      const data = await res.json();
      setStatus(data.status);
    };
    poll();
    const id = setInterval(poll, 9000);
    return () => clearInterval(id);
  }, [status, orderId]);

  if (status === 'completed') return <p>Payment received!</p>;

  return (
    <div>
      <img src={qrCodeUrl} alt="Payment QR code" />
      <p>Send exactly {expectedAmount} USDT · status: {status}</p>
    </div>
  );
}