Skip to main content
POST/payout/v1/status

Transaction 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

AttributeDetails
MethodGET
URLhttps://merchant.paywize.in/api/payout/v1/status
AuthenticationBearer token required
Content-Typeapplication/json
EncryptionResponse data is AES-256-CBC encrypted
Rate Limit200 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):

ParameterRequiredTypeDescription
transaction_idOptionalStringTransaction ID (IRN) returned from initiate payout
sender_idOptionalStringUnique 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

FieldTypeDescription
transaction_idStringPaywize generated unique transaction ID
sender_idStringMerchant provided unique sender ID
wallet_idStringMerchant wallet ID
amountStringTransfer amount
payment_modeStringPayment mode used (IMPS, NEFT, RTGS)
remarksStringTransfer description
statusStringCurrent transaction status (INITIATED, PROCESSING, SUCCESS, FAILED, REFUNDED)
status_messageStringDescriptive message about the current status
utr_numberStringUnique Transaction Reference number from bank
beneficiaryObjectBeneficiary information object
beneficiary.beneficiary_nameStringBeneficiary account holder name
beneficiary.beneficiary_acc_numberStringBeneficiary account number
beneficiary.beneficiary_ifscStringBeneficiary bank IFSC code
timestampsObjectTransaction timestamp information
timestamps.created_atStringTransaction creation timestamp (ISO 8601 format)
timestamps.updated_atStringLast update timestamp (ISO 8601 format)

Transaction Status Values

Status CodeDescriptionStatus Message Examples
INITIATEDTransaction has been initiated"Payment initiated", "Transaction created successfully"
PROCESSINGTransaction is being processed"Payment in progress", "Processing with bank"
SUCCESSTransaction completed successfully"Payment completed successfully", "Amount transferred successfully"
FAILEDTransaction failed"Payment failed", "Insufficient balance", "Invalid beneficiary details"
REFUNDEDTransaction 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

CodeMessage
2000Transaction fetched successfully

Client Error Responses

CodeMessageDescription
4101Missing TxnId or senderIdEither transaction_id or sender_id parameter is required
4102Only provide transaction_id or sender_id not bothEither transaction_id or sender_id only one parameter is required
CodeMessageDescription
4001Unauthorized – invalid or expired tokenJWT token is invalid, expired, or missing
CodeMessageDescription
4103Transaction not foundNo 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

  1. Parameter Validation: Always validate that either txn_id or client_ref_id is provided, but not both
  2. Error Handling: Implement proper error handling for all possible response codes
  3. Token Management: Ensure your JWT token is valid and refresh if expired
  4. Polling Strategy: For real-time updates, consider implementing webhooks instead of frequent polling
  5. Data Decryption: Always decrypt response data to access actual transaction details
  6. Logging: Log API requests for debugging but never log decrypted sensitive data
  7. 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 →

Next Steps