SZ Secure Payment Gateway - Official API Documentation

1️⃣ Introduction

SZ Secure is a unified, white-label payment gateway designed for merchants who need a simple, reliable, and scalable payment integration solution.

All gateway routing, load balancing, and failover mechanisms are handled internally by our infrastructure. Merchants never interact with or see any third-party payment providers directly.

Key Features:
• Automatic gateway routing and failover
• White-label solution (your brand only)
• Support for UPI, Cards, Wallets, and more
• Real-time payment notifications
• Comprehensive webhook system

2️⃣ API Credentials

You will receive the following credentials from your SZ Secure dashboard after account activation:

Credentials

API_KEY     : Your unique merchant API key
API_SECRET  : Your secret key for signing requests

Security Notice:
Never expose your API_SECRET in client-side code or public repositories. Store it securely in environment variables or server configuration.

3️⃣ Create Payment API

Endpoint

HTTP

POST https://szsecure.pro/api/payment_create.php

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	✅ Yes	Your merchant API key
`merchant_order_id`	string	✅ Yes	Unique order ID (must be unique per transaction)
`amount`	string	✅ Yes	Payment amount in INR (must be string, not number)
`notify_url`	string	✅ Yes	Callback URL for payment notifications
`sign`	string	✅ Yes	Request signature (MD5 hash)

Important: The amount parameter MUST be sent as a string, not as a numeric value. Example: "100" not 100

4️⃣ Signature Generation

All API requests must be signed using MD5 hash. The signature ensures request integrity and authenticates your API calls.

Signature Algorithm

PHP

<?php

// Step 1: Build parameters array
$params = [
  'api_key'           => 'YOUR_API_KEY',
  'merchant_order_id' => 'ORDER_12345',
  'amount'            => "100",  // MUST be string
  'notify_url'        => 'https://yourdomain.com/callback'
];

// Step 2: Sort parameters alphabetically
ksort($params);

// Step 3: Build signing string
$raw = '';
foreach ($params as $k => $v) {
  $raw .= $k . '=' . $v . '&';
}
$raw .= 'key=' . API_SECRET;

// Step 4: Generate MD5 signature
$sign = md5($raw);

// Step 5: Add signature to request
$params['sign'] = $sign;

?>

Signing Rules

Sort alphabetically: Parameters must be sorted by key name (ascending)
String format: Amount must always be sent as a string
Exact match: The notify_url must match exactly in signature and callback
Lowercase hash: Use lowercase MD5 hash (not uppercase)

Example Signing String

api_key=7ea136602ca20ba029ae532044362a4d&amount=100&merchant_order_id=TEST_001¬ify_url=https://example.com/callback&key=20fb775c8ecd1a18399107bdbd96fb84

5️⃣ API Success Response

On successful payment creation, you will receive the following JSON response:

JSON

{
  "status": 1,
  "order_sn": "ORD6969ee8f33173",
  "pay_url": "https://payment.gateway.com/pay?token=abc123",
  "gateway": "szsecure"
}

Response Fields

Field	Type	Description
`status`	integer	1 = Success, 0 = Failure
`order_sn`	string	Gateway's internal order ID
`pay_url`	string	Payment page URL (redirect user here)
`gateway`	string	Gateway identifier

Handling the Response

PHP

<?php

$response = json_decode($apiResponse, true);

if ($response['status'] === 1 && !empty($response['pay_url'])) {
    // Redirect user to payment page
    header('Location: ' . $response['pay_url']);
    exit;
} else {
    // Handle error
    $error = $response['message'] ?? 'Unknown error';
    echo "Payment creation failed: " . $error;
}

?>

6️⃣ Payment Callback (Webhook)

Once a payment is completed, SZ Secure will send a server-to-server POST request to your notify_url with payment details.

Callback Payload

JSON

{
  "order_sn": "ORD6969ee8f33173",
  "merchant_order_id": "UPI202601160753516945",
  "amount": 200,
  "status": "SUCCESS",
  "gateway": "szsecure",
  "gateway_order_id": "ORD6969ee8f33173",
  "time": 1768550081,
  "sign": "90027733869FE750CB06A3CB8A0E4435"
}

Callback Signature Verification

PHP

<?php

// Read callback data
$rawInput = file_get_contents('php://input');
$data = json_decode($rawInput, true);

// Verify signature
$expectedSign = strtoupper(md5(
    $data['order_sn'] .
    $data['amount'] .
    $data['status'] .
    API_SECRET
));

if ($expectedSign !== strtoupper($data['sign'])) {
    http_response_code(403);
    exit('INVALID SIGN');
}

// Signature verified - process payment
if ($data['status'] === 'SUCCESS') {
    // Update order status in database
    // Credit user wallet
    // Send confirmation email
}

// Always return OK to acknowledge receipt
exit('OK');

?>

Important: Always verify the signature before processing the callback. Return "OK" to acknowledge receipt, otherwise the gateway will retry sending the callback.

Callback Status Values

SUCCESS - Payment completed successfully
FAILED - Payment failed
CANCELLED - Payment cancelled by user

🧪 7️⃣ Live API Tester

Test the SZ Secure API with your credentials in real-time:

8️⃣ Support & Resources

Need Help?

If you encounter any issues during integration:

Check the signature generation carefully
Verify all parameters are sent as strings
Ensure your callback URL is publicly accessible
Test with the API tester above

Contact Support:
For technical support or questions about your integration, please contact your account manager or open a support ticket in the SZ Secure dashboard.

🔐 SZ Secure Payment Gateway