POST/collection/v1/status

Payment Status

Check real-time payment collection status via Paywize API.

Last updated: 2026-02-21

Status Check

Overview

Check the current status of a payment transaction using either the transaction ID (txnId) or sender ID (senderId). This endpoint provides real-time transaction status and payment details.

Quick Reference

Attribute	Details
Method	GET
URL	`https://merchant.paywize.in/api/collection/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 txnId or senderId (not both):

Parameter	Required	Type	Description
txnId	Optional	String	Unique transaction ID provided by Paywize
senderId	Optional	String	Unique sender ID provided by merchant

Note: You must provide either txnId OR senderId, but not both.

Sample Requests

Using Transaction ID

GET https://merchant.paywize.in/api/collection/v1/status?txnId=CFCE140825000009

Using Sender ID

GET https://merchant.paywize.in/api/collection/v1/status?senderId=SENDERID000345

Response

Success Response (200 OK)

{
  "respCode": 2000,
  "respMessage": "Transaction status fetched successfully",
  "data": "0oA+t8GGuDZ0FrEbhM9bZ2pxTDZTaHRWRW1tQnN0dWUxVC92Yi9WQW9SSFdlTk56Ri9EYmVWTmVGNTF1R3FVSnFRVWJUaFpqbTk4RTZrandTa25ke"
}

Decrypted Response Data

{
  "senderId": "SENDERID00001",
  "txnId": "CFCE160825000001",
  "requestAmount": "100.00",
  "paymentMode": "Intent",
  "utr": "405812345678",
  "remarks": "test",
  "status": "SUCCESS",
  "statusMessage": "Payment completed successfully",
  "createdAt": "2025-08-16T07:46:45.277Z",
  "updatedAt": "2025-08-16T08:18:15.378Z"
}

Response Fields

Field	Description
senderId	Merchant provided unique sender ID
txnId	Paywize generated unique transaction ID
requestAmount	Payment amount requested
paymentMode	Payment method used (Intent, etc.)
utr	Unique Transaction Reference from bank
remarks	Payment remarks/description
status	Current transaction status
statusMessage	Detailed status description
createdAt	Transaction creation timestamp
updatedAt	Last update timestamp

Transaction Status Values

Status	Description
INITIATED	Payment request created, awaiting customer action
SUCCESS	Payment completed successfully
FAILED	Payment failed
PENDING	Payment under review

Error Responses

Code	Message	Description
2000	Transaction status fetched successfully	Success
4000	Either Transaction ID (txnId) or Sender ID (senderId) is required	Missing required parameter
4008	Unauthorized – invalid or expired token	Token is invalid or expired
4104	Transaction not found	Transaction does not exist
4103	Provide either senderId or txnId. Not both.	Both parameters provided
4105	Missing or invalid txnId format	Invalid txnId format
4107	Unauthorized: Transaction does not belong to this merchant	Access denied
5000	Internal server error	Server error

Implementation Examples

JavaScript

import crypto from 'crypto';

// Decryption function
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 checkPaymentStatus(token, txnId = null, senderId = null, apiKey, secretKey) {
  // Validate parameters
  if (!txnId && !senderId) {
    throw new Error('Either txnId or senderId is required');
  }
  if (txnId && senderId) {
    throw new Error('Provide either txnId or senderId, not both');
  }

  // Build query parameter
  const queryParam = txnId ? `txnId=${txnId}` : `senderId=${senderId}`;
  const url = `https://merchant.paywize.in/api/collection/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.respCode === 2000) {
    // Decrypt the response data
    const decryptedData = decryptMerchantData(result.data, apiKey, secretKey);
    return JSON.parse(decryptedData);
  } else {
    throw new Error(`API Error ${result.respCode}: ${result.respMessage}`);
  }
}

// Usage examples
try {
  // Check by transaction ID
  const statusByTxnId = await checkPaymentStatus(jwtToken, 'CFCE140825000009', null, apiKey, secretKey);
  console.log('Status by txnId:', statusByTxnId);

  // Check by sender ID
  const statusBySenderId = await checkPaymentStatus(jwtToken, null, 'SENDERID000345', apiKey, secretKey);
  console.log('Status by senderId:', statusBySenderId);

} catch (error) {
  console.error('Status check failed:', error.message);
}

Python

import requests
import json
from encryption_utils import decrypt_merchant_data

def check_payment_status(token, api_key, secret_key, txn_id=None, sender_id=None):
    # Validate parameters
    if not txn_id and not sender_id:
        raise ValueError('Either txn_id or sender_id is required')
    if txn_id and sender_id:
        raise ValueError('Provide either txn_id or sender_id, not both')

    # Build query parameter
    query_param = f'txnId={txn_id}' if txn_id else f'senderId={sender_id}'
    url = f'https://merchant.paywize.in/api/collection/v1/status?{query_param}'

    response = requests.get(
        url,
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {token}'
        }
    )

    result = response.json()

    if result['respCode'] == 2000:
        # Decrypt the response data
        decrypted_data = decrypt_merchant_data(result['data'], api_key, secret_key)
        return json.loads(decrypted_data)
    else:
        raise Exception(f"API Error {result['respCode']}: {result['respMessage']}")

# Usage examples
try:
    # Check by transaction ID
    status_by_txn_id = check_payment_status(jwt_token, api_key, secret_key, txn_id='CFCE140825000009')
    print('Status by txnId:', status_by_txn_id)

    # Check by sender ID
    status_by_sender_id = check_payment_status(jwt_token, api_key, secret_key, sender_id='SENDERID000345')
    print('Status by senderId:', status_by_sender_id)

except Exception as error:
    print('Status check failed:', str(error))

PHP

<?php

require_once 'PaywizeEncryption.php';

function checkPaymentStatus($token, $apiKey, $secretKey, $txnId = null, $senderId = null) {
    // Validate parameters
    if (!$txnId && !$senderId) {
        throw new InvalidArgumentException('Either txnId or senderId is required');
    }
    if ($txnId && $senderId) {
        throw new InvalidArgumentException('Provide either txnId or senderId, not both');
    }

    // Build query parameter
    $queryParam = $txnId ? "txnId=$txnId" : "senderId=$senderId";
    $url = "https://merchant.paywize.in/api/collection/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['respCode'] == 2000) {
        // Decrypt the response data
        $decryptedData = PaywizeEncryption::decryptMerchantData($result['data'], $apiKey, $secretKey);
        return json_decode($decryptedData, true);
    } else {
        throw new Exception("API Error {$result['respCode']}: {$result['respMessage']}");
    }
}

// Usage examples
try {
    // Check by transaction ID
    $statusByTxnId = checkPaymentStatus($jwtToken, $apiKey, $secretKey, 'CFCE140825000009');
    echo "Status by txnId: " . json_encode($statusByTxnId) . "\n";

    // Check by sender ID
    $statusBySenderId = checkPaymentStatus($jwtToken, $apiKey, $secretKey, null, 'SENDERID000345');
    echo "Status by senderId: " . 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/collection/v1/status?txnId=CFCE140825000009" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Check status by sender ID
curl -X GET "https://merchant.paywize.in/api/collection/v1/status?senderId=SENDERID000345" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Best Practices

Parameter Validation: Always validate that either txnId or senderId 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

Webhook Alternative

Instead of polling for status updates, consider implementing webhooks for real-time notifications: Learn about Webhooks →

Next Steps

Implement Webhooks for real-time updates
Learn about Authentication
Learn about Encryption
View Collection API Overview

PreviousInitiate Payment

NextWebhooks