SecureNexPay Developer Documentation

Overview

SecureNexPay lets merchants create secure payment links, redirect customers to checkout, receive signed payment webhooks, and mark orders as paid safely.

Quick Start

1. Get Public Key and Secret Key from SecureNexPay Merchant Panel
2. Create payment from your backend/server
3. Generate HMAC signature using Secret Key
4. Redirect customer to checkout_url
5. Receive signed webhook
6. Verify webhook signature
7. Mark order as paid

Base URL

https://merchant.securenexpay.com

Minimum Files Required for Custom PHP Website

Merchant Credentials

Payment Flow

Customer clicks Pay Now
   ↓
Merchant backend creates signed request
   ↓
POST https://merchant.securenexpay.com/api/create-payment.php
   ↓
SecureNexPay validates:
Public Key + Merchant Status + HMAC Signature + Timestamp + Nonce + Allowed Domain
   ↓
Payment Link Created
   ↓
Customer redirects to checkout_url
   ↓
Customer completes payment
   ↓
SecureNexPay sends signed webhook to merchant webhook_url
   ↓
Merchant verifies webhook signature
   ↓
Order marked as paid

Create Payment API

Endpoint

POST https://merchant.securenexpay.com/api/create-payment.php

Required Headers

Request Body

{
  "public_key": "pk_live_xxxxxxxxxxxxxxxxx",
  "order_id": "ORDER1001",
  "amount": "190.00",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "customer_phone": "01700000000",
  "success_url": "https://yourdomain.com/payment-success",
  "cancel_url": "https://yourdomain.com/payment-cancel",
  "webhook_url": "https://yourdomain.com/api/securenexpay-webhook"
}

Signature Formula

signature = HMAC_SHA256(raw_json_body + timestamp + nonce, secret_key)

Required Fields

Custom PHP Integration Example

1. config.php

<?php

define('SNP_PUBLIC_KEY', 'pk_live_xxxxxxxxxxxxxxxxx');
define('SNP_SECRET_KEY', 'sk_live_xxxxxxxxxxxxxxxxx');
define('SNP_CREATE_URL', 'https://merchant.securenexpay.com/api/create-payment.php');

2. create-payment.php

<?php
require_once __DIR__ . '/config.php';

$orderId = 'ORDER1001';
$amount = '190.00';

$payload = [
    'public_key' => SNP_PUBLIC_KEY,
    'order_id' => $orderId,
    'amount' => $amount,
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
    'customer_phone' => '01700000000',
    'success_url' => 'https://yourdomain.com/success.php?order_id=' . urlencode($orderId),
    'cancel_url' => 'https://yourdomain.com/cancel.php?order_id=' . urlencode($orderId),
    'webhook_url' => 'https://yourdomain.com/webhook.php'
];

$rawBody = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$timestamp = time();
$nonce = bin2hex(random_bytes(16));
$signature = hash_hmac('sha256', $rawBody . $timestamp . $nonce, SNP_SECRET_KEY);

$ch = curl_init(SNP_CREATE_URL);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $rawBody,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Accept: application/json',
        'X-SecureNexPay-Timestamp: ' . $timestamp,
        'X-SecureNexPay-Nonce: ' . $nonce,
        'X-SecureNexPay-Signature: ' . $signature
    ],
    CURLOPT_TIMEOUT => 30
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if ($httpCode >= 200 && $httpCode < 300 && !empty($result['checkout_url'])) {
    header('Location: ' . $result['checkout_url']);
    exit;
}

echo 'Payment creation failed.';
echo '<pre>' . htmlspecialchars($response) . '</pre>';

3. webhook.php

<?php
require_once __DIR__ . '/config.php';
header('Content-Type: application/json');

$rawPayload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_SECURENEXPAY_SIGNATURE'] ?? '';
$expectedSignature = hash_hmac('sha256', $rawPayload, SNP_SECRET_KEY);

if (!$receivedSignature || !hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    echo json_encode(['success' => false, 'message' => 'Invalid webhook signature.']);
    exit;
}

$data = json_decode($rawPayload, true);
if (!is_array($data)) {
    http_response_code(400);
    echo json_encode(['success' => false, 'message' => 'Invalid JSON payload.']);
    exit;
}

if (($data['status'] ?? '') === 'COMPLETED') {
    $orderId = $data['order_id'];
    $paymentUid = $data['payment_uid'];
    $transactionId = $data['transaction_id'];
    $amount = $data['amount'];

    // TODO:
    // 1. Find order by $orderId
    // 2. Verify amount matches your order amount
    // 3. Store $paymentUid and $transactionId
    // 4. Mark order as paid/completed
}

http_response_code(200);
echo json_encode(['success' => true, 'message' => 'Webhook processed.']);

4. success.php

<?php
echo 'Payment successful. Your order is being processed.';

5. cancel.php

<?php
echo 'Payment cancelled or failed. Please try again.';

Create Payment Success Response

{
  "success": true,
  "message": "Payment created successfully.",
  "payment_uid": "PAY20260614123456xxxx",
  "provider_payment_uid": null,
  "order_id": "ORDER1001",
  "amount": "190.00",
  "checkout_url": "https://merchant.securenexpay.com/checkout/pay.php?payment_uid=PAY...",
  "provider_checkout_url": "https://secure.securenexpay.com/api/execute/xxxx"
}

