API Documentation — DhanSolution Payment Gateway

概述 | Overview

DhanSolution 支付网关支持 两种货币，每个商户固定分配一种货币。系统根据商户的货币自动选择支付通道。

DhanSolution payment gateway supports two currencies. Each merchant is assigned one currency, and the system automatically routes payments to the correct channel.

INR 印度卢比 — UPI / 银行转账
支付类型 (Pay-In): INRUPI
出款类型 (Payout): 银行转账 (需提供银行名称、账号、IFSC)

PKR 巴基斯坦卢比 — JazzCash / EasyPaisa
支付类型 (Pay-In): PKRPH (JazzCash) 或 PKRPH-EASY (EasyPaisa)
出款类型 (Payout): 钱包转账 (需提供CNIC、钱包号码、手机号)

身份验证 | Authentication

所有 API 请求都需要身份验证。请将您的凭证作为 POST 参数发送。
All API requests require authentication. Send your credentials as POST parameters:

Parameter	Type	Description
`api_key`	String	Your API Key (find in Credentials page)
`api_secret`	String	Your API Secret (find in Credentials page)

All requests use application/x-www-form-urlencoded. Responses are JSON.

1. 创建支付 | Create Payment (Pay-In)

POST ?route=payment/create

创建付款订单。返回一个用于跳转客户的支付链接。
Create a payment order. Returns a payment URL to redirect the customer.

INR INR 商户无需传递 trade_type，系统自动使用 INRUPI。

PKR PKR 商户可通过 trade_type 参数选择支付方式：PKRPH（JazzCash，默认）或 PKRPH-EASY（EasyPaisa）。

Parameter	Type	Required	Description
`amount`	Float	Yes	Payment amount (e.g. 100.00)
`trade_type`	String	No	PKR only `PKRPH` (JazzCash) or `PKRPH-EASY` (EasyPaisa). Default: `PKRPH`. Not needed for INR.
`remark`	String	No	Order remark (returned in callback)
`ip`	String	No	Customer IP address
`notify_url`	String	No	Your webhook URL for callbacks

INR Example Request:

curl -X POST "https://dhansolution.in/pay/api/index.php?route=payment/create" \
-d "api_key=ds_your_api_key" \
-d "api_secret=your_api_secret" \
-d "amount=100.00" \
-d "remark=Order #123"

PKR Example Request (JazzCash):

curl -X POST "https://dhansolution.in/pay/api/index.php?route=payment/create" \
-d "api_key=ds_your_api_key" \
-d "api_secret=your_api_secret" \
-d "amount=1000.00" \
-d "trade_type=PKRPH" \
-d "remark=Order #123"

Example Response:

{
"status": 1,
"message": "ok",
"data": {
"order_id": "DHAN20260701123456",
"amount": 100.00,
"currency": "INR",
"pay_url": "https://dhansolution.in/pay/...",
"type": "url"
}
}

2. 查询支付状态 | Check Payment Status

POST ?route=payment/status

查询现有付款订单的状态。
Check the status of an existing payment order.

Parameter	Type	Required	Description
`order_id`	String	Yes	The order ID from payment/create

Example Response:

{
"status": 1,
"message": "ok",
"data": {
"order_id": "DHAN20260701123456",
"amount": 100.00,
"paid_amount": 100.00,
"currency": "INR",
"status": "success",
"created_at": "2026-07-01 12:00:00",
"paid_at": "2026-07-01 12:05:00",
"remark": "Order #123"
}
}

Status Values: pending · success · failed · expired

3. 查询余额 | Check Balance

POST ?route=balance

查询您的可用余额。
Check your available balance.

响应中 currency 字段返回您商户的货币类型 (INR 或 PKR)。
The currency field returns your merchant's assigned currency (INR or PKR).

{
"status": 1,
"message": "ok",
"data": {
"currency": "INR",
"lg_balance": "50000.00",
"merchant_balance": "45000.00"
}
}

4. 创建出款 | Create Payout

POST ?route=payout/create

发起出款到受益人账户。资金会从您的余额中扣除。
Initiate a payout to a beneficiary. Funds are deducted from your balance.

INR 出款 PKR 出款

INR 银行转账出款 — 需要受益人银行信息：银行名称、账号、IFSC。

Parameter	Type	Required	Description
`amount`	Float	Yes	Payout amount (must be ≤ available balance)
`account_name`	String	Yes	Beneficiary account holder name
`bank_name`	String	Yes	Beneficiary bank name (e.g. HDFC Bank)
`account_number`	String	Yes	Beneficiary bank account number
`ifsc`	String	Yes	Beneficiary IFSC code (e.g. HDFC0001234)
`phone`	String	No	Beneficiary phone number
`remark`	String	No	Payout remark
`notify_url`	String	No	Webhook URL for payout callbacks

INR Example Request:

