Merchant API Reference

Version 1 · Base URL: https://payments.alvanlabs.com/api/v1

The Alvan Labs Pay API enables merchants to accept UPI payments with fully automatic reconciliation — no payment gateway required. When a customer initiates a payment, the API assigns a system-determined payment amount using proprietary reconciliation logic, enabling zero-touch matching of incoming credits to orders.

Getting Started

Everything you need to set up before going live

Authentication

How to identify yourself as a merchant

All API requests are authenticated using your Merchant Key — a unique string in the format mch_<24 hex chars>. This key is passed as a request body field or query parameter depending on the endpoint. There are no bearer tokens or API key headers required.

Error Handling

Standard HTTP status codes and error response format

All errors return a JSON body with a detail field describing the issue.

End-to-End Payment Flow

How a payment goes from initiation to verified

Order Statuses

All possible states an order can be in

UPI Deep Link

How to use the upi_link returned by initiate-pay

The upi_link is a standard UPI Intent URL. You can use it in two ways:

// Using qrcode.js
QRCode.toCanvas(canvas, upiLink, { width: 200 })

// Or: qrcode-generator, jsQR, etc.

<a href="{{ upi_link }}" class="pay-btn">
  Pay ₹{{ unique_amount }}
</a>

Polling Strategy

Best practices for polling /check-payment

// JavaScript polling example
async function pollPayment(orderId, merchantId) {
  const maxTime = 60 * 60 * 1000; // 1 hour
  const start = Date.now();
  let interval = 5000; // start at 5s

  while (Date.now() - start < maxTime) {
    const res = await fetch(
      `/api/v1/check-payment/${orderId}?merchant_id=${merchantId}`
    );
    const data = await res.json();

    if (data.status === 'paid') {
      // Payment confirmed!
      handleSuccess(data);
      return;
    }
    if (!data.success) {
      handleError('Order not found');
      return;
    }

    // Back off over time
    if (Date.now() - start > 10 * 60 * 1000) interval = 30000;
    else if (Date.now() - start > 2 * 60 * 1000) interval = 15000;

    await new Promise(r => setTimeout(r, interval));
  }

  handleTimeout(); // 1 hour passed
}

Proprietary Reconciliation

How Alvan Labs Pay matches payments to orders automatically

Alvan Labs Pay uses proprietary reconciliation technology to automatically match incoming UPI payments to the correct order — without any manual intervention. When you initiate a payment, the system assigns a unique_amount for that session. This amount must be paid exactly as specified.

Order Expiry

What happens when an order is not paid within 1 hour

• ✅ Orders expire 1 hour after creation.
• ✅ An automated background job runs every minute to detect expired orders and move them to failed_orders.
• ✅ A timeout email is sent to the customer's email address when an order expires.
• ✅ Expired orders are visible in the merchant dashboard under the "Expired" filter.
• ✅ Merchants can manually verify an expired order from the dashboard if they received payment after expiry.
• ⚠️ After expiry, the payment session is released and new orders can be initiated for the same amount.

WooCommerce Integration

Built-in automatic order status sync

When your merchant account has integration_type = woo configured, the system automatically calls the WooCommerce REST API to update the order to processing when payment is verified. No additional code needed.

Shopify Integration

Native Shopify Checkout Extension with Direct Deep-Linking

Accept zero-fee UPI payments directly in your Shopify Store using our dedicated Shopify App. The integration embeds a native Checkout UI Extension block directly on your store's **Thank You** and **Order Status** pages.

Webhooks Coming Soon

Push notifications when payment is verified

When integration_type = webhook, the system will POST a JSON payload to your configured webhook_url when an order is verified. The webhook payload format will be:

// Planned webhook payload (subject to change)
{
  "event": "payment.verified",
  "order_id": "WC-1042",
  "amount": 500.07,
  "merchant_id": "mch_...",
  "verified_at": "2026-05-14T18:32:11"
}

Contact payments@alvanlabs.com to request early access.

Custom PHP Integration

Full example for non-WooCommerce PHP applications

<?php
// ─── Step 1: Initiate payment ───────────────────────────────
$merchantId = 'mch_4b7d2e9f1a3c058762de4f91';
$orderId    = 'ORDER-' . time();  // your unique order ID

$payload = json_encode([
    'order_id'       => $orderId,
    'customer_email' => 'customer@example.com',
    'customer_phone' => '9876543210',
    'base_amount'    => 500.00,
    'merchant_id'    => $merchantId,
]);

$ch = curl_init('https://payments.alvanlabs.com/api/v1/initiate-pay');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$response || $response['status'] !== 'success') {
    die('Payment initiation failed: ' . ($response['detail'] ?? 'unknown error'));
}

$uniqueAmount = $response['unique_amount'];   // e.g. 500.07
$upiLink      = $response['upi_link'];        // display as QR or button
$expiresAt    = $response['expires_at'];      // show countdown timer

// Store $orderId + $uniqueAmount in your DB for reference

// ─── Step 2: Poll for payment status (server-side or AJAX) ─
function checkPaymentStatus($orderId, $merchantId): string {
    $url = "https://payments.alvanlabs.com/api/v1/check-payment/{$orderId}?merchant_id={$merchantId}";
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5]);
    $data = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $data['status'] ?? 'error';
}

// In your AJAX endpoint:
$status = checkPaymentStatus($_GET['order_id'], $merchantId);
echo json_encode(['status' => $status]);  // "pending" | "paid" | "not_found"
?>

cURL Examples

Quick reference for testing all three endpoints

curl -X POST https://payments.alvanlabs.com/api/v1/initiate-pay \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TEST-001",
    "customer_email": "test@example.com",
    "customer_phone": "9876543210",
    "base_amount": 500.00,
    "merchant_id": "mch_4b7d2e9f1a3c058762de4f91"
  }'

curl "https://payments.alvanlabs.com/api/v1/check-payment/TEST-001?merchant_id=mch_4b7d2e9f1a3c058762de4f91"

curl "https://payments.alvanlabs.com/api/v1/check-status/TEST-001?merchant_id=mch_4b7d2e9f1a3c058762de4f91"

Frequently Asked Questions