WowPay API Documentation

Powerful payment processing API for seamless transactions

Get Started API Reference
API Endpoints
Quick Links
SDK Downloads API Postman Collection Support

Getting Started

Welcome to the WowPay API documentation. This API allows you to integrate payment processing capabilities into your application.

Authentication

All API requests require authentication using your API keys. Include these in every request:

  • appid: Your application ID
  • app_secret: Your secret API key
  • sign: MD5 signature of appid and app_secret
Keep your app_secret confidential and never expose it in client-side code.

Base URL

https://wowpay.cfd/api

Rate Limits

API requests are limited to 60 requests per minute. Exceeding this limit will result in a 429 status code.

API Versions

Version Status Description Base URL
v1 Active Original API version /api/
v2 Latest Enhanced with customer details /api/v2/

POST /api/balance

Check user's wallet balance

Endpoint URL
https://wowpay.cfd/api/balance
Request Headers
Header Value Required
Content-Type application/x-www-form-urlencoded; charset=UTF-8 Yes
Server True Yes
Request Parameters
Parameter Type Required Description
appid string Yes Your API authentication key (API 令牌)
app_secret string Yes API密钥 to check balance for
sign string Yes MD5 signature of appid and app_secret
Response Example
{
    "status": "success",
    "balance": 1000.50,
    "currency": "USD"
}

POST /api/payment v1

Initiating Collection Request

This endpoint allows you to initiate a payment collection from your customers.
Endpoint URL
https://wowpay.cfd/api/payment
Signature Calculation

The signature for v1 API is calculated as:

sign = md5(strtolower(appid . app_secret));
Request Parameters
Parameter Type Required Description
appid string Yes Application ID
app_secret string Yes Application secret key
orderid string Yes Unique order ID
amount decimal Yes Amount to collect
time string Optional Timestamp of the request
sign string Yes MD5 signature of appid and app_secret
Response Example
{
    "status": "success",
    "message": "success",
    "app_id": "wow10000",
    "amount": "100",
    "orderid": "8021455822",
    "payment_id": "WOW20250323193504",
    "url": "https://wowpay.cfd/payment/WOW20250323193504"
}
Tips
  • Always verify the payment status using webhooks or by checking with our API
  • The orderid must be unique for each transaction
  • Amount should be in the smallest currency unit (e.g., cents for USD)

POST /api/v2/payment v2.0 NEW

Enhanced payment collection with customer details

This is the upgraded version 2.0 of our payment API with additional customer information fields.
Endpoint URL
https://wowpay.cfd/api/v2/payment
Signature Calculation

The signature for v2 API is calculated as:

sign = md5(appid + app_secret + orderid + amount + name + mobile)
PHP Signature Example
// Generate v2 signature
$appid = "YOUR_APP_ID";
$app_secret = "YOUR_APP_SECRET";
$orderid = "UNIQUE_ORDER_123";
$amount = "100.00";
$name = "John Doe";
$mobile = "9876543210";

$sign = md5($appid . $app_secret . $orderid . $amount . $name . $mobile);
Request Parameters
Parameter Type Required Description
appid string Yes Application ID
app_secret string Yes Application secret key
orderid string Yes Unique order ID
amount decimal Yes Amount to collect
name string Yes Customer name
mobile string Yes Customer mobile number
redirect_url string Optional After Payment Done Page will be Redirect
sign string Yes MD5 signature (see calculation above)
Response Example
{
    "status": "success",
    "message": "Payment initiated",
    "app_id": "WOW10000",
    "amount": "100.00",
    "orderid": "ORDER_123456",
    "customer": {
        "name": "John Doe",
        "mobile": "9876543210"
    },
    "payment_id": "WOW20250323193504",
    "url": "https://wowpay.cfd/payment/WOW20250323193504",
    "version": "2.0"
}
Migration from v1 to v2
  • New required fields: name and mobile
  • Updated signature calculation including new fields
  • Enhanced response with customer details
  • Backward compatible with v1 parameters

POST /api/payout NEW

Initiating Payout Request