curl -X POST "https://dhansolution.in/pay/api/index.php?route=payout/create" \
-d "api_key=ds_your_api_key" \
-d "api_secret=your_api_secret" \
-d "amount=500.00" \
-d "account_name=John Doe" \
-d "bank_name=HDFC Bank" \
-d "account_number=12345678901" \
-d "ifsc=HDFC0001234"

PKR 钱包转账出款 — 需要受益人钱包信息：CNIC号、钱包号码、手机号、钱包类型 (jazzcash/easypaisa)。

Parameter	Type	Required	Description
`amount`	Float	Yes	Payout amount (must be ≤ available balance)
`account_name`	String	Yes	Beneficiary account holder name
`account_number`	String	Yes	Beneficiary wallet number (03xxxxxxxxx)
`phone`	String	Yes	Beneficiary phone number (03xxxxxxxxx)
`uid`	String	Yes	CNIC number (format: 42201-1234567-1)
`card_number`	String	Yes	Card number
`addon1`	String	Yes	Wallet type: `jazzcash` or `easypaisa`
`remark`	String	No	Payout remark
`notify_url`	String	No	Webhook URL for payout callbacks

PKR Example Request (JazzCash):

curl -X POST "https://dhansolution.in/pay/api/index.php?route=payout/create" \
-d "api_key=ds_your_api_key" \
-d "api_secret=your_api_secret" \
-d "amount=500.00" \
-d "account_name=Muhammad Ali" \
-d "account_number=03001234567" \
-d "phone=03001234567" \
-d "uid=42201-1234567-1" \
-d "card_number=1234567890123456" \
-d "addon1=jazzcash"

Example Response (both currencies):

{
"status": 1,
"message": "ok",
"data": {
"order_id": "PO20260701123456",
"amount": 500.00,
"currency": "INR",
"status": "processing"
}
}

5. 查询出款状态 | Check Payout Status

POST ?route=payout/status

实时查询出款状态。
Check the real-time status of a payout.

Parameter	Type	Required	Description
`order_id`	String	Yes	The payout order ID

{
"status": 1,
"message": "ok",
"data": {
"order_id": "PO20260701123456",
"amount": 500.00,
"currency": "INR",
"status": "success",
"created_at": "2026-07-01 12:00:00",
"paid_at": "2026-07-01 12:30:00",
"account_name": "John Doe"
}
}

Status Values: pending · processing · success · failed

6. 支付回调通知 | Pay-In Webhook

当支付完成时，DhanSolution 会向您的 notify_url 发送回调。
When a payment is completed, DhanSolution sends a callback to your notify_url.

Header	Description
`X-DhanSolution-Signature`	HMAC-SHA256 signature of JSON body using your webhook secret
`X-DhanSolution-Event`	Event type: `payment.completed`

Callback Body:

{
"event": "payment.completed",
"order_id": "DHAN20260701123456",
"amount": 100.00,
"paid_amount": 100.00,
"currency": "INR",
"status": "success",
"paid_at": "2026-07-01 12:05:00",
"remark": "Order #123"
}

$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DHANSOLUTION_SIGNATURE'];
$expected = hash_hmac('sha256', $body, 'your_webhook_secret');
if (hash_equals($expected, $signature)) {
// Valid callback - process the order
}
http_response_code(200);
exit('ok');

重要提示 | Important: 必须在5秒内返回 HTTP 200 "ok"。重试间隔：1分 → 5分 → 15分 → 30分 → 1小时 → 6小时 → 24小时。
Respond with HTTP 200 "ok" within 5 seconds. Retries: 1min → 5min → 15min → 30min → 1hr → 6hr → 24hr.

7. 出款回调通知 | Payout Webhook

当出款状态更新时，DhanSolution 会向您的 notify_url 发送回调。
When a payout status updates, DhanSolution sends a callback to your notify_url.

Header	Description
`X-DhanSolution-Signature`	HMAC-SHA256 signature of JSON body using your webhook secret
`X-DhanSolution-Event`	Event type: `payout.completed`

{
"event": "payout.completed",
"order_id": "PO20260701123456",
"amount": 500.00,
"currency": "INR",
"status": "success",
"paid_at": "2026-07-01 12:30:00",
"account_name": "John Doe"
}

重要提示 | Important: 与支付回调相同的重试规则。
Same retry schedule as pay-in webhooks.

错误代码 | Error Codes

Code	Message	Description
401	Missing API credentials	API key or secret not provided
401	Invalid API credentials	API key or secret is incorrect
400	Invalid amount	Amount must be greater than 0
400	Missing order_id	Order ID required for status check
400	Insufficient balance	Balance less than payout amount
400	Missing required fields	Required payout fields not provided
400	Invalid trade_type	Invalid trade_type for PKR merchant. Use PKRPH or PKRPH-EASY
404	Order not found	No order found with given ID

API 接口文档 | Documentation