# Build. Integrate. Scale.
Developer-first APIs for payments, payouts & banking automation.
Ask a question...
Get started Authenticate Integrate Contribute
{% columns %}
{% column width="50%" %}
### Get Started with KwikPaisa
Launch payments, payouts, and banking APIs in minutes.
Create your account, generate API keys, and make your first live API request using simple integration examples for every major tech stack.
{% hint style="warning" icon="life-ring" %}
**Need some help?**
Troubleshoot common issues or ask for help.
I get a 401 Unauthorized error
This usually happens when the request signature is invalid or required authentication headers are missing.
**Verify the following:**
* `x-client-id` is correct
* `x-signature` is generated properly
* `x-timestamp` is a valid UNIX timestamp
* Your API secret key is correct
* Request body matches the exact payload used during signature generation
KwikPaisa Signature Formula
HMAC\_SHA256(payload + timestamp, secret\_key)
**Important Rules**
* Payload keys must be recursively sorted
* JSON must use unescaped slashes
* Signature must be generated using the exact request payload
I get a 400 Bad Request error
This means one or more required request fields are missing or invalid.
**Common Reasons**
* Invalid amount format
* Missing `order_id`
* Invalid UPI ID or bank details
* Empty request body
* Invalid JSON structure
**Example**
For Create Order API:
* `amount`
* `customer_mobile`
* `order_id`
must be passed correctly.
Also ensure:
* `Content-Type: application/json`
* Valid request payload format
My payment or payout stays in processing
Transactions may remain in processing state while awaiting confirmation from banking or UPI networks.
**Recommended Action**
* Use Order Status API for payments
* Use Payout Status API for payouts
* Avoid creating duplicate requests for the same transaction
**Payment APIs**
* Create Order
* Order Status
* Order Cancel
**Payout APIs**
* Balance Inquiry
* Transaction Initiation
* Payout Status
The request succeeds, but the response is not what I expect
This usually happens due to:
* Incorrect environment usage
* Wrong webhook handling
* Duplicate order IDs
* Invalid payout mode
* Incorrect callback parsing
**Verify:**
* You are using the correct API endpoint
* Request payload matches API documentation
* Webhook responses are being parsed correctly
* Transaction status is checked using status APIs
**Recommended**
Always rely on:
* Order Status API
* Payout Status API
instead of frontend callback responses.
My webhook is not working
**Verify the following:**
* Webhook URL is publicly accessible
* Your server returns HTTP `200 OK`
* SSL certificate is valid
* Firewall is not blocking requests
**Important**
KwikPaisa automatically retries failed webhook deliveries.
Ensure your webhook:
* accepts POST requests
* processes JSON payloads
* responds quickly
My signature works locally but fails on server
This is usually caused by payload formatting differences.
**Ensure:**
* Payload sorting is identical
* JSON encoding is consistent
* Timestamp is generated in seconds
* No extra spaces or formatting changes exist
**Correct Signature Logic**
```
signature = HMAC_SHA256(payload + timestamp, secret_key)
```
{% file src="/files/7wLcq9lqStH1NzPaiXUM" %}
I get insufficient balance errors during payouts
Your payout wallet balance may be low.
**Before initiating payouts:**
* Check available balance using Balance Inquiry API
* Ensure sufficient wallet balance exists
* Verify payout limits configured for your account
Duplicate transaction detected
KwikPaisa blocks duplicate transaction attempts for security and reconciliation purposes.
**Best Practices**
* Always use unique `order_id`
* Avoid retrying instantly
* Use status APIs before retrying failed transactions
Which APIs should I use for transaction verification?
For reliable transaction verification:
**Payments**
Use:
* Order Status API
**Payouts**
Use:
* Payout Status API
Avoid relying only on:
* frontend redirects
* user-side success screens
* temporary processing responses
{% endhint %}
With your first integration complete, explore our API guides and references to build payments, payouts, and banking workflows with KwikPaisa.
Get started API reference
{% endcolumn %}
{% column width="50%" %}
{% stepper %}
{% step %}
**Create Your Merchant Account**
Sign up and generate your API credentials to start integrating KwikPaisa APIs.
Sign up Log in
{% endstep %}
{% step %}
**Make Your First API Request**
Connect with KwikPaisa APIs using secure authentication and signature-based requests.
```
Endpoint:
POST {baseUrl}/api/v3/pg/order/create
```
{% tabs %}
{% tab title="JavaScript" %}
{% code overflow="wrap" %}
```javascript
const crypto = require('crypto');
const payload = {
amount: "100.00",
order_id: "ORD123456"
};
const timestamp = Math.floor(Date.now() / 1000);
const signature = crypto
.createHmac('sha256', 'YOUR_SECRET_KEY')
.update(JSON.stringify(payload) + timestamp)
.digest('hex');
console.log(signature);
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
import json
import hmac
import hashlib
import time
payload = {
"amount": "100.00",
"order_id": "ORD123456"
}
# Sort payload keys
sorted_payload = dict(sorted(payload.items()))
# Convert to JSON
payload_json = json.dumps(
sorted_payload,
separators=(',', ':')
)
# Generate timestamp
timestamp = str(int(time.time()))
# Generate signature
signature = hmac.new(
b'YOUR_SECRET_KEY',
(payload_json + timestamp).encode(),
hashlib.sha256
).hexdigest()
print(signature)
```
{% endcode %}
{% endtab %}
{% tab title="cURL" %}
{% code overflow="wrap" %}
```bash
curl --request POST \
--url {baseUrl}/api/v3/pg/order/create \
--header "Content-Type: application/json" \
--header "x-client-id: YOUR_CLIENT_ID" \
--header "x-timestamp: 1716206400" \
--header "x-signature: GENERATED_SIGNATURE" \
--data '{
"amount": "100.00",
"order_id": "ORD123456",
"customer_mobile": "9999999999"
}'
```
{% endcode %}
{% endtab %}
{% tab title="Go" %}
{% code overflow="wrap" expandable="true" %}
```go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"time"
)
func main() {
payload := map[string]string{
"amount": "100.00",
"order_id": "ORD123456",
}
payloadJSON, _ := json.Marshal(payload)
timestamp := fmt.Sprintf("%d", time.Now().Unix())
message := string(payloadJSON) + timestamp
secretKey := "YOUR_SECRET_KEY"
h := hmac.New(sha256.New, []byte(secretKey))
h.Write([]byte(message))
signature := hex.EncodeToString(h.Sum(nil))
fmt.Println(signature)
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Parse the Response**
If the request is successful, KwikPaisa APIs return a response like this:
{% code title="response.json" overflow="wrap" %}
```json
{
"code": "200",
"status": "success",
"message": "API authentication successful!",
"return_data": {
"kwikX_order_id": "kp_40dec464-7155-43a3-855d-c95c5ab1be71",
"created_at": "13-05-2026 08:34 AM",
"order_id": 3501946751751,
"order_status": "UN_PAID",
"payment_link": "http://orchestration.localhost/payment/sandbox/pay_TSN7ASUDmzcZNyH8qLeG8PrR4CWB9pwFQOuDPYia0fd5k2fMzN"
}
}
```
{% endcode %}
{% endstep %}
{% endstepper %}
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column width="50%" %}
API Guides API Reference
{% endcolumn %}
{% endcolumns %}
Need Integration Support?
Get help with API integration, webhooks, payouts, and onboarding from the KwikPaisa technical team.
Contact Support API Status
# Welcome
Build secure, scalable, and production-ready payment infrastructure with KwikPaisa APIs.
The KwikPaisa Guides are designed to help developers integrate:
* Payment Gateway APIs
* Banking & Payout APIs
* Hosted Checkout
* Webhooks
* Signature Verification
* Settlement Workflows
* Production Security Controls
Whether you are building:
* Fintech platforms
* Neo-banking systems
* Marketplace payouts
* Vendor settlements
* SaaS billing systems
* Wallet infrastructure
KwikPaisa provides modern APIs and banking orchestration tools to help you move money securely and reliably.
***
## What You’ll Learn
These guides walk you through:
* API authentication
* Request signing
* Payment order creation
* Hosted checkout integration
* Payout automation
* Webhook handling
* Retry logic
* Security best practices
* Production deployment
Every guide is written for real-world production use cases with examples, workflows, and operational recommendations.
***
## Available Guides
### Quick Start
Get started with:
* Account setup
* API credentials
* First API request
* Sandbox testing
***
### Authentication
Learn how to securely authenticate API requests using:
* API Keys
* HMAC SHA256 signatures
* Timestamps
* Secure headers
***
### Payment Gateway Integration
Integrate hosted checkout flows:
* Create Order API
* Redirect customers
* Verify payment status
* Cancel payment orders
***
### Payout Integration
Build automated banking workflows:
* Balance inquiry
* Payout initiation
* Payout status verification
* Settlement tracking
***
### Webhooks
Receive real-time transaction updates:
* Payment notifications
* Payout notifications
* Signature verification
* Retry handling
***
### Testing & Sandbox
Safely test integrations using:
* Sandbox credentials
* Mock responses
* UAT testing
* Failure scenarios
***
### Error Handling
Learn production-grade handling for:
* API failures
* Retry logic
* Processing transactions
* Reconciliation workflows
***
### Going Live
Prepare for production deployment with:
* Security checks
* IP whitelisting
* Production readiness
* Compliance recommendations
***
## Production-Ready by Design
KwikPaisa APIs are built with:
* Enterprise-grade security
* Banking-grade reliability
* Real-time transaction processing
* Scalable payout infrastructure
* Advanced reconciliation workflows
Security features include:
* HMAC SHA256 signatures
* HTTPS-only communication
* Webhook verification
* Replay attack protection
* IP whitelisting support
***
## Recommended Integration Flow
1. Generate API credentials
2. Configure authentication
3. Test APIs in Sandbox
4. Integrate webhooks
5. Validate transaction flows
6. Complete UAT testing
7. Move to production safely
***
## Need Help?
For:
* Production onboarding
* Payout enablement
* Security reviews
* High-risk merchant setup
* Settlement configuration
contact the KwikPaisa integration and onboarding team.
# Create account
Before integrating KwikPaisa APIs, you must create and configure your merchant account, complete business verification, and activate the required banking services.
This guide walks you through the complete onboarding process for:
* Payment Gateway activation
* Payout activation
* Sandbox API access
* Developer Console setup
***
## Step 1 — Create Your Account
Visit the KwikPaisa Dashboard and create your merchant account using your email address.
### Registration Flow
1. Enter your email address
data,
String secretKey,
long timestamp
) throws Exception {
TreeMap sortedData = new TreeMap<>(data);
ObjectMapper mapper = new ObjectMapper();
String payload = mapper.writeValueAsString(sortedData);
String signString = payload + timestamp;
Mac sha256Hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(
secretKey.getBytes(),
"HmacSHA256"
);
sha256Hmac.init(secretKeySpec);
byte[] hash = sha256Hmac.doFinal(
signString.getBytes()
);
StringBuilder hexString = new StringBuilder();
for (byte b : hash) {
hexString.append(String.format("%02x", b));
}
return hexString.toString();
}
}
```
{% endtab %}
{% tab title=".NET (C#)" %}
```c
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json;
class Program
{
static void Main()
{
var data = new SortedDictionary
{
{ "order_id", "123456" },
{ "amount", "100" }
};
string payload = JsonConvert.SerializeObject(data);
long timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
string signString = payload + timestamp;
string secretKey = "YOUR_SECRET_KEY";
using(var hmac = new HMACSHA256(
Encoding.UTF8.GetBytes(secretKey)))
{
byte[] hash = hmac.ComputeHash(
Encoding.UTF8.GetBytes(signString)
);
string signature = BitConverter
.ToString(hash)
.Replace("-", "")
.ToLower();
Console.WriteLine(signature);
}
}
}
```
{% endtab %}
{% tab title="Flutter / Dart" %}
```dart
import 'dart:convert';
import 'package:crypto/crypto.dart';
void main() {
Map data = {
"order_id": "123456",
"amount": "100"
};
final sortedKeys = data.keys.toList()..sort();
final sortedData = {
for (var key in sortedKeys) key: data[key]
};
String payload = jsonEncode(sortedData);
int timestamp = DateTime.now()
.millisecondsSinceEpoch ~/ 1000;
String secretKey = "YOUR_SECRET_KEY";
String signString = payload + timestamp.toString();
var hmacSha256 = Hmac(
sha256,
utf8.encode(secretKey)
);
var digest = hmacSha256.convert(
utf8.encode(signString)
);
String signature = digest.toString();
print(signature);
}
```
{% endtab %}
{% tab title="Go" %}
```go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"time"
)
func main() {
payload := map[string]string{
"order_id": "123456",
"amount": "100",
}
payloadJSON, _ := json.Marshal(payload)
timestamp := fmt.Sprintf("%d", time.Now().Unix())
message := string(payloadJSON) + timestamp
secretKey := "YOUR_SECRET_KEY"
h := hmac.New(sha256.New, []byte(secretKey))
h.Write([]byte(message))
signature := hex.EncodeToString(h.Sum(nil))
fmt.Println(signature)
}
```
{% endtab %}
{% endtabs %}
## Common Authentication Errors
### 401 Unauthorized
Possible reasons:
* Invalid signature
* Wrong secret key
* Expired timestamp
* Incorrect payload format
* Missing headers
### Invalid Signature
This usually happens when:
* Payload is modified after signing
* Keys are not sorted correctly
* JSON formatting differs
* Timestamp mismatch occurs
## Security Best Practices
* Never expose your `secret_key` publicly
* Always generate signatures on the server side
* Use HTTPS for all API requests
* Generate unique timestamps for every request
* Rotate credentials periodically
* Validate webhook signatures before processing callbacks
## Recommended Workflow
1. Generate timestamp
2. Prepare payload
3. Generate signature
4. Attach required headers
5. Send API request
6. Validate API response
# Security
KwikPaisa APIs are designed with enterprise-grade security standards to protect merchant transactions, sensitive customer data, and banking workflows.
All API requests are secured using HMAC SHA256 signature authentication, timestamp validation, encrypted communication, and strict request verification mechanisms.
This guide outlines the recommended security practices for securely integrating with KwikPaisa APIs.
***
## API Authentication Security
Every API request must include:
```http
Content-Type: application/json
Accept: application/json
X-API-KEY: pk_test_xxxxxxxxx
X-TIMESTAMP: GENERATED_TIMESTAMP
X-SIGNATURE: GENERATED_SIGNATURE
```
The X-SIGNATURE header is generated using:
```http
HMAC_SHA256(payload + timestamp, secret_key)
```
This helps prevent:
* Unauthorized requests
* Payload tampering
* Replay attacks
* Request forgery
***
## Protect Your Secret Keys
Your `secret_key` is highly sensitive and should always remain confidential.
### Best Practices
* Never expose secret keys in frontend applications
* Never commit credentials to Git repositories
* Store secrets securely using environment variables
* Rotate credentials periodically
* Restrict internal access to production credentials
***
## Always Use HTTPS
All API requests must be sent over secure HTTPS connections.
HTTPS encryption protects:
* API credentials
* Customer information
* Transaction payloads
* Webhook communications
Non-HTTPS requests may be rejected for security reasons.
***
## Timestamp Validation
KwikPaisa validates request timestamps to prevent replay attacks.
### Recommendations
* Generate a fresh timestamp for every request
* Use UNIX timestamp in seconds format
* Synchronize server time using NTP
* Avoid reusing old request payloads
Expired timestamps may result in:
```
401 Unauthorized
```
***
## Signature Verification
Before processing any request, KwikPaisa validates:
* Payload integrity
* Timestamp validity
* Merchant authentication
* Signature authenticity
Any mismatch between:
* Request payload
* Timestamp
* Secret key
will invalidate the request.
***
## Webhook Security
Webhook notifications should always be verified before processing.
### Recommended Validation Steps
1. Validate webhook signature
2. Verify request timestamp
3. Check transaction status using APIs
4. Respond with HTTP 200 quickly
***
## IP Whitelisting
For enhanced security, production merchants may enable IP whitelisting.
This allows API access only from trusted server IP addresses.
### Benefits
* Prevents unauthorized API access
* Adds an additional security layer
* Restricts access to approved infrastructure
***
## Secure Server-Side Integrations
All:
* Signature generation
* Secret key handling
* Transaction validation
must happen only on secure backend servers.
Never generate signatures from:
* Mobile apps
* Frontend JavaScript
* Public client applications
***
## Replay Attack Protection
KwikPaisa uses timestamp validation and request signing to prevent replay attacks.
Replay attacks occur when attackers reuse old valid API requests to trigger duplicate actions.
To prevent this:
* Generate unique timestamps
* Avoid duplicate order IDs
* Validate transaction status before retries
***
## Production Security Checklist
Before going live:
* Use HTTPS only
* Secure all secret keys
* Validate webhook signatures
* Enable IP whitelisting
* Monitor API activity
* Rotate credentials regularly
* Implement proper server-side validation
***
## Recommended Security Workflow
1. Generate timestamp
2. Prepare request payload
3. Generate HMAC SHA256 signature
4. Send secure HTTPS request
5. Validate API response
6. Verify webhook notifications
***
## Common Security Errors
### 401 Unauthorized
Possible reasons:
* Invalid signature
* Expired timestamp
* Incorrect secret key
* Missing authentication headers
***
### Invalid Signature
Usually caused by:
* Modified payload
* Incorrect JSON formatting
* Unsorted payload keys
* Timestamp mismatch
***
## Need Help?
If you experience authentication or security-related issues, contact the KwikPaisa integration support team for assistance with:
* Signature verification
* Webhook validation
* Production onboarding
* IP whitelisting
* Security configuration
```
```
# Create Order
Use the Create Order API to generate a new payment order and initiate a hosted checkout session for your customer.
Once the order is created successfully, KwikPaisa returns a hosted payment link that can be used to redirect customers and complete the payment securely.
This API supports:
* UPI Payments
* QR Payments
* Net Banking
* Cards
* Wallets
***
## Endpoint
```http
POST /api/v3/pg/order/create
```
***
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
#### This endpoint requires standard KwikPaisa authentication headers.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
***
## Request Parameters
| Parameter | Type | Required | Description |
| ------------------------------ | -------------- | -------- | ---------------------------- |
| `order_id` | Integer/String | Yes | Unique merchant order ID |
| `order_amount` | Decimal | Yes | Transaction amount |
| `order_currency` | String | Yes | Currency code (Example: INR) |
| `order_note` | String | No | Additional order information |
| `service_type` | String | Yes | Transaction service type |
| `customer.name` | String | Yes | Customer full name |
| `customer.email` | String | Yes | Customer email address |
| `customer.phone` | String | Yes | Customer mobile number |
| `customer.address.line1` | String | Yes | Primary address line |
| `customer.address.line2` | String | No | Secondary address line |
| `customer.address.city` | String | Yes | Customer city |
| `customer.address.state` | String | Yes | Customer state |
| `customer.address.country` | String | Yes | Customer country |
| `customer.address.postal_code` | String | Yes | Customer postal/ZIP code |
| `return_url` | String | Yes | Merchant return/callback URL |
***
## Example Request Body
```json
{
"order_id": 6116229263036,
"order_amount": 105,
"order_currency": "INR",
"order_note": "Additional order info",
"service_type": "DIGITAL",
"customer": {
"name": "Ajay",
"email": "developer@jangras.co",
"phone": "9816512345",
"address": {
"line1": "Capital Office, Kemp House",
"line2": "152 - 160 City Road",
"city": "London",
"state": "London",
"country": "UK",
"postal_code": "EC1V 2NX"
}
},
"return_url": "https://merchant.in/process_return.php?order_id=order_1626945143520"
}
```
***
## Example cURL Request
```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/order/create \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--data '{
"order_id": 6116229263036,
"order_amount": 105,
"order_currency": "INR",
"order_note": "Additional order info",
"service_type": "DIGITAL",
"customer": {
"name": "Ajay",
"email": "developer@jangras.co",
"phone": "9816512345",
"address": {
"line1": "Capital Office, Kemp House",
"line2": "152 - 160 City Road",
"city": "London",
"state": "London",
"country": "UK",
"postal_code": "EC1V 2NX"
}
},
"return_url": "https://merchant.in/process_return.php?order_id=order_1626945143520"
}'
```
***
## Example Success Response
```json
{
"code": "200",
"status": "success",
"message": "API authentication successful!",
"return_data": {
"kwikX_order_id": "kp_40dec464-7155-43a3-855d-c95c5ab1be71",
"created_at": "13-05-2026 08:34 AM",
"order_id": 6116229263036,
"order_status": "UN_PAID",
"payment_link": "https://sandbox.kwikpaisa.com/payment/checkout/..."
}
}
```
***
## Response Parameters
| Parameter | Description |
| ---------------- | ----------------------------------- |
| `kwikX_order_id` | Unique KwikPaisa generated order ID |
| `created_at` | Order creation timestamp |
| `order_id` | Merchant order ID |
| `order_status` | Current payment status |
| `payment_link` | Hosted checkout payment URL |
***
## Redirect Customer to Payment Link
After receiving the response, redirect the customer to:
```http
payment_link
```
This hosted payment page allows customers to securely complete the transaction using supported payment methods.
***
## Order Status Flow
Possible order statuses:
| Status | Description |
| ------------ | ------------------------------ |
| `UN_PAID` | Payment pending |
| `PROCESSING` | Payment under processing |
| `PAID` | Payment completed successfully |
| `FAILED` | Payment failed |
| `EXPIRED` | Payment session expired |
***
## Important Notes
* `order_id` must always be unique
* Duplicate order IDs may be rejected
* Generate signatures server-side only
* Always validate payment status using Order Status API
* Do not rely only on frontend redirects
***
## Recommended Payment Flow
1. Create Order API
2. Redirect customer to `payment_link`
3. Customer completes payment
4. Receive webhook notification
5. Verify payment using Order Status API
***
## Common Errors
### 400 Bad Request
Possible reasons:
* Missing required parameters
* Invalid payload format
* Invalid order amount
***
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### Duplicate Order ID
Possible reasons:
* Reusing existing `order_id`
* Duplicate payment attempts
***
## Best Practices
* Always use unique order IDs
* Validate payment status server-side
* Verify webhook signatures
* Store `kwikX_order_id` for reconciliation
* Use HTTPS for all requests
# Redirect User
After successfully creating an order using the Create Order API, KwikPaisa returns a hosted checkout URL in the:
```
payment_link
```
parameter.
You must redirect the customer to this payment link to complete the payment securely using the KwikPaisa hosted checkout page.
## Payment Flow
1. Merchant creates payment order
2. KwikPaisa returns `payment_link`
3. Merchant redirects customer to hosted checkout
4. Customer completes payment
5. KwikPaisa redirects customer back to merchant `return_url`
6. Merchant verifies payment using Order Status API or Webhook
***
## Example Create Order Response
```json
{
"code": "200",
"status": "success",
"message": "API authentication successful!",
"return_data": {
"kwikX_order_id": "kp_40dec464-7155-43a3-855d-c95c5ab1be71",
"created_at": "13-05-2026 08:34 AM",
"order_id": 6116229263036,
"order_status": "UN_PAID",
"payment_link": "https://sandbox.kwikpaisa.com/payment/checkout/..."
}
}
```
***
## Redirect Customer
Redirect the customer to:
```
payment_link
```
returned in the API response.
***
## JavaScript Redirect Example
```javascript
window.location.href = response.return_data.payment_link;
```
***
## PHP Redirect Example
```php
header(
"Location: " . $response['return_data']['payment_link']
);
exit;
```
***
## Successful Payment Redirection
After the customer completes the payment successfully, KwikPaisa redirects the customer back to the merchant `return_url`.
The redirect is sent as a GET request with:
```http
?order_id={merchant_order_id}
```
appended automatically.
***
## Example Redirect URL
```http
https://merchant.in/process_return.php?order_id=6116229263036
```
***
## Important Notes
* The `return_url` must be publicly accessible
* Always use HTTPS URLs
* `order_id` returned in redirect is the merchant order ID
* Frontend redirects should not be used as final payment confirmation
* Always verify payment using:
* Order Status API
* Webhook notifications
***
## Recommended Verification Flow
After receiving the redirect:
1. Extract `order_id`
2. Call Order Status API
3. Verify payment status server-side
4. Update transaction status in your system
***
## Why Verification is Important
Customer redirects may fail due to:
* Browser interruptions
* Network issues
* User closing the page
* Device crashes
For reliable payment confirmation, always validate transactions server-side.
***
## Recommended Integration Flow
1. Create Order
2. Redirect customer to `payment_link`
3. Customer completes payment
4. Receive redirect on `return_url`
5. Verify transaction using APIs/webhooks
6. Mark order as successful
***
## Best Practices
* Always verify payment status server-side
* Do not trust frontend redirects alone
* Store merchant `order_id` securely
* Use unique order IDs for every transaction
* Enable webhook handling for real-time updates
# Check Status
Use the Order Status API to fetch the real-time status of a payment order created using the KwikPaisa Payment Gateway.
This API helps merchants:
* Verify payment completion
* Track transaction status
* Validate redirected payments
* Reconcile transactions securely
The Order Status API should always be used for final payment verification instead of relying only on frontend redirects.
***
## Endpoint
```http
POST /api/v3/pg/order/status
```
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
## Authentication required.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
***
## Request Parameters
| Parameter | Type | Required | Description |
| ---------- | -------------- | -------- | ----------------- |
| `order_id` | Integer/String | Yes | Merchant order ID |
***
## Example Request Body
```json
{
"order_id": 6116229263036
}
```
***
## Example cURL Request
```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/order/status \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
"order_id": 6116229263036
}'
```
***
## Example Success Response
```json
{
"code": "200",
"status": "success",
"message": "API authentication successful!",
"return_data": {
"kwikX_order_id": "kp_9b9e725b-b415-40fd-ac1c-068ab508f7e7",
"order_id": "6873654104683",
"order_amount": "105.00",
"order_currency": "INR",
"order_status": "PAID",
"payment_id": "pay_dfg4fgffghfh454",
"order_source": "API",
"created_at": null
}
}
```
***
## Response Parameters
| Parameter | Description |
| ---------------- | --------------------------------------------- |
| `kwikX_order_id` | Unique KwikPaisa order ID |
| `order_id` | Merchant order ID |
| `order_amount` | Transaction amount |
| `order_currency` | Transaction currency |
| `order_status` | Current payment status |
| `payment_id` | Unique payment transaction ID |
| `order_source` | Source of order creation |
| `paymentDetails` | Payment method and transaction details object |
| `created_at` | Order creation timestamp |
| `paid_at` | Payment completion timestamp |
***
## Payment Status Values
| Status | Description |
| ------------ | ------------------------------ |
| `UN_PAID` | Payment pending |
| `PROCESSING` | Payment under processing |
| `PAID` | Payment completed successfully |
| `FAILED` | Payment failed |
| `EXPIRED` | Payment session expired |
***
## Recommended Verification Flow
1. Create Order API
2. Redirect customer to hosted checkout
3. Customer completes payment
4. Receive redirect/webhook
5. Call Order Status API
6. Verify final payment status server-side
***
## Why Order Status Verification is Important
Frontend redirects may not always guarantee successful payments due to:
* Browser interruptions
* Network failures
* Customer closing the payment page
* Delayed bank confirmations
Always verify transactions using the Order Status API before marking orders as successful.
***
## Best Practices
* Always validate payment status server-side
* Verify webhook notifications
* Store `kwikX_order_id` for reconciliation
* Retry status checks for processing transactions
* Avoid duplicate order IDs
***
## Common Errors
### 400 Bad Request
Possible reasons:
* Missing `order_id`
* Invalid payload structure
* Incorrect request format
***
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### Order Not Found
Possible reasons:
* Invalid order ID
* Order does not exist
* Incorrect merchant credentials
***
## Recommended Retry Logic
If the payment status is:
```
PROCESSING
```
Retry the status check after a few seconds before marking the transaction as failed.
***
## Security Recommendations
* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS only
* Validate webhook signatures
* Verify timestamps before processing responses
# Cancel Order
Use the Order Cancel API to cancel an unpaid or pending payment order created using the KwikPaisa Payment Gateway.
This API allows merchants to:
* Cancel abandoned payment sessions
* Expire unpaid payment links
* Prevent duplicate payment attempts
* Manage order lifecycle securely
Only eligible orders can be cancelled successfully.
***
## Endpoint
```http
POST /api/v3/pg/order/cancel
```
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
***
## Authentication required.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
***
## Request Parameters
| Parameter | Type | Required | Description |
| ---------- | -------------- | -------- | ----------------- |
| `order_id` | Integer/String | Yes | Merchant order ID |
***
## Example Request Body
```json
{
"order_id": 6116229263036
}
```
***
## Example cURL Request
```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/order/cancel \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
"order_id": 6116229263036
}'
```
***
## Example Success Response
```json
{
"code": "200",
"status": "success",
"message": "Order cancelled successfully.",
"return_data": {
"order_id": 6116229263036,
"order_status": "CANCELLED",
"cancelled_at": "13-05-2026 09:14 AM"
}
}
```
***
## Response Parameters
| Parameter | Description |
| -------------- | ---------------------------- |
| `order_id` | Merchant order ID |
| `order_status` | Updated order status |
| `cancelled_at` | Order cancellation timestamp |
***
## Cancel Eligible Statuses
Orders can typically be cancelled when they are in:
| Status | Description |
| ------------ | ------------------------ |
| `UN_PAID` | Payment not completed |
| `PROCESSING` | Payment under processing |
Orders that are already:
* `PAID`
* `FAILED`
* `EXPIRED`
* `CANCELLED`
may not be cancellable.
***
## Recommended Use Cases
Use Order Cancel API when:
* Customer abandons checkout
* Payment session expires
* Merchant wants to stop pending payment attempts
* Duplicate orders need cancellation
***
## Important Notes
* `order_id` must belong to your merchant account
* Cancellation may fail for completed payments
* Always verify final order status using Order Status API
* Cancelled payment links should not be reused
***
## Recommended Workflow
1. Create Order
2. Redirect customer to payment page
3. Customer abandons payment or session expires
4. Call Order Cancel API
5. Verify updated order status
***
## Common Errors
### 400 Bad Request
Possible reasons:
* Missing `order_id`
* Invalid request payload
* Incorrect request structure
***
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### Order Cannot Be Cancelled
Possible reasons:
* Payment already completed
* Order already cancelled
* Invalid order state
***
## Security Recommendations
* Generate signatures server-side only
* Use HTTPS for all API requests
* Never expose secret keys publicly
* Verify order ownership before cancellation
* Validate timestamps for every request
***
## Best Practices
* Cancel abandoned payment sessions regularly
* Verify order status before cancellation attempts
* Avoid duplicate payment links
* Store cancellation logs for reconciliation
# Balance Inquiry
Use the Balance Inquiry API to fetch the available payout wallet balance linked to your KwikPaisa merchant account.
This API helps merchants:
* Check available payout balance
* Validate wallet funds before initiating payouts
* Monitor payout account liquidity
* Prevent insufficient balance payout failures
The Balance Inquiry API should be used before initiating bulk or high-value payouts.
***
## Endpoint
```http
POST /api/v3/payout/balance
```
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
***
## Authentication required.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
## Request Body
This API does not require any request payload.
```json
{
"kwikx_wallet_id": "4646464445"
}
```
***
## Example cURL Request
```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/payout/balance \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
"kwikx_wallet_id": "4646464445"
}'
```
***
## Example Success Response
```json
{
"status": true,
"code": 200,
"message": "Wallet balance fetched successfully.",
"data": {
"environment": "sandbox",
"wallet_id": "6116229263036",
"currency": "INR",
"balance": "99990.00",
"ip_status": "approved",
"profile_status": "under_review",
"account_status": "under_review"
}
}
```
***
## Response Parameters
| Parameter | Description |
| ---------------- | --------------------------------------------------- |
| `environment` | Current API environment (`sandbox` or `production`) |
| `wallet_id` | Unique merchant wallet ID |
| `currency` | Wallet currency |
| `balance` | Available wallet balance |
| `ip_status` | Merchant IP whitelist approval status |
| `profile_status` | Merchant profile verification status |
| `account_status` | Merchant account review/approval status |
***
## Recommended Use Cases
Use Balance Inquiry API to:
* Validate payout wallet balance
* Check available funds before payouts
* Monitor operational liquidity
* Prevent payout failures due to insufficient funds
***
## Important Notes
* Balance is returned in real-time
* Currency is currently supported in INR
* Insufficient balance may prevent payout initiation
* Always validate balance before bulk payout processing
***
## Recommended Workflow
1. Check wallet balance
2. Validate available funds
3. Initiate payout transaction
4. Verify payout status using Payout Status API
***
## Common Errors
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### 403 Access Denied
Possible reasons:
* Merchant not authorized for payouts
* Payout services disabled
***
## Security Recommendations
* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS for all requests
* Validate API responses before processing payouts
***
## Best Practices
* Check balance before every payout batch
* Monitor payout wallet regularly
* Maintain sufficient operational balance
* Implement low-balance alerting systems
# Create Payout
Use the Transaction Initiation API to initiate payouts directly from your KwikPaisa wallet to beneficiary bank accounts using supported banking transfer modes.
This API enables merchants to:
* Send instant payouts
* Process salary disbursements
* Automate vendor settlements
* Transfer funds securely
* Build scalable payout workflows
***
## Endpoint
```http
POST /api/v3/banking/payment/create
```
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
***
## Authentication required.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
***
## Request Parameters
{% tabs %}
{% tab title="Bank Transfer" %}
| Parameter | Type | Required | Description |
| ------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `kwikx_wallet_id` | String | Yes | Merchant wallet ID |
| `debit_account_type` | String | Yes | Source account type |
| `transfer_type` | String | Yes | Transfer processing type |
| `mobile` | String | Yes | Merchant mobile number |
| `email` | String | Yes | Merchant email address |
| `country_dialing_code` | String | Yes | Country dialing code |
| `transfer_mode` | String | Yes | Transfer mode (`imps`, `neft`, `rtgs`, `upi`, `ach`, `wire`, `swift`, `sepa`, `bank_transfer`, `wallet`, `card_transfer`, `international`) |
| `transfer_amount` | Decimal | Yes | Transfer amount |
| `payout_order_id` | String/Integer | Yes | Unique merchant payout order ID |
| `account_transfer.account_owner_name` | String | Yes | Beneficiary account holder name |
| `account_transfer.account_number` | String | Yes | Beneficiary account number |
| `account_transfer.ifsc_code` | String | Yes | Beneficiary IFSC code |
| `account_transfer.is_validate` | Boolean/String | No | Validate beneficiary account |
| `account_transfer.payment_for` | String | No | Transfer description |
| {% endtab %} | | | |
{% tab title="UPI" %}
| Parameter | Type | Required | Description |
| ----------------------------- | -------------- | -------- | ------------------------------- |
| `kwikx_wallet_id` | String | Yes | Merchant wallet ID |
| `debit_account_type` | String | Yes | Source account type |
| `transfer_type` | String | Yes | Transfer processing type |
| `beneficiary_id` | String/Null | No | Existing beneficiary reference |
| `mobile` | String | Yes | Merchant mobile number |
| `email` | String | Yes | Merchant email address |
| `address` | String/Null | No | Merchant address |
| `country_dialing_code` | String | Yes | Country dialing code |
| `transfer_mode` | String | Yes | Transfer mode (`upi`) |
| `transfer_amount` | Decimal | Yes | Transfer amount |
| `payout_order_id` | String/Integer | Yes | Unique merchant payout order ID |
| `upi_transfer.upi_owner_name` | String | Yes | Beneficiary UPI holder name |
| `upi_transfer.upi_id` | String | Yes | Beneficiary UPI ID |
| `upi_transfer.is_validate` | Boolean/String | No | Validate beneficiary UPI ID |
| `upi_transfer.payment_for` | String | No | Transfer description |
| {% endtab %} | | | |
| {% endtabs %} | | | |
## Example Request Body'
{% tabs %}
{% tab title="Bank Transfer" %}
```json
{
"kwikx_wallet_id": "9896989698",
"debit_account_type": "kwikx_wallet",
"transfer_type": "direct",
"mobile": "9896989698",
"email": "email@example.com",
"country_dialing_code": "91",
"transfer_mode": "imps",
"transfer_amount": "9999999999",
"payout_order_id": "9999999999",
"account_transfer": {
"account_owner_name": "beneficiary name",
"account_number": "6760654654",
"ifsc_code": "icici000143",
"is_validate": "false",
"payment_for": "salary payment"
}
}
```
{% endtab %}
{% tab title="UPI" %}
```json
{
"kwikx_wallet_id": "9896989698",
"debit_account_type": "kwikx_wallet",
"transfer_type": "direct",
"mobile": "9896989698",
"email": "email@example.com",
"country_dialing_code": "91",
"transfer_mode": "upi",
"transfer_amount": "9999999999",
"payout_order_id": "9999999999",
"upi_transfer": {
"upi_owner_name": "beneficiary name",
"upi_id": "upi-owner@upi",
"is_validate": "false",
"payment_for": "salary payment"
}
}
```
{% endtab %}
{% endtabs %}
## Example cURL Request
{% tabs %}
{% tab title="Bank Transfer" %}
```json
curl -X POST https://sandbox.kwikpaisa.com/api/v3/banking/payment/create \
-H "X-API-KEY: pk_test_mQZnmh2BeSDTjEQgzwiSPOhrWyUsPqS6" \
-H "X-SIGNATURE: 623a603fa35bb5ab736a1272dcd797908ab9af4b0247a55bcfc8676cd821a39b" \
-H "X-TIMESTAMP: 1778659835" \
-H "Content-Type: application/json" \
-d '{
"kwikx_wallet_id": "9896989698",
"debit_account_type": "kwikx_wallet",
"transfer_type": "direct",
"mobile": "9896989698",
"email": "email@example.com",
"country_dialing_code": "91",
"transfer_mode": "imps",
"transfer_amount": "9999999999",
"payout_order_id": "9999999999",
"account_transfer": {
"account_owner_name": "beneficiary name",
"account_number": "6760654654",
"ifsc_code": "icici000143",
"is_validate": "false",
"payment_for": "salary payment"
}
}'
```
{% endtab %}
{% tab title="UPI" %}
```json
curl -X POST https://sandbox.kwikpaisa.com/api/v3/banking/payment/create \
-H "X-API-KEY: pk_test_mQZnmh2BeSDTjEQgzwiSPOhrWyUsPqS6" \
-H "X-SIGNATURE: 623a603fa35bb5ab736a1272dcd797908ab9af4b0247a55bcfc8676cd821a39b" \
-H "X-TIMESTAMP: 1778659835" \
-H "Content-Type: application/json" \
-d '{
"kwikx_wallet_id": "9896989698",
"debit_account_type": "kwikx_wallet",
"transfer_type": "direct",
"mobile": "9896989698",
"email": "email@example.com",
"country_dialing_code": "91",
"transfer_mode": "upi",
"transfer_amount": "9999999999",
"payout_order_id": "9999999999",
"upi_transfer": {
"upi_owner_name": "beneficiary name",
"upi_id": "upi-owner@upi",
"is_validate": "false",
"payment_for": "salary payment"
}
}'
```
{% endtab %}
{% endtabs %}
## Example Success Response
```json
{
"status": true,
"code": 200,
"message": "Payout initiated successfully.",
"data": {
"payout_id": "payout_2c17a19bc5be6d05",
"payout_order_id": 1778761733,
"wallet_id": "2026-04-30 13:01:32",
"debited_amount": 99,
"available_balance": 98627.88
}
}
```
***
## Response Parameters
| Parameter | Description |
| ------------------- | ------------------------------------ |
| `payout_id` | Unique KwikPaisa payout reference ID |
| `payout_order_id` | Merchant payout order ID |
| `wallet_id` | Wallet transaction reference |
| `debited_amount` | Amount debited from wallet |
| `available_balance` | Remaining wallet balance |
***
## Example Failed Response
### Insufficient Wallet Balance
```json
{
"status": false,
"code": 422,
"message": "Insufficient wallet balance."
}
```
***
### Transaction Not Found
```json
{
"code": 404,
"status": false,
"message": "Order not found",
"return_data": {
"payout_id": null,
"payout_order_id": "68736541046834",
"payout_status": null
}
}
```
***
## Supported Transfer Modes
| Transfer Mode | Description |
| --------------- | --------------------------------------------------- |
| `imps` | Instant bank transfer available 24x7 |
| `neft` | Standard bank settlement transfer |
| `rtgs` | Real-time gross settlement for high-value transfers |
| `upi` | Instant UPI transfer using UPI ID |
| `ach` | Automated Clearing House batch transfer |
| `wire` | International wire transfer |
| `swift` | International SWIFT banking transfer |
| `sepa` | Eurozone SEPA bank transfer |
| `bank_transfer` | Standard domestic bank transfer |
| `wallet` | Wallet-to-wallet transfer |
| `card_transfer` | Card-based payout transfer |
| `international` | International cross-border payout |
## Recommended Payout Flow
1. Check wallet balance
2. Generate payout request signature
3. Initiate payout transaction
4. Store `payout_id` and `payout_order_id`
5. Verify payout using Payout Status API
6. Handle webhook notifications
***
## Important Notes
* `payout_order_id` must always be unique
* Duplicate payout IDs may be rejected
* Ensure sufficient wallet balance before initiating payouts
* Beneficiary bank details should be validated carefully
* Always verify payout status server-side
***
## Common Errors
### 400 Bad Request
Possible reasons:
* Missing required parameters
* Invalid payload structure
* Invalid IFSC code
* Incorrect account details
***
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### 422 Insufficient Wallet Balance
Possible reasons:
* Wallet balance too low
* Transfer amount exceeds available balance
***
### 404 Order Not Found
Possible reasons:
* Invalid payout order ID
* Transaction does not exist
* Incorrect merchant credentials
***
## Security Recommendations
* Always generate signatures server-side
* Never expose secret keys publicly
* Use HTTPS for all API requests
* Validate beneficiary details carefully
* Monitor payout reconciliation regularly
***
## Best Practices
* Use unique payout order IDs
* Validate account details before payouts
* Store payout references securely
* Retry processing payouts carefully
* Enable webhook handling for real-time payout updates
# Check Payout Status
Use the Payout Status API to fetch the real-time status of a payout transaction initiated using the KwikPaisa Banking APIs.
This API helps merchants:
* Verify payout completion
* Track transaction processing
* Monitor payout failures
* Validate fund settlement
* Reconcile payout transactions
The Payout Status API should always be used for final payout verification instead of relying only on payout initiation responses.
***
## Endpoint
```http
POST /api/v3/banking/payment/status
```
#### To view all available base URLs and environments, refer to:
➡️ [API Resources](/v3-guide/quick-start/api-resources)
***
## Authentication required.
Refer to:\
➡️ [Headers](/v3-guide/authentication/headers)\
➡️ [Signature Generation](/v3-guide/authentication/signature)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp)
***
## Request Parameters
| Parameter | Type | Required | Description |
| -------------------- | -------------- | -------- | ------------------------ |
| `kwikx_wallet_id` | String | Yes | Merchant wallet ID |
| `debit_account_type` | String | Yes | Source account type |
| `payout_order_id` | String/Integer | Yes | Merchant payout order ID |
***
## Example Request Body
```json
{
"kwikx_wallet_id": "177s8761897",
"debit_account_type": "kwikx_wallet",
"payout_order_id": "177s8761897"
}
```
***
## Example cURL Request
```http
curl -X POST https://sandbox.kwikpaisa.com/api/v3/banking/payment/status \
-H "X-API-KEY: pk_test_xxxxxxxxx" \
-H "X-SIGNATURE: GENERATED_SIGNATURE" \
-H "X-TIMESTAMP: GENERATED_TIMESTAMP" \
-H "Content-Type: application/json" \
-d '{
"kwikx_wallet_id": "177s8761897",
"debit_account_type": "kwikx_wallet",
"payout_order_id": "177s8761897"
}'
```
***
## Example Success Response
```json
{
"status": true,
"code": 200,
"message": "Payout status fetched successfully.",
"data": {
"payout_id": "payout_a782fdb71b5e1659",
"payout_order_id": "1778761734",
"wallet_id": "2026-04-30 13:01:32",
"status": "SUCCESS",
"amount": "99",
"currency": "INR",
"utr_number": "UAT1778761735",
"message": "Funds debited successfully",
"amount_debited": "YES",
"created_at": "14-05-2026"
}
}
```
***
## Response Parameters
| Parameter | Description |
| ----------------- | ------------------------------------ |
| `payout_id` | Unique KwikPaisa payout reference ID |
| `payout_order_id` | Merchant payout order ID |
| `wallet_id` | Wallet transaction reference |
| `status` | Current payout status |
| `amount` | Payout amount |
| `currency` | Transaction currency |
| `utr_number` | Bank UTR/reference number |
| `message` | Transaction processing message |
| `amount_debited` | Indicates whether amount was debited |
| `created_at` | Payout transaction creation date |
***
## Payout Status Values
| Status | Description |
| ------------ | ------------------------------ |
| `SUCCESS` | Payout completed successfully |
| `FAILED` | Payout failed |
| `PROCESSING` | Payout under processing |
| `PENDING` | Awaiting bank confirmation |
| `REVERSED` | Amount reversed back to wallet |
***
## Example Failed Response
### Transaction Not Found
```json
{
"status": false,
"code": 404,
"message": "Payout transaction not found."
}
```
***
### Failed Transaction Response
```json
{
"status": true,
"code": 200,
"message": "Payout status fetched successfully.",
"data": {
"payout_id": "payout_b7c9d4d780db71e8",
"payout_order_id": "1778761897",
"wallet_id": "2026-04-30 13:01:32",
"status": "FAILED",
"amount": "9999999999",
"currency": "INR",
"utr_number": "NA",
"message": "Txn failed due to insufficient funds",
"amount_debited": "NO",
"created_at": "14-05-2026"
}
}
```
***
### Invalid Wallet ID
```json
{
"status": false,
"code": 403,
"message": "Invalid wallet ID for selected environment."
}
```
***
## Recommended Verification Flow
1. Initiate payout transaction
2. Store `payout_id` and `payout_order_id`
3. Call Payout Status API
4. Verify final payout status
5. Reconcile payout transactions
6. Update transaction records
***
## Important Notes
* `payout_order_id` must always be unique
* Wallet ID must belong to the selected environment
* Sandbox and production wallet IDs are different
* UTR numbers may take time to generate
* Always verify payout status server-side
***
## Common Errors
### 400 Bad Request
Possible reasons:
* Missing required parameters
* Invalid request payload
* Incorrect request structure
***
### 401 Unauthorized
Possible reasons:
* Invalid API key
* Incorrect signature
* Expired timestamp
***
### 403 Invalid Wallet ID
Possible reasons:
* Wrong environment wallet ID
* Invalid merchant wallet
***
### 404 Payout Transaction Not Found
Possible reasons:
* Invalid payout order ID
* Transaction does not exist
* Incorrect merchant credentials
***
## Security Recommendations
* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS for all payout requests
* Store payout references securely
* Validate payout responses before processing
***
## Best Practices
* Verify every payout transaction server-side
* Store UTR/reference numbers
* Maintain payout audit logs
* Retry processing payouts carefully
* Enable webhook notifications for real-time updates
# Cancel Payout
The Cancel Payout feature allows merchants to stop or revoke payout transactions before they are processed successfully by the banking system.
This functionality is designed for:
* Scheduled payouts
* Queued transactions
* Delayed settlement workflows
* Bulk payout management systems
Currently, payout cancellation support is limited and available only for eligible payout states.
***
## Current Availability
The Cancel Payout feature is currently under development and may not be available for all merchants or payout modes.
At present:
* Instant payouts generally cannot be cancelled once initiated
* Successfully processed payouts cannot be reversed using this API
* Only queued or scheduled payouts may support cancellation
Availability depends on:
* Transfer mode
* Banking partner
* Processing stage
* Merchant configuration
***
## When Payouts Can Be Cancelled
Payouts may be cancellable only when they are:
| Status | Cancellation Support |
| ------------ | -------------------- |
| `QUEUED` | Supported |
| `SCHEDULED` | Supported |
| `PROCESSING` | Limited support |
| `SUCCESS` | Not supported |
| `FAILED` | Not required |
| `REVERSED` | Not supported |
***
## Queued Payout Cancellation
Queued payouts are transactions that are accepted by the system but not yet processed by banking infrastructure.
These transactions may be cancelled before:
* Bank submission
* Settlement processing
* Fund debit confirmation
Cancellation success depends on whether the payout has already entered the bank processing pipeline.
***
## Scheduled Payout Cancellation
Scheduled payouts are future-dated payout instructions configured for execution at a later date or time.
These payouts can generally be:
* Cancelled
* Modified
* Rescheduled
before the scheduled execution window begins.
Scheduled payout support is useful for:
* Salary disbursement systems
* Vendor settlement scheduling
* Subscription payouts
* Bulk settlement operations
***
## Instant Payout Limitations
Most real-time payout modes such as:
* IMPS
* UPI
* RTGS (post-processing)
* Instant bank transfers
are processed immediately after initiation.
Once a payout enters active banking rails:
* Cancellation may no longer be possible
* Funds may already be debited
* Bank processing may already be completed
For this reason, instant payout cancellation is generally not supported.
***
## Recommended Merchant Workflow
Before initiating payouts:
1. Validate beneficiary details
2. Verify payout amount
3. Check wallet balance
4. Validate duplicate payout IDs
5. Confirm transfer mode carefully
After payout initiation:
1. Track payout status
2. Monitor processing state
3. Attempt cancellation only for eligible payouts
4. Verify final payout outcome using Payout Status API
***
## Important Notes
* Payout cancellation is not guaranteed
* Successful cancellation depends on payout state
* Processed payouts cannot be reversed automatically
* Merchants should validate transactions carefully before initiation
* Some banking partners may not support payout cancellation
***
## Future Enhancements
KwikPaisa is actively working on:
* Scheduled payout management
* Advanced payout queue controls
* Bulk payout cancellation
* Payout pause/resume workflows
* Real-time payout orchestration controls
These features will be introduced gradually based on infrastructure and banking partner support.
***
## Recommended Best Practices
* Use scheduled payouts for large settlement operations
* Avoid initiating duplicate payout requests
* Implement internal payout approval workflows
* Verify beneficiary details before payout execution
* Monitor payout statuses continuously
***
## Security & Compliance Notes
For security and regulatory reasons:
* Completed payouts cannot be forcefully reversed
* Banking settlements are governed by partner bank rules
* Certain payout modes may have irreversible processing behavior
Merchants are responsible for validating:
* Beneficiary details
* Transfer amounts
* Transaction references
* Approval workflows
before initiating payouts.
***
## Need Help?
If you require:
* Scheduled payout enablement
* Queue management support
* Bulk payout orchestration
* Advanced payout controls
please contact the KwikPaisa integration and onboarding team.
# Webhook setup
KwikPaisa Webhooks allow merchants to receive real-time payment and payout notifications directly on their server without continuously polling APIs.
Webhooks are recommended for:
* Payment status updates
* Payout status updates
* Settlement notifications
* Transaction reconciliation
* Automated workflow processing
Using webhooks helps merchants build faster, scalable, and reliable transaction systems.
***
## What are Webhooks?
A webhook is an HTTP callback sent by KwikPaisa to your server whenever a transaction event occurs.
Instead of repeatedly checking transaction status APIs, KwikPaisa automatically pushes updates to your configured webhook endpoint.
***
## Supported Webhook Events
{% tabs %}
{% tab title="PG Orders Events" %}
| Event | Description |
| ----------------------------- | -------------------------------------- |
| `pg.order.created` | Order created successfully |
| `pg.order.updated` | Order details updated |
| `pg.order.pending` | Order awaiting payment |
| `pg.order.processing` | Order is being processed |
| `pg.order.completed` | Order completed successfully |
| `pg.order.failed` | Order processing failed |
| `pg.order.cancelled` | Order cancelled |
| `pg.order.expired` | Order session expired |
| `pg.order.closed` | Order closed |
| `pg.order.refund_initiated` | Refund initiated for order |
| `pg.order.refunded` | Order refunded successfully |
| `pg.order.partially_refunded` | Partial refund processed for order |
| `pg.order.dispute.created` | Dispute created for order |
| `pg.order.dispute.closed` | Order dispute resolved/closed |
| `pg.order.chargeback.created` | Chargeback initiated for order |
| `pg.order.payment.success` | Payment received for order |
| `pg.order.payment.failed` | Payment attempt failed for order |
| `pg.order.webhook.failed` | Order webhook delivery failed |
| `pg.order.webhook.retrying` | Retrying failed order webhook delivery |
| {% endtab %} | |
{% tab title="PG Payments Events" %}
| Event | Description |
| ------------------------------- | ------------------------------------- |
| `pg.payment.created` | Payment order created |
| `pg.payment.pending` | Payment pending from customer |
| `pg.payment.processing` | Payment is being processed |
| `pg.payment.success` | Payment completed successfully |
| `pg.payment.failed` | Payment failed |
| `pg.payment.cancelled` | Payment cancelled |
| `pg.payment.expired` | Payment session expired |
| `pg.payment.refunded` | Full refund processed |
| `pg.payment.partially_refunded` | Partial refund processed |
| `pg.refund.created` | Refund request created |
| `pg.refund.processing` | Refund under processing |
| `pg.refund.success` | Refund completed successfully |
| `pg.refund.failed` | Refund failed |
| `pg.settlement.created` | Settlement generated |
| `pg.settlement.processed` | Settlement processed successfully |
| `pg.settlement.failed` | Settlement processing failed |
| `pg.dispute.created` | Payment dispute created |
| `pg.dispute.updated` | Dispute details updated |
| `pg.dispute.won` | Dispute resolved in merchant favor |
| `pg.dispute.lost` | Dispute lost |
| `pg.dispute.closed` | Dispute closed |
| `pg.dispute.fee.withdrawal` | Dispute handling fee deducted |
| `pg.dispute.fee.refunded` | Dispute fee refunded |
| `pg.chargeback.created` | Chargeback initiated |
| `pg.chargeback.processing` | Chargeback under review |
| `pg.chargeback.won` | Chargeback resolved in merchant favor |
| `pg.chargeback.lost` | Chargeback lost |
| `pg.chargeback.closed` | Chargeback closed |
| `pg.withdrawal.created` | Wallet withdrawal initiated |
| `pg.withdrawal.processing` | Withdrawal under processing |
| `pg.withdrawal.success` | Withdrawal completed successfully |
| `pg.withdrawal.failed` | Withdrawal failed |
| `pg.webhook.failed` | Webhook delivery failed |
| `pg.webhook.retrying` | Webhook retry attempt in progress |
| {% endtab %} | |
{% tab title="Payout Events" %}
| Event | Description |
| ---------------------------- | --------------------------------------- |
| `po.payout.created` | Payout request created |
| `po.payout.queued` | Payout added to processing queue |
| `po.payout.processing` | Payout is being processed |
| `po.payout.success` | Payout completed successfully |
| `po.payout.failed` | Payout failed |
| `po.payout.reversed` | Payout reversed back to wallet |
| `po.payout.cancelled` | Payout cancelled |
| `po.payout.refunded` | Payout amount refunded |
| `po.payout.pending` | Payout pending approval or processing |
| `po.payout.on_hold` | Payout temporarily placed on hold |
| `po.payout.bank_rejected` | Bank rejected payout request |
| `po.payout.bank_processing` | Bank is processing payout |
| `po.payout.retrying` | Payout retry attempt initiated |
| `po.payout.timeout` | Payout processing timed out |
| `po.payout.webhook.failed` | Payout webhook delivery failed |
| `po.payout.webhook.retrying` | Retrying failed payout webhook delivery |
| {% endtab %} | |
| {% endtabs %} | |
***
## Webhook URL Requirements
Your webhook endpoint must:
* Be publicly accessible
* Support HTTPS
* Accept `POST` requests
* Return HTTP `200 OK` quickly
* Handle JSON payloads properly
***
## Example Webhook URL
```
https://merchant.com/api/webhooks/kwikpaisa
```
## Webhook Request Method
```
POST
```
***
## Webhook Headers `UNDER DEVELOPMENT`
```
Content-Type: application/json
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP
```
***
## Webhook Security `UNDER DEVELOPMENT`
Every webhook request is signed using HMAC SHA256 signature verification.
Webhook signatures should always be validated before processing webhook data.
The signature is generated using:
```
HMAC_SHA256(payload + timestamp, secret_key)
```
***
## Example Payment Webhook Payload
```json
{
"event": "pg.payment.success",
"code": 200,
"status": true,
"message": "API authentication successful!",
"data": {
"kwikX_order_id": "kp_9b9e725b-b415-40fd-ac1c-068ab508f7e7",
"order_id": "6873654104683",
"payment_id": "pay_dgfdggdgdfg",
"order_amount": "105.00",
"order_currency": "INR",
"order_status": "PAID",
"order_source": "API",
"created_at": null,
"paymentDetails": {}
}
}
```
***
## Example Payout Webhook Payload
```json
{
"event": "po.payout.success",
"data": {
"order_id": "1778761734",
"kwikx_payout_id": "payout_a782fdb71b5e1659",
"status": "SUCCESS",
"amount": "99",
"currency": "INR",
"utr_number": "UAT1778761735",
"txnLog": {
"account_transfer": {
"account_number": "6760654654",
"account_owner_name": "beneficiary name",
"ifsc_code": "icici000143",
"is_validate": "false",
"payment_for": "salary payment"
},
"address": null,
"beneficiary_id": null,
"country_dialing_code": "91",
"debit_account_type": "kwikx_wallet",
"email": "email@example.com",
"kwikx_wallet_id": "2026-04-30 13:01:32",
"mobile": "9896989698",
"payout_order_id": 1778761734,
"transfer_amount": "99",
"transfer_mode": "imps",
"transfer_type": "direct",
"api_user_id": 472,
"business_profile_id": 96,
"api_key_id": 8,
"mode": "sandbox"
},
"processed_at": "2026-05-14 12:28:55"
}
}
```
***
## Webhook Verification Process
Recommended verification steps:
1. Read webhook payload
2. Extract `X-SIGNATURE` header
3. Extract `X-TIMESTAMP` header
4. Generate local signature
5. Compare generated signature with received signature
6. Process webhook only if signatures match
***
## Example Node.js Verification
```
const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const timestamp = req.headers['x-timestamp'];
const receivedSignature = req.headers['x-signature'];
const generatedSignature = crypto
.createHmac('sha256', 'YOUR_SECRET_KEY')
.update(payload + timestamp)
.digest('hex');
if (generatedSignature === receivedSignature) {
console.log('Webhook verified');
} else {
console.log('Invalid webhook signature');
}
```
***
## Webhook Response Requirements
Your server should return:
```
HTTP 200 OK
```
immediately after successful webhook processing.
***
## Retry Mechanism
If your server:
* Times out
* Returns non-200 responses
* Fails to respond
KwikPaisa may retry webhook delivery automatically.
***
## Recommended Retry Handling
Your webhook system should:
* Handle duplicate events safely
* Store webhook logs
* Use idempotent processing
* Verify transaction status using APIs when needed
***
## Best Practices
* Always validate webhook signatures
* Use HTTPS endpoints only
* Respond quickly with HTTP 200
* Process webhook logic asynchronously
* Store webhook payloads for audit logs
* Verify final transaction status server-side
***
## Important Notes
* Webhooks should not be trusted without verification
* Duplicate webhook events may occur
* Payment status should always be verified server-side
* Webhooks complement APIs and do not replace verification APIs
***
## Common Errors
### Invalid Signature
Possible reasons:
* Incorrect secret key
* Payload modification
* Timestamp mismatch
***
### Webhook Timeout
Possible reasons:
* Slow webhook processing
* Server downtime
* Network failures
***
## Recommended Production Workflow
1. Receive webhook
2. Verify signature
3. Validate payload
4. Store webhook event
5. Verify transaction status using APIs
6. Update merchant system
7. Return HTTP 200 response
# Signature verification
Under Development
KwikPaisa signs every webhook request using HMAC SHA256 to ensure webhook authenticity and payload integrity.
Webhook signature verification helps merchants:
* Verify webhook authenticity
* Prevent unauthorized requests
* Detect payload tampering
* Protect webhook endpoints against replay attacks
All webhook requests should always be verified before processing transaction data.
***
## Webhook Headers
Every webhook request contains:
```http
Content-Type: application/json
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP
```
## Signature Formula
Refer to: \\
➡️ [Signature Generation](/v3-guide/authentication/signature)
## Verification Process
To verify a webhook request:
1. Read the raw webhook payload
2. Extract `X-SIGNATURE` header
3. Extract `X-TIMESTAMP` header
4. Generate local HMAC SHA256 signature
5. Compare generated signature with received signature
6. Process webhook only if signatures match
***
## Important Rules
* Use the raw request payload exactly as received
* Do not modify JSON formatting before verification
* Verify timestamps to prevent replay attacks
* Reject invalid signatures immediately
* Always use your server-side `secret_key`
***
## Example Webhook Payload
```
{
"event": "payment.success",
"data": {
"order_id": "6116229263036",
"amount": "105.00",
"currency": "INR",
"status": "PAID"
}
}
```
***
{% tabs %}
{% tab title="Node.js" %}
```javascript
const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const timestamp = req.headers['x-timestamp'];
const receivedSignature = req.headers['x-signature'];
const generatedSignature = crypto
.createHmac('sha256', 'YOUR_SECRET_KEY')
.update(payload + timestamp)
.digest('hex');
if (generatedSignature === receivedSignature) {
console.log('Webhook verified successfully');
} else {
console.log('Invalid webhook signature');
}
```
{% endtab %}
{% tab title="PHP" %}
```php
setTimeout(resolve, (i + 1) * 5000)
);
}
console.log('Maximum retries exceeded');
}
```
***
## Recommended Retry Workflow
1. Initiate transaction
2. Receive processing response
3. Retry status verification carefully
4. Process webhook notifications
5. Verify final transaction status
6. Update internal systems
***
## Duplicate Transaction Protection
Before retrying:
* Verify transaction status first
* Check existing transaction references
* Avoid duplicate payout initiation
* Avoid duplicate payment orders
***
## Common Retry Mistakes
Avoid:
* Infinite retry loops
* Aggressive retry intervals
* Duplicate payout creation
* Reusing expired timestamps
* Ignoring webhook events
***
## Security Recommendations
* Generate fresh timestamps for retries
* Regenerate signatures for every request
* Verify webhook signatures
* Store retry logs securely
* Use HTTPS only
***
## Logging Recommendations
Always log:
* Retry attempts
* API responses
* Transaction statuses
* Error responses
* Webhook events
This helps with:
* Reconciliation
* Audit tracking
* Failure investigation
* Debugging
***
## Best Practices
* Use idempotent transaction IDs
* Implement exponential backoff
* Verify transaction status before retries
* Handle webhooks asynchronously
* Maintain reconciliation logs
* Monitor retry failures continuously
***
## Important Notes
* Banking delays are normal in some scenarios
* Processing transactions may take time
* Final confirmation should always happen server-side
* Webhooks may arrive after API responses
# Go Live
Before moving your KwikPaisa integration to production, merchants should complete all security validations, UAT testing, webhook verification, reconciliation checks, and operational readiness reviews.
Going live means your application will begin processing real customer payments and payouts using production banking infrastructure.
Proper production readiness helps ensure:
* Stable transaction processing
* Secure API communication
* Reliable payment workflows
* Accurate payout settlements
* Safe customer experience
***
## Production Readiness Requirements
Before production activation, merchants should ensure:
* Sandbox integration completed successfully
* UAT testing approved
* Webhook verification implemented
* Signature validation working correctly
* Retry handling configured
* Error handling implemented
* Transaction reconciliation validated
* Security review completed
***
## Production Base URL
```http
https://api.kwikpaisa.com
```
## Production Credentials
Production credentials are issued after successful onboarding and compliance verification.
Example production headers:
```
Content-Type: application/jsonAccept: application/jsonX-API-KEY: pk_live_xxxxxxxxxX-SIGNATURE: GENERATED_SIGNATUREX-TIMESTAMP: GENERATED_TIMESTAMP
```
***
## Environment Migration Checklist
Before switching from Sandbox to production:
| Requirement | Status |
| ----------------------------- | ----------- |
| Replace Sandbox API keys | Required |
| Replace Sandbox secret keys | Required |
| Update production base URLs | Required |
| Configure production webhooks | Required |
| Verify signature generation | Required |
| Enable IP whitelisting | Recommended |
| Validate retry workflows | Required |
| Enable transaction monitoring | Recommended |
***
## Production Security Requirements
Merchants should implement:
* HTTPS-only communication
* Server-side signature generation
* Secure credential storage
* Webhook signature verification
* Replay attack protection
* Access control policies
* Transaction audit logging
***
## Webhook Production Setup
Before going live:
* Configure production webhook URLs
* Verify webhook signatures
* Test duplicate event handling
* Implement webhook retries
* Store webhook audit logs
Webhook endpoints must:
* Be publicly accessible
* Support HTTPS
* Return HTTP 200 quickly
* Handle JSON payloads properly
***
## Transaction Monitoring
Production systems should continuously monitor:
* Payment success rates
* Payout processing
* Failed transactions
* Webhook delivery status
* API response failures
* Retry attempts
* Reconciliation mismatches
***
## Recommended Production Workflow
### Payment Flow
1. Create payment order
2. Redirect customer to hosted checkout
3. Receive webhook notification
4. Verify payment using Order Status API
5. Update internal order status
6. Reconcile settlements
***
### Payout Flow
1. Check payout wallet balance
2. Initiate payout
3. Track payout status
4. Store UTR/reference numbers
5. Verify webhook notifications
6. Reconcile payout records
***
## Logging Recommendations
Merchants should securely log:
* API requests
* API responses
* Transaction references
* Webhook payloads
* Retry attempts
* Error responses
* Signature verification results
These logs help with:
* Debugging
* Audit tracking
* Reconciliation
* Compliance reviews
***
## Common Production Issues
### Invalid Signature
Possible reasons:
* Incorrect secret key
* Payload modification
* Timestamp mismatch
***
### Webhook Failures
Possible reasons:
* Incorrect webhook URL
* SSL certificate issues
* Slow webhook responses
***
### Authentication Errors
Possible reasons:
* Invalid production API keys
* Expired timestamps
* Incorrect signature generation
## Recommended Go-Live Checklist
Before enabling live traffic:
* Complete end-to-end testing
* Verify webhook security
* Validate reconciliation workflows
* Test failure handling
* Verify retry logic
* Confirm production credentials
* Enable monitoring systems
* Review operational alerts
***
## Security Recommendations
* Never expose production secret keys
* Restrict API access securely
* Rotate credentials periodically
* Validate all incoming webhooks
* Maintain audit logs for compliance
***
## Best Practices
* Monitor transactions continuously
* Validate payment and payout statuses server-side
* Use idempotent transaction IDs
* Implement retry-safe workflows
* Maintain reconciliation systems
* Handle webhook events asynchronously
## Important Notes
* Production transactions involve real money movement
* Banking settlement delays may occur
* Webhook delivery timing may vary
* Final transaction validation should always happen server-side
# Production checklist
Before enabling live transactions, merchants should complete all required production readiness checks to ensure secure, stable, and reliable payment and payout operations.
This checklist helps validate:
* API integration readiness
* Security implementation
* Webhook configuration
* Transaction monitoring
* Reconciliation workflows
* Operational stability
Completing the production checklist helps reduce:
* Failed transactions
* Security risks
* Reconciliation mismatches
* Duplicate processing
* Downtime issues
***
## API Configuration Checklist
Ensure the following are completed:
| Requirement | Status |
| --------------------------------- | -------- |
| Production API keys configured | Required |
| Production secret keys configured | Required |
| Sandbox credentials removed | Required |
| Production base URLs updated | Required |
| HTTPS enabled for all APIs | Required |
| Signature generation verified | Required |
***
## Authentication Validation
Verify:
* `X-API-KEY` is correct
* `X-SIGNATURE` generation is accurate
* `X-TIMESTAMP` is generated dynamically
* Signatures are generated server-side only
Required headers:
```http
Content-Type: application/json
Accept: application/json
X-API-KEY: pk_live_xxxxxxxxx
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP
```
## Webhook Checklist
Verify webhook setup carefully before going live.
| Requirement | Status |
| ------------------------------------------ | ----------- |
| Production webhook URL configured | Required |
| HTTPS webhook endpoint enabled | Required |
| Webhook signature verification implemented | Required |
| Duplicate webhook handling implemented | Required |
| Webhook retry handling implemented | Required |
| Webhook logging enabled | Recommended |
***
## Payment Gateway Checklist
Validate:
* Order creation flow
* Hosted checkout redirects
* Payment success handling
* Payment failure handling
* Order status verification
* Reconciliation workflows
***
## Payout Checklist
Validate:
* Wallet balance verification
* Payout initiation flow
* Payout status tracking
* UTR/reference handling
* Failed payout handling
* Retry logic implementation
***
## Security Checklist
Before production activation:
| Security Requirement | Status |
| ----------------------------------- | ----------- |
| Secret keys stored securely | Required |
| HTTPS enforced | Required |
| Webhook signatures validated | Required |
| Replay attack protection enabled | Recommended |
| IP whitelisting configured | Recommended |
| Access control policies implemented | Recommended |
***
## Retry Handling Checklist
Verify:
* Processing transaction retries
* Exponential backoff handling
* Duplicate transaction prevention
* Idempotent transaction IDs
* Webhook retry processing
***
## Transaction Monitoring Checklist
Production systems should monitor:
* API failures
* Payment success rates
* Payout processing
* Webhook delivery failures
* Retry attempts
* Reconciliation mismatches
* Duplicate transactions
***
## Logging Checklist
Enable logging for:
* API requests
* API responses
* Webhook payloads
* Signature verification
* Retry attempts
* Error responses
* Transaction references
Logs are critical for:
* Debugging
* Compliance audits
* Reconciliation
* Issue investigation
***
## Recommended Testing Before Go-Live
Before enabling production traffic:
* Complete end-to-end testing
* Validate payment success flow
* Validate payment failure flow
* Test payout workflows
* Verify webhook delivery
* Confirm signature validation
* Test retry logic
* Validate reconciliation workflows
***
## Operational Readiness Checklist
Ensure:
* Support teams are informed
* Monitoring systems are active
* Incident response plans exist
* Transaction alerts are configured
* Operational escalation flows are ready
***
## Common Production Mistakes
Avoid:
* Using Sandbox credentials in production
* Exposing secret keys publicly
* Ignoring webhook verification
* Blind retry loops
* Duplicate payout requests
* Missing reconciliation workflows
***
## Best Practices
* Validate all transactions server-side
* Use idempotent transaction references
* Monitor webhook failures continuously
* Store audit logs securely
* Implement retry-safe workflows
* Maintain reconciliation systems
***
## Important Notes
* Production APIs process real financial transactions
* Banking confirmations may take time
* Webhook timing may vary
* Final settlement verification should always happen server-side
***
## Final Go-Live Validation
Before accepting live traffic:
✅ Security validation completed\
✅ Webhook verification working\
✅ Retry handling implemented\
✅ Reconciliation workflows validated\
✅ Monitoring enabled\
✅ Production credentials configured\
✅ UAT testing approved
# IP whitelisting
IP Whitelisting adds an additional security layer by allowing API access only from trusted server IP addresses configured on your KwikPaisa merchant account.
When IP Whitelisting is enabled:
* Only approved server IPs can access production APIs
* Unauthorized requests are automatically blocked
* API security is significantly improved
IP Whitelisting is strongly recommended for all production merchants handling payments and payouts.
***
## Why IP Whitelisting is Important
IP Whitelisting helps protect against:
* Unauthorized API access
* Credential misuse
* Malicious API requests
* Unauthorized payout attempts
* External attack vectors
Even if API credentials are compromised, requests from unapproved IP addresses will be rejected.
***
## How IP Whitelisting Works
When a request reaches the KwikPaisa infrastructure:
1. The source server IP is validated
2. The IP is matched against approved merchant IPs
3. Requests from approved IPs are processed
4. Requests from unapproved IPs are blocked automatically
***
## Recommended Use Cases
IP Whitelisting is highly recommended for:
* Production payment systems
* Payout processing systems
* Banking integrations
* Financial reconciliation systems
* Backend transaction services
***
## Recommended Server Types
Whitelist only trusted backend infrastructure such as:
* Dedicated servers
* Cloud application servers
* Secure API gateways
* Production backend systems
* VPN-restricted infrastructure
Avoid whitelisting:
* Personal devices
* Dynamic residential IPs
* Public networks
* Development machines
***
## Example Production Request Headers
```http
Content-Type: application/json
Accept: application/json
X-API-KEY: pk_live_xxxxxxxxx
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP
```
## Supported IP Types
KwikPaisa supports:
* IPv4 addresses
* Static public IPs
* Dedicated cloud server IPs
Example:
```bash
103.21.244.15
```
***
## Multiple IP Support
Merchants may whitelist multiple IP addresses for:
* Load-balanced infrastructure
* Multi-server deployments
* Backup production systems
* Disaster recovery environments
***
## Environment Separation
Sandbox and production environments may use different IP configurations.
Ensure:
* Production IPs are whitelisted separately
* Sandbox testing IPs are configured correctly
* Environment credentials are not mixed
***
## IP Change Management
If your production server IP changes:
1. Contact KwikPaisa support
2. Submit updated IP addresses
3. Wait for confirmation before sending production traffic
Requests from unapproved IPs may fail immediately.
***
## Example Access Failure
If a request originates from a non-whitelisted IP:
```json
{
"status": false,
"code": 403,
"message": "IP address is not whitelisted."
}
```
***
## Common Reasons for IP Rejection
Possible reasons:
* Incorrect production IP
* Dynamic IP changes
* Load balancer IP mismatch
* Cloud infrastructure migration
* Environment configuration issues
***
## Security Recommendations
* Use static public IPs only
* Restrict API access to backend servers
* Rotate credentials periodically
* Combine IP Whitelisting with webhook verification
* Monitor unauthorized access attempts
***
## Best Practices
* Maintain updated IP records
* Whitelist backup infrastructure carefully
* Review IP access regularly
* Remove unused IPs immediately
* Avoid exposing production APIs publicly
***
## Operational Recommendations
Merchants should maintain:
* IP inventory records
* Infrastructure documentation
* Backup IP procedures
* Emergency access escalation workflows
***
## Important Notes
* IP Whitelisting is a production security feature
* Whitelisting does not replace signature verification
* All API requests must still include valid authentication headers
* Requests from blocked IPs will not reach transaction processing systems
***
## Recommended Security Stack
KwikPaisa recommends combining:
* IP Whitelisting
* HMAC SHA256 signatures
* HTTPS-only communication
* Webhook verification
* Replay attack protection
* Secure credential storage
for maximum production security.
## Geo-Restricted IP Access
For additional compliance and fraud prevention, KwikPaisa may enforce geo-restricted API access for payout services.
This means payout APIs should generally be accessed only from server infrastructure located in the same country as the registered merchant entity.
Example:
* Indian merchants should use Indian server infrastructure
* UAE merchants should use UAE-hosted infrastructure
* UK merchants should use UK-hosted infrastructure
***
## Why Geo Restrictions are Important
Geo-restricted access helps:
* Prevent unauthorized international payout activity
* Reduce fraud risks
* Improve regulatory compliance
* Enhance banking security controls
* Protect merchant payout infrastructure
***
## Example
If a merchant account is registered in India:
✅ Recommended:
* India-based cloud servers
* India-hosted backend infrastructure
* Indian static public IP addresses
❌ Not Recommended:
* Foreign VPS servers
* International proxy routing
* Dynamic overseas infrastructure
***
## Supported Infrastructure
Recommended hosting providers:
* AWS India
* Google Cloud India
* Azure India
* Indian dedicated server providers
* Secure India-based VPS infrastructure
***
## Important Notes
* Geo validation may apply only to payout APIs
* Payment Gateway APIs may have different restrictions
* Cross-border payout enablement may require additional approval
* Certain international payout corridors may support global infrastructure separately
***
## Compliance Recommendations
Merchants should:
* Use static public IPs
* Host payout systems in the merchant operating country
* Avoid routing payout APIs through VPNs or proxies
* Maintain infrastructure compliance documentation
***
## Security Recommendations
KwikPaisa recommends combining:
* Geo-restricted IP access
* IP whitelisting
* HMAC SHA256 signatures
* HTTPS-only communication
* Webhook verification
for maximum payout security.
# Security checks
KwikPaisa recommends implementing multiple security layers before enabling production payment and payout processing.
Security checks help protect:
* Merchant accounts
* Customer transactions
* Banking infrastructure
* API credentials
* Payout systems
* Webhook endpoints
Production financial systems should always follow strict security and compliance standards.
***
## Core Security Requirements
All merchants should implement:
* HTTPS-only communication
* HMAC SHA256 signature verification
* Secure credential storage
* Webhook signature validation
* Replay attack protection
* Server-side transaction validation
* Transaction monitoring
***
## API Authentication Security
Every API request must include valid authentication headers:
```http
X-API-KEY
X-SIGNATURE
X-TIMESTAMP
```
KwikPaisa validates:
* Merchant authentication
* Request integrity
* Timestamp freshness
* Payload authenticity
Invalid or tampered requests are rejected automatically.
## Signature Verification
All requests should use HMAC SHA256 signatures.
Signature verification protects against:
* Payload tampering
* Unauthorized API access
* Replay attacks
* Forged transaction requests
Recommended formula:
Refer to:\
➡️ Authentication → [Signature](/v3-guide/authentication/signature)
***
## Timestamp Validation
Timestamps help prevent replay attacks.
Merchants should:
* Generate fresh timestamps for every request
* Use UNIX timestamps in seconds
* Synchronize server time properly
* Reject expired requests
***
## Secret Key Protection
Your `secret_key` is highly sensitive.
Never:
* Expose secret keys publicly
* Store credentials in frontend applications
* Commit credentials to Git repositories
* Share production keys insecurely
Recommended storage:
* Environment variables
* Secure secret managers
* Encrypted infrastructure storage
***
## HTTPS Enforcement
All APIs and webhook endpoints must use HTTPS.
HTTPS protects:
* Transaction payloads
* API credentials
* Customer data
* Banking communication
Non-HTTPS integrations may be blocked in production environments.
***
## Webhook Security
Webhook endpoints should always:
* Verify webhook signatures
* Validate timestamps
* Handle duplicate events safely
* Return HTTP 200 quickly
* Process requests asynchronously
Never trust webhook payloads without verification.
***
## Replay Attack Protection
Replay attacks occur when attackers reuse previously valid requests.
To prevent replay attacks:
* Validate timestamps
* Reject old requests
* Generate unique transaction IDs
* Use idempotent processing
* Verify signatures properly
***
## IP Whitelisting
Production merchants are strongly encouraged to enable:
* Static IP whitelisting
* Geo-restricted payout access
* Secure backend-only API access
Only trusted backend infrastructure should access production APIs.
***
## Transaction Validation
Before processing transactions:
* Verify payment status using APIs
* Validate payout status server-side
* Check webhook authenticity
* Confirm transaction references
* Prevent duplicate transaction handling
***
## Logging & Monitoring
Merchants should securely monitor:
* Failed authentication attempts
* Invalid signature requests
* Webhook failures
* Duplicate transaction attempts
* Suspicious payout activity
* API error spikes
Maintain secure audit logs for:
* Compliance
* Reconciliation
* Security investigations
***
## Recommended Security Architecture
KwikPaisa recommends:
| Security Layer | Recommended |
| --------------------- | ----------- |
| HTTPS | Yes |
| HMAC SHA256 | Yes |
| IP Whitelisting | Yes |
| Webhook Verification | Yes |
| Replay Protection | Yes |
| Idempotent Processing | Yes |
| Audit Logging | Yes |
***
## Common Security Risks
Avoid:
* Exposing production credentials
* Using frontend signature generation
* Ignoring webhook verification
* Blind retry loops
* Sharing API keys publicly
* Running production APIs from unsecured servers
***
## Infrastructure Recommendations
Production systems should use:
* Dedicated backend infrastructure
* Static public IPs
* Secure firewall rules
* VPN-restricted administrative access
* Encrypted storage systems
* Monitoring and alerting tools
***
## Operational Security Recommendations
Merchants should:
* Rotate credentials periodically
* Restrict internal API access
* Maintain access logs
* Review payout activities regularly
* Monitor webhook failures continuously
***
## Compliance Recommendations
Depending on merchant category and geography, merchants may be required to:
* Maintain transaction logs
* Store reconciliation records
* Follow banking compliance rules
* Enable audit tracking
* Support dispute investigations
***
## Best Practices
* Validate every transaction server-side
* Use unique transaction references
* Implement retry-safe workflows
* Handle webhooks asynchronously
* Monitor production systems continuously
* Test security controls regularly
***
## Important Notes
* Production APIs process real financial transactions
* Banking security controls may vary by region
* Payout systems may have additional compliance requirements
* Security validation should be reviewed periodically
***
## Final Production Security Checklist
Before going live:
✅ HTTPS enabled\
✅ Signatures verified\
✅ Webhook validation implemented\
✅ Retry protection configured\
✅ IP whitelisting enabled\
✅ Audit logging configured\
✅ Monitoring systems active\
✅ Credentials secured
***
## Need Help?
For production security reviews, IP whitelisting, payout compliance, or advanced infrastructure security assistance, contact the KwikPaisa onboarding and integration team.
# Special Rules
Certain business categories may be classified as high-risk based on transaction behavior, industry type, regulatory exposure, dispute ratios, fraud patterns, settlement risks, or banking partner policies.
High-risk merchants may be subject to additional operational, security, compliance, and payout controls to ensure platform stability and regulatory compliance.
These rules help protect:
* Banking infrastructure
* Merchant operations
* Customer transactions
* Settlement systems
* Regulatory obligations
***
## What is a High-Risk Merchant?
A merchant may be categorized as high-risk due to factors such as:
* High transaction volume
* Elevated refund or chargeback ratios
* Regulatory-sensitive industries
* High payout frequency
* International transaction exposure
* Fraud-prone business models
* Rapid transaction spikes
* Unusual settlement patterns
***
## Examples of High-Risk Categories
Examples may include:
* Gaming platforms
* Betting or fantasy systems
* Forex-related services
* International remittance services
* Crypto-related businesses
* High-volume digital services
* Subscription-heavy platforms
* Multi-level marketing systems
* Adult-content related services
* Aggregator payout systems
Classification depends on:
* Banking partner policies
* Compliance review
* Transaction behavior
* Jurisdiction regulations
***
## Enhanced Verification Requirements
High-risk merchants may require:
* Extended KYC verification
* Business ownership validation
* Enhanced due diligence
* Banking verification
* Settlement review approval
* Operational risk assessment
Additional documentation may be requested during onboarding or periodic reviews.
***
## Transaction Monitoring
High-risk merchant accounts may be monitored more aggressively for:
* Unusual transaction spikes
* Fraud indicators
* Abnormal payout activity
* High refund rates
* Suspicious settlement behavior
* Velocity anomalies
Automated risk systems may temporarily:
* Delay settlements
* Restrict payouts
* Trigger manual reviews
* Require additional verification
***
## Payout Restrictions
Additional payout controls may apply to high-risk merchants.
Possible restrictions include:
| Restriction | Description |
| ------------------- | --------------------------------------------- |
| Delayed Settlements | Settlement hold periods may apply |
| Daily Payout Limits | Maximum payout caps may exist |
| Rolling Reserves | Partial settlement reserves may be maintained |
| Manual Review | High-value payouts may require review |
| Geo Restrictions | Country-based payout controls may apply |
***
## Reserve Policies
Certain merchants may be subject to reserve requirements.
Reserve mechanisms help protect against:
* Chargebacks
* Fraud losses
* Settlement disputes
* Regulatory exposure
Reserve types may include:
* Rolling reserves
* Fixed reserves
* Delayed settlement reserves
Reserve policies depend on:
* Merchant category
* Transaction history
* Banking partner requirements
* Risk profile
***
## Enhanced Security Requirements
High-risk merchants should implement:
* Strict IP whitelisting
* Geo-restricted payout infrastructure
* Multi-layer authentication
* Advanced fraud monitoring
* Webhook verification
* Secure payout approval workflows
KwikPaisa may require additional production security validation before activation.
***
## Infrastructure Recommendations
Recommended infrastructure controls:
* Dedicated production servers
* Static public IP addresses
* Country-specific payout infrastructure
* Restricted administrative access
* Audit logging systems
* Real-time monitoring tools
***
## Compliance Requirements
High-risk merchants may require:
* Periodic compliance reviews
* Transaction audit reports
* Settlement reconciliation records
* Regulatory reporting support
* Source-of-funds verification
* Beneficiary validation
Failure to comply may result in:
* Temporary restrictions
* Settlement delays
* Payout suspension
* Account review
***
## Transaction Velocity Controls
KwikPaisa risk systems may automatically monitor:
* Transactions per minute
* Payout frequency
* Rapid balance movement
* High-value transaction bursts
* Unusual account activity
Automated protection systems may temporarily:
* Limit transactions
* Pause payouts
* Require manual review
* Trigger enhanced verification
***
## Webhook & API Monitoring
High-risk merchants should maintain:
* Webhook audit logs
* Transaction retry logs
* API access monitoring
* Security event tracking
* Fraud detection systems
Continuous monitoring is strongly recommended.
***
## Best Practices
High-risk merchants should:
* Maintain strong reconciliation systems
* Validate all beneficiary details
* Monitor fraud activity continuously
* Review payout behavior regularly
* Store detailed audit logs
* Implement internal approval workflows
***
## Important Notes
* Risk classification may change over time
* Banking partner policies may vary
* Additional controls may apply dynamically
* Production access may require periodic review
KwikPaisa reserves the right to:
* Modify settlement policies
* Adjust payout controls
* Enforce additional compliance checks
* Restrict unsupported business models
based on operational, regulatory, or banking requirements.
***
## Recommended Production Controls
KwikPaisa strongly recommends:
✅ IP Whitelisting\
✅ Geo-Restricted Payout Access\
✅ Webhook Verification\
✅ Replay Attack Protection\
✅ Idempotent Processing\
✅ Audit Logging\
✅ Fraud Monitoring\
✅ Secure Credential Storage
for all high-risk production merchants.
***
## Need Help?
For high-risk merchant onboarding, settlement approvals, reserve policy discussions, payout enablement, or advanced compliance requirements, contact the KwikPaisa onboarding and risk management team.
# Web Checkout APIs
# Create Order
Hosted Checkout order creation APIs
## Create Hosted Checkout Order
> Creates a hosted checkout payment order and returns\
> a secure payment link for customer redirection. 
