API Reference

1curl -X POST "https://staging-sb-merchant-api.sabpaisa.in/api/v2/payments" \
2  -H "X-Api-Key: your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "merchantId": "AJME84",
6    "merchantTxnId": "TESTING06032610564854",
7    "amount": 50000,
8    "currency": "INR",
9    "customerName": "Bhargav",
10    "customerEmail": "[email protected]",
11    "customerPhone": "9876543210",
12    "returnUrl": "https://yoursite.com/payment/return",
13    "checksum": "your_generated_checksum_here",
14    "timestamp": 1707123456
15  }'

1curl -X POST "https://staging-sb-merchant-api.sabpaisa.in/api/v2/payments" \
2  -H "X-Api-Key: your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "merchantId": "AJME84",
6    "merchantTxnId": "TESTING06032610564854",
7    "amount": 172000,
8    "currency": "INR",
9    "customerName": "Bhargav",
10    "customerEmail": "[email protected]",
11    "customerPhone": "9876543210",
12    "returnUrl": "https://yoursite.com/payment/return",
13    "description": "Order #12345 - 2x Blue T-Shirt",
14    "checksum": "your_generated_checksum_here",
15    "timestamp": 1707123456,
16    "metadata": { "orderId": "ORD-12345", "source": "mobile_app" },
17    "billingAddress": {
18      "name": "Bhargav",
19      "line1": "123 MG Road",
20      "city": "Bengaluru",
21      "state": "KA",
22      "postalCode": "560001",
23      "country": "IN"
24    },
25    "lineItems": [{
26      "name": "Blue T-Shirt",
27      "sku": "TSH-BLU-L",
28      "quantity": 2,
29      "unitPrice": 75000,
30      "taxPercent": 18.0
31    }],
32    "orderSummary": {
33      "subtotal": 150000,
34      "shippingAmount": 5000,
35      "discountAmount": 10000,
36      "taxAmount": 27000,
37      "totalAmount": 172000
38    }
39  }'

1{
2  "success": true,
3  "paymentId": "sppay_f2c2f710ecd34427a710",
4  "checkoutUrl": "https://staging-sb-checkout.sabpaisa.in/checkout/sppay_f2c2f710ecd34427a710",
5  "status": "PENDING",
6  "amount": 50000,
7  "currency": "INR",
8  "merchantTxnId": "TESTING06032610564854",
9  "expiresAt": "2026-02-13T12:30:00",
10  "clientSecret": "sppay_f2c2f710ecd34427a710_secret_08bf1afa68fb...",
11  "message": "Payment created successfully. Redirect customer to checkoutUrl.",
12  "traceId": "abc123def456"
13}

1{checkoutUrl}?clientSecret={clientSecret}

1app.post('/pay', async (req, res) => {
2  const response = await createPaymentSession(req.body);
3  const redirectUrl = `${response.checkoutUrl}?clientSecret=${response.clientSecret}`;
4  res.redirect(redirectUrl);
5});

1@PostMapping("/pay")
2public ResponseEntity<Void> pay(@RequestBody OrderRequest order) {
3    CreatePaymentResponse response = createPaymentSession(order);
4    String redirectUrl = response.getCheckoutUrl() + "?clientSecret=" + response.getClientSecret();
5    return ResponseEntity.status(HttpStatus.FOUND)
6            .header("Location", redirectUrl)
7            .build();
8}

1@app.route('/pay', methods=['POST'])
2def pay():
3    response = create_payment_session(request.json)
4    redirect_url = f"{response['checkoutUrl']}?clientSecret={response['clientSecret']}"
5    return redirect(redirect_url)

1$response = createPaymentSession($orderData);
2$redirectUrl = $response['checkoutUrl'] . '?clientSecret=' . $response['clientSecret'];
3header("Location: " . $redirectUrl);
4exit;

1// After receiving response from your backend
2const redirectUrl = `${response.checkoutUrl}?clientSecret=${response.clientSecret}`;
3window.location.href = redirectUrl;