Use this endpoint to send money to your customers' bank accounts.
Endpoint URL
https://wowpay.cfd/api/payout
Request Headers
Header Value Required
Content-Type application/x-www-form-urlencoded; charset=UTF-8 Yes
Server True Yes
Request Parameters
Parameter Type Required Description
appid string Yes Application ID
app_secret string Yes Application secret key
orderid string Yes Unique order ID
amount decimal Yes Amount to payout
beneficiary_name string Yes Account Holder Name
bank_name string Yes Bank Name
account_no string Yes Bank Account Number
ifsc string Yes IFSC Code
sign string Yes MD5 signature of appid and app_secret
Response Example
{
    "status": "success",
    "message": "payout initiate",
    "app_id": "wow10000",
    "amount": "10000",
    "orderid": "t104"
}
Processing Times

Payouts typically process within 1-3 business days, depending on the bank.

Important Notes
  • Verify all bank details before initiating payout
  • Payouts are irreversible once processed
  • Maintain sufficient balance in your account for payouts

Webhook Notifications

Real-time payment status updates

WowPay will send HTTP POST requests to your configured endpoint when payment status changes occur.
Our Server IP
Webhook Integration

Bind our server IP to your webhook page to accept notifications

Webhook URL

Configure this in your WowPay Merchant Dashboard under Settings → Webhooks

Authentication

All webhook requests are signed with HMAC-SHA256 for verification:

X-WowPay-Signature: HMAC-SHA256(timestamp + body, YOUR_APP_SECRET)
X-WowPay-Timestamp: UNIX_TIMESTAMP
Webhook Payload
Field Type Description
orderid string Your original order ID
status string Payment status (success, failed, pending)
type string Transaction Type (payin , payout)
app_id string Your WowPay application ID
amount decimal Payment amount
payment_id string WowPay transaction reference
utr string Bank transaction number
currency string 3-letter currency code (e.g. USD)
timestamp integer Unix timestamp of the event
Verification Example (PHP)
function verifyWebhook() {
    $headers = getallheaders();
    $signature = $headers['X-WowPay-Signature'] ?? '';
    $timestamp = $headers['X-WowPay-Timestamp'] ?? '';
    $payload = file_get_contents('php://input');
    
    // Verify timestamp (5-minute window)
    if (abs(time() - $timestamp) > 300) {
        throw new Exception('Expired request');
    }
    
    // Verify signature
    $expected = hash_hmac('sha256', $timestamp.$payload, APP_SECRET);
    if (!hash_equals($expected, $signature)) {
        throw new Exception('Invalid signature');
    }
    
    return json_decode($payload, true);
}
Response Handling

Your endpoint should return HTTP 200 within 5 seconds with:

{
    "status": "success",
    "message": "Webhook processed"
}
Important: If you don't respond with HTTP 200, WowPay will retry the webhook up to 5 times over 24 hours.
Event Types
Event Description Retry Policy
payment.success Payment completed successfully 3 retries
payment.failed Payment failed or was declined No retries
payment.refunded Payment was refunded 5 retries

Error Codes & Troubleshooting

Reference for all API error responses

All error responses follow the same JSON structure with HTTP status codes
Error Response Format
{
    "status": "error",
    "code": "ERR_4001",
    "message": "Invalid API credentials",
    "documentation_url": "https://docs.wowpay.example/errors/ERR_4001"
}
HTTP Status Codes
Code Status Description
200 OK Request succeeded
400 Bad Request Invalid request parameters
401 Unauthorized Authentication failed
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error
API Error Codes
Error Code HTTP Status Description Solution
ERR_4001 400 Missing required parameter Check all required fields are included
ERR_4002 400 Invalid parameter value Verify parameter formats and types
ERR_4003 400 Duplicate order ID Generate a unique order ID
ERR_4011 401 Invalid API credentials Verify your appid and app_secret
ERR_4012 401 Signature verification failed Recalculate the MD5 signature
ERR_4031 403 IP not whitelisted Add your IP to merchant dashboard
ERR_4041 404 Transaction not found Verify the payment_id
ERR_4291 429 API rate limit exceeded Wait 1 minute before retrying
ERR_5001 500 Internal server error Retry after 5 minutes
ERR_5002 500 Payment gateway timeout Check transaction status later
Troubleshooting Tips

  • Verify your appid and app_secret match your merchant dashboard
  • Ensure your signature is calculated as md5(appid + app_secret)
  • Check your server time is synchronized (NTP)

  • For duplicate order IDs, implement a unique ID generator
  • If amount is invalid, check minimum/maximum limits
  • For expired transactions, create a new payment request

  • Retry after 5 minutes for 500 errors
  • Check status.wowpay.example for outages
  • Implement exponential backoff for retries
For complete error handling guidance, see our API Best Practices documentation.