/payout/v1/statusTransaction Status
Check real-time payout transaction status via Paywize API.
Last updated: 2026-02-21
Transaction Status
Overview
Check the current status of a payout transaction using either the transaction ID or sender ID. This endpoint provides real-time transaction status and detailed information.
Quick Reference
| Attribute | Details |
|---|---|
| Method | GET |
| URL | https://merchant.paywize.in/api/payout/v1/status |
| Authentication | Bearer token required |
| Content-Type | application/json |
| Encryption | Response data is AES-256-CBC encrypted |
| Rate Limit | 200 requests/minute |
Endpoint
Authentication Required: Bearer token
Authentication
This endpoint requires a valid JWT Bearer token. Learn how to generate tokens: Authentication Guide →
Request Headers
Content-Type: application/json
Authorization: Bearer <jwt_token>
Query Parameters
You must provide either transaction_id or sender_id (at least one is required):
| Parameter | Required | Type | Description |
|---|---|---|---|
| transaction_id | Optional | String | Transaction ID (IRN) returned from initiate payout |
| sender_id | Optional | String | Unique sender ID provided during payout initiation |
Note: Either transaction_id OR sender_id must be provided (at least one is required).
Sample Requests
Using Transaction ID
GET https://merchant.paywize.in/api/payout/v1/status?transaction_id=PAY123456789
Using Sender ID
GET https://merchant.paywize.in/api/payout/v1/status?sender_id=unique_transaction_id
Response
Success Response (200 OK)
{
"resp_code": 2000,
"resp_message": "Transaction fetched successfully",
"data": "U2FsdGVkX1+XYZ789...encrypted_response_here"
}
Decrypted Response Data
{
"transaction_id": "PAY123456789",
"sender_id": "unique_transaction_id",
"wallet_id": "virtual_account_number",
"amount": "1000.00",
"payment_mode": "IMPS",
"remarks": "Payment",
"status": "SUCCESS",
"status_message": "Payment completed successfully",
"utr_number": "415612345678",
"beneficiary": {
"beneficiary_name": "John Doe",
"beneficiary_acc_number": "123456789012",
"beneficiary_ifsc": "HDFC0001234"
},
"timestamps": {
"created_at": "2025-11-05T12:30:15Z",
"updated_at": "2025-11-05T12:35:22Z"
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
| transaction_id | String | Paywize generated unique transaction ID |
| sender_id | String | Merchant provided unique sender ID |
| wallet_id | String | Merchant wallet ID |
| amount | String | Transfer amount |
| payment_mode | String | Payment mode used (IMPS, NEFT, RTGS) |
| remarks | String | Transfer description |
| status | String | Current transaction status (INITIATED, PROCESSING, SUCCESS, FAILED, REFUNDED) |
| status_message | String | Descriptive message about the current status |
| utr_number | String | Unique Transaction Reference number from bank |
| beneficiary | Object | Beneficiary information object |
| beneficiary.beneficiary_name | String | Beneficiary account holder name |
| beneficiary.beneficiary_acc_number | String | Beneficiary account number |
| beneficiary.beneficiary_ifsc | String | Beneficiary bank IFSC code |
| timestamps | Object | Transaction timestamp information |
| timestamps.created_at | String | Transaction creation timestamp (ISO 8601 format) |
| timestamps.updated_at | String | Last update timestamp (ISO 8601 format) |
Transaction Status Values
| Status Code | Description | Status Message Examples |
|---|---|---|
| INITIATED | Transaction has been initiated | "Payment initiated", "Transaction created successfully" |
| PROCESSING | Transaction is being processed | "Payment in progress", "Processing with bank" |
| SUCCESS | Transaction completed successfully | "Payment completed successfully", "Amount transferred successfully" |
| FAILED | Transaction failed | "Payment failed", "Insufficient balance", "Invalid beneficiary details" |
| REFUNDED | Transaction amount refunded | "Amount refunded to wallet", "Transaction reversed" |
Note: Status codes are accessed via status and status messages via status_message in the response object.
Error Responses
Success Response
| Code | Message |
|---|---|
2000 | Transaction fetched successfully |
Client Error Responses
| Code | Message | Description |
|---|---|---|
4101 | Missing TxnId or senderId | Either transaction_id or sender_id parameter is required |
4102 | Only provide transaction_id or sender_id not both | Either transaction_id or sender_id only one parameter is required |
| Code | Message | Description |
|---|---|---|
4001 | Unauthorized – invalid or expired token | JWT token is invalid, expired, or missing |
| Code | Message | Description |
|---|---|---|
4103 | Transaction not found | No transaction found with provided transaction_id or sender_id |
Implementation Examples
JavaScript
import crypto from 'crypto';
function decryptMerchantData(data, key, iv) {
const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
const decrypted = Buffer.concat([
decipher.update(Buffer.from(data, 'base64')),
decipher.final()
]);
return decrypted.toString('utf8');
}
async function checkPayoutStatus(token, transactionId = null, senderId = null, apiKey, secretKey) {
// Validate parameters
if (!transactionId && !senderId) {
throw new Error('Either transaction_id or sender_id is required');
}
if (transactionId && senderId) {
throw new Error('Provide either transaction_id or sender_id, not both');
}
// Build query parameter
const queryParam = transactionId ? `transaction_id=${transactionId}` : `sender_id=${senderId}`;
const url = `https://merchant.paywize.in/api/payout/v1/status?${queryParam}`;
const response = await fetch(url, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
}
});
const result = await response.json();
if (result.resp_code === 2000) {
const decryptedData = decryptMerchantData(result.data, apiKey, secretKey);
return JSON.parse(decryptedData);
} else {
throw new Error(`API Error ${result.resp_code}: ${result.resp_message}`);
}
}
// Usage examples
try {
// Check by transaction ID
const statusByTxnId = await checkPayoutStatus(jwtToken, 'PAY123456789', null, apiKey, secretKey);
console.log('Status by transaction_id:', statusByTxnId);
// Check by sender ID
const statusBySenderId = await checkPayoutStatus(jwtToken, null, 'unique_transaction_id', apiKey, secretKey);
console.log('Status by sender_id:', statusBySenderId);
} catch (error) {
console.error('Status check failed:', error.message);
}
Python
import requests
import json
from encryption_utils import decrypt_merchant_data
def check_payout_status(token, api_key, secret_key, transaction_id=None, sender_id=None):
# Validate parameters
if not transaction_id and not sender_id:
raise ValueError('Either transaction_id or sender_id is required')
if transaction_id and sender_id:
raise ValueError('Provide either transaction_id or sender_id, not both')
# Build query parameter
query_param = f'transaction_id={transaction_id}' if transaction_id else f'sender_id={sender_id}'
url = f'https://merchant.paywize.in/api/payout/v1/status?{query_param}'
response = requests.get(
url,
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
}
)
result = response.json()
if result['resp_code'] == 2000:
decrypted_data = decrypt_merchant_data(result['data'], api_key, secret_key)
return json.loads(decrypted_data)
else:
raise Exception(f"API Error {result['resp_code']}: {result['resp_message']}")
# Usage examples
try:
# Check by transaction ID
status_by_txn_id = check_payout_status(jwt_token, api_key, secret_key, transaction_id='PAY123456789')
print('Status by transaction_id:', status_by_txn_id)
# Check by sender ID
status_by_sender_id = check_payout_status(jwt_token, api_key, secret_key, sender_id='unique_transaction_id')
print('Status by sender_id:', status_by_sender_id)
except Exception as error:
print('Status check failed:', str(error))
PHP
<?php
require_once 'PaywizeEncryption.php';
function checkPayoutStatus($token, $apiKey, $secretKey, $transactionId = null, $senderId = null) {
// Validate parameters
if (!$transactionId && !$senderId) {
throw new InvalidArgumentException('Either transaction_id or sender_id is required');
}
if ($transactionId && $senderId) {
throw new InvalidArgumentException('Provide either transaction_id or sender_id, not both');
}
// Build query parameter
$queryParam = $transactionId ? "transaction_id=$transactionId" : "sender_id=$senderId";
$url = "https://merchant.paywize.in/api/payout/v1/status?$queryParam";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPGET, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result['resp_code'] == 2000) {
$decryptedData = PaywizeEncryption::decryptMerchantData($result['data'], $apiKey, $secretKey);
return json_decode($decryptedData, true);
} else {
throw new Exception("API Error {$result['resp_code']}: {$result['resp_message']}");
}
}
// Usage examples
try {
// Check by transaction ID
$statusByTxnId = checkPayoutStatus($jwtToken, $apiKey, $secretKey, 'PAY123456789');
echo "Status by transaction_id: " . json_encode($statusByTxnId) . "\n";
// Check by sender ID
$statusBySenderId = checkPayoutStatus($jwtToken, $apiKey, $secretKey, null, 'unique_transaction_id');
echo "Status by sender_id: " . json_encode($statusBySenderId) . "\n";
} catch (Exception $error) {
echo "Status check failed: " . $error->getMessage() . "\n";
}
?>
cURL Example
# Check status by transaction ID
curl -X GET "https://merchant.paywize.in/api/payout/v1/status?transaction_id=PAY123456789" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
# Check status by sender ID
curl -X GET "https://merchant.paywize.in/api/payout/v1/status?sender_id=unique_transaction_id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Status Flow
graph TD
A[INITIATED] --> B[PROCESSING]
B --> C[SUCCESS]
B --> D[FAILED]
B --> E[PENDING]
E --> C
E --> D
D --> F[REFUNDED]
Best Practices
- Parameter Validation: Always validate that either txn_id or client_ref_id is provided, but not both
- Error Handling: Implement proper error handling for all possible response codes
- Token Management: Ensure your JWT token is valid and refresh if expired
- Polling Strategy: For real-time updates, consider implementing webhooks instead of frequent polling
- Data Decryption: Always decrypt response data to access actual transaction details
- Logging: Log API requests for debugging but never log decrypted sensitive data
- Status Interpretation: Handle all possible status values in your application logic
Webhook Alternative
Instead of polling for status updates, consider implementing webhooks for real-time notifications: Learn about Webhooks →