1https://yoursite.com/payment/return?transaction_id=SP_3129835&merchant_txn_id=ORDER001&status=SUCCESS&amount=1000.00&paid_amount=1000.00&payment_mode=UPI&timestamp=1739540000000&signature=a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

1Step 1: Sort parameters alphabetically by key:
2  amount          = 1000.00
3  merchant_txn_id = ORDER001
4  paid_amount     = 1000.00
5  payment_mode    = UPI
6  status          = SUCCESS
7  timestamp       = 1739540000000
8  transaction_id  = SP_3129835
9
10Step 2: Join as key=value with pipe separator:
11  amount=1000.00|merchant_txn_id=ORDER001|paid_amount=1000.00|payment_mode=UPI|status=SUCCESS|timestamp=1739540000000|transaction_id=SP_3129835
12
13Step 3: HMAC-SHA256 with your secret key:
14  HMAC-SHA256(dataString, secretKey) → 64-char lowercase hex

1const crypto = require('crypto');
2
3app.get('/payment/return', (req, res) => {
4  const { signature, ...params } = req.query;
5
6  // Step 1: Sort keys alphabetically and build data string
7  const dataString = Object.keys(params)
8    .sort()
9    .map(key => `${key}=${params[key]}`)
10    .join('|');
11
12  // Step 2: Compute HMAC-SHA256
13  const expectedSignature = crypto
14    .createHmac('sha256', process.env.SECRET_KEY)
15    .update(dataString)
16    .digest('hex');
17
18  // Step 3: Compare signatures
19  if (expectedSignature !== signature) {
20    return res.status(400).send('Invalid signature — possible tampering');
21  }
22
23  // Signature valid — now check status
24  if (params.status === 'SUCCESS') {
25    // IMPORTANT: Also verify via Transaction Enquiry API or Webhooks
26    res.send('Payment successful!');
27  } else {
28    res.send(`Payment ${params.status.toLowerCase()}`);
29  }
30});

1@GetMapping("/payment/return")
2public ResponseEntity<String> handleReturn(@RequestParam Map<String, String> params) {
3    String receivedSignature = params.remove("signature");
4
5    // Sort keys and build data string
6    String dataString = params.entrySet().stream()
7        .sorted(Map.Entry.comparingByKey())
8        .map(e -> e.getKey() + "=" + e.getValue())
9        .collect(Collectors.joining("|"));
10
11    // Compute HMAC-SHA256
12    Mac mac = Mac.getInstance("HmacSHA256");
13    mac.init(new SecretKeySpec(secretKey.getBytes(UTF_8), "HmacSHA256"));
14    byte[] hash = mac.doFinal(dataString.getBytes(UTF_8));
15    StringBuilder hex = new StringBuilder();
16    for (byte b : hash) hex.append(String.format("%02x", b));
17    String expectedSignature = hex.toString();
18
19    if (!expectedSignature.equals(receivedSignature)) {
20        return ResponseEntity.badRequest().body("Invalid signature");
21    }
22
23    // Signature valid — verify status via API and show result
24    return ResponseEntity.ok("Payment " + params.get("status"));
25}

1import hmac, hashlib
2
3@app.route('/payment/return')
4def payment_return():
5    params = dict(request.args)
6    received_signature = params.pop('signature', '')
7
8    # Sort keys and build data string
9    data_string = '|'.join(
10        f'{k}={params[k]}' for k in sorted(params.keys())
11    )
12
13    # Compute HMAC-SHA256
14    expected_signature = hmac.new(
15        SECRET_KEY.encode(), data_string.encode(), hashlib.sha256
16    ).hexdigest()
17
18    if expected_signature != received_signature:
19        return 'Invalid signature', 400
20
21    # Signature valid — verify status via API and show result
22    return f"Payment {params['status'].lower()}"

1<?php
2$params = $_GET;
3$receivedSignature = $params['signature'];
4unset($params['signature']);
5
6// Sort keys alphabetically
7ksort($params);
8
9// Build data string
10$dataString = implode('|', array_map(
11    fn($k, $v) => "$k=$v",
12    array_keys($params), array_values($params)
13));
14
15// Compute HMAC-SHA256
16$expectedSignature = hash_hmac('sha256', $dataString, $secretKey);
17
18if ($expectedSignature !== $receivedSignature) {
19    http_response_code(400);
20    die('Invalid signature');
21}
22
23// Signature valid — verify status via API and show result
24echo "Payment " . strtolower($params['status']);

1message  = merchantId|merchantTxnId|amount|currency|timestamp
2checksum = HMAC-SHA256(secretKey, message) → lowercase hex (64 characters)
3
4Example:
5message  = "AJME84|TESTING06032610564854|100|INR|1772774819"
6checksum = HMAC-SHA256("your_secret_key", message) → "e3b0c44298fc1c149afbf4c8..."

1const crypto = require('crypto');
2
3function generateChecksum(secretKey, merchantId, merchantTxnId, amount, currency, timestamp) {
4  const message = `${merchantId}|${merchantTxnId}|${amount}|${currency}|${timestamp}`;
5  return crypto.createHmac('sha256', secretKey).update(message).digest('hex');
6}
7
8// Usage
9const timestamp = Math.floor(Date.now() / 1000);
10const checksum = generateChecksum(
11  'your_secret_key', 'AJME84', 'TESTING06032610564854', 100, 'INR', timestamp
12);

1import javax.crypto.Mac;
2import javax.crypto.spec.SecretKeySpec;
3import java.nio.charset.StandardCharsets;
4
5public String generateChecksum(String secretKey, String merchantId, String merchantTxnId,
6                                long amount, String currency, long timestamp) {
7    String message = merchantId + "|" + merchantTxnId + "|" + amount + "|" + currency + "|" + timestamp;
8    Mac mac = Mac.getInstance("HmacSHA256");
9    mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
10    byte[] hash = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
11    StringBuilder hex = new StringBuilder();
12    for (byte b : hash) hex.append(String.format("%02x", b));
13    return hex.toString();
14}

1import hmac, hashlib, time
2
3def generate_checksum(secret_key, merchant_id, merchant_txn_id, amount, currency, timestamp):
4    message = f"{merchant_id}|{merchant_txn_id}|{amount}|{currency}|{timestamp}"
5    return hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()
6
7# Usage
8timestamp = int(time.time())
9checksum = generate_checksum(
10    'your_secret_key', 'AJME84', 'TESTING06032610564854', 100, 'INR', timestamp
11)

1function generateChecksum($secretKey, $merchantId, $merchantTxnId, $amount, $currency, $timestamp) {
2    $message = "{$merchantId}|{$merchantTxnId}|{$amount}|{$currency}|{$timestamp}";
3    return hash_hmac('sha256', $message, $secretKey);
4}
5
6// Usage
7$timestamp = time();
8$checksum = generateChecksum(
9    'your_secret_key', 'AJME84', 'TESTING06032610564854', 100, 'INR', $timestamp
10);

1using System.Security.Cryptography;
2using System.Text;
3
4public string GenerateChecksum(string secretKey, string merchantId, string merchantTxnId,
5                                long amount, string currency, long timestamp) {
6    string message = $"{merchantId}|{merchantTxnId}|{amount}|{currency}|{timestamp}";
7    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
8    byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
9    return BitConverter.ToString(hash).Replace("-", "").ToLower();
10}

1{
2  "success": false,
3  "error": {
4    "code": "INVALID_SIGNATURE",
5    "message": "Checksum verification failed"
6  },
7  "traceId": "abc123def456"
8}

1{
2  "event": "payment.success",
3  "txn_id": "TXN202602150001",
4  "merchant_txn_id": "ORDER-12345",
5  "status": "SUCCESS",
6  "request_amount": 1500.00,
7  "paid_amount": 1500.00,
8  "currency": "INR",
9  "payment_mode": "UPI",
10  "bank_txn_id": "BANK123456789",
11  "bank_rrn": "432109876543",
12  "completed_at": "2026-02-15T10:30:00Z",
13  "timestamp": "2026-02-15T10:30:01.234Z",
14  "idempotency_key": "TXN202602150001_SUCCESS"
15}