Create Payment Error Responses

Missing Signature

{
  "success": false,
  "message": "Missing request signature."
}

Invalid Signature

{
  "success": false,
  "message": "Invalid request signature."
}

Unauthorized Domain

{
  "success": false,
  "message": "Unauthorized domain.",
  "allowed_domain": "shop.example.com",
  "request_domain": "otherdomain.com",
  "field": "webhook_url"
}

Provider Brand/API Key Error

{
  "success": false,
  "message": "Provider payment creation failed.",
  "provider_response": {
    "status": 0,
    "message": "Invalid API Request."
  }
}

Allowed Domain Rule

If a merchant has an allowed domain, then success_url, cancel_url, and webhook_url must use the same domain.

Allowed domain: shop.example.com

Allowed:
https://shop.example.com/payment-success
https://shop.example.com/checkout/cancel
https://shop.example.com/api/webhook

Not allowed:
https://example.com/payment-success
https://sub.shop.example.com/payment-success
https://otherdomain.com/payment-success

Payment Status API

Endpoint

GET https://merchant.securenexpay.com/api/payment-status.php?public_key=pk_live_xxxxx&payment_uid=PAY20260614123456xxxx

Required Query Parameters

Example

https://merchant.securenexpay.com/api/payment-status.php?public_key=pk_live_xxxxx&payment_uid=PAY20260614123456xxxx

Success Response

{
  "success": true,
  "payment_uid": "PAY20260614123456xxxx",
  "order_id": "ORDER1001",
  "amount": "190.00",
  "net_amount": "190.00",
  "payment_method": "bkash",
  "transaction_id": "ABC123456",
  "status": "COMPLETED",
  "created_at": "2026-06-14 12:20:00",
  "paid_at": "2026-06-14 12:30:00"
}

Error Response

{
  "success": false,
  "message": "Public key is required."
}

Webhook

When payment is completed, SecureNexPay sends a POST request to the merchant webhook URL.

Webhook Payload

{
  "payment_uid": "PAY20260614123456xxxx",
  "order_id": "ORDER1001",
  "amount": "190.00",
  "net_amount": "190.00",
  "status": "COMPLETED",
  "payment_method": "bkash",
  "transaction_id": "ABC123456",
  "paid_at": "2026-06-14 12:30:00"
}

Webhook Header

X-SecureNexPay-Signature: generated_hmac_signature

Webhook Signature Formula

webhook_signature = HMAC_SHA256(raw_webhook_body, secret_key)

Webhook Response Requirement

Your webhook endpoint must return HTTP 200-299 after successful processing.

Success Response

{
  "success": true,
  "message": "Webhook processed."
}

Invalid Signature Response

{
  "success": false,
  "message": "Invalid webhook signature."
}

Webhook Retry System

If merchant webhook fails, SecureNexPay retries delivery automatically.

Payment Status Values

WooCommerce Integration

For WooCommerce stores, install the official SecureNexPay WooCommerce Gateway plugin and configure:

Public Key
Secret Key
Create Payment API URL
Payment Status API URL

The plugin automatically generates:

Webhook URL
Return URL
Cancel URL
Request Signature
Timestamp
Nonce

Integration Diagram

Customer
   ↓
Merchant Website
   ↓
create-payment.php
   ↓
SecureNexPay Create Payment API
   ↓
checkout_url
   ↓
Customer Payment Page
   ↓
Payment Completed
   ↓
Signed Webhook
   ↓
Merchant webhook.php
   ↓
Verify Signature + Update Order
   ↓
Order Completed

Security Checklist

• Use HTTPS for all URLs.
• Never expose Secret Key publicly.
• Generate a new nonce for every payment create request.
• Use current Unix timestamp for every request.
• Verify webhook signature before marking order as paid.
• Never trust only customer return page.
• Store payment_uid and transaction_id.
• Verify order amount before completing order.
• Check allowed domain before payment creation.
• Return HTTP 200 only after order is successfully updated.

Testing Guide

Valid Test

Correct Public Key
Correct Secret Signature
Correct Timestamp
Unique Nonce
Correct Allowed Domain
Expected: Payment created successfully

Missing Signature Test

Remove X-SecureNexPay-Signature header
Expected: 401 Missing request signature

Wrong Signature Test

X-SecureNexPay-Signature: wrong123
Expected: 401 Invalid request signature

Wrong Domain Test

Allowed domain: shop.example.com
webhook_url: https://otherdomain.com/webhook
Expected: 403 Unauthorized domain

Replay Attack Test

Send same timestamp + nonce + signature twice
Expected:
First request may pass
Second request should fail

Production Notes

• Create Payment API must be called from merchant backend/server, not directly from frontend JavaScript.
• Webhook is the final authority for completing an order.
• Return URL is only for customer redirect/thank-you page.
• If email sending fails in WooCommerce, configure SMTP.
• Keep WooCommerce plugin and SecureNexPay API version compatible.
• Save payment_uid and transaction_id to prevent duplicate processing.
• For custom integration, always verify amount before marking order as paid.

Support

Email: support@securenexpay.com

Merchant Panel: merchant.securenexpay.com