Validate Threshold

Validates user threshold limits and usage for transactions to determine if a transaction is allowed based on wallet balances, threshold master limits, and threshold detail limits.

Basic Information

Method: POST
URL: https://api.gafapay.com:8443/gafapay/v3/transaction/validate_threshold
Content-Type: application/json
companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: 5bb30135-1815-41d5-827f-baed3daba4af
Authorization: Token required

Headers

companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: 5bb30135-1815-41d5-827f-baed3daba4af
authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlNDk0Njg3N2YxODk0NmIyOTlmZGRmMGYyMTMzZGNiYSIsInJvbGVzIjpbIlJPTEVfQURNSU4iXSwiZXhwIjoxNzU5NjQ2NTU5fQ.NoUhIlH54d-1UbvNzxl5tUKqnqZq2-uH-7Q_XJ86Oug
Content-Type: application/json

Request Body

{
    "product_code": "P2P",
    "sender_user_id": "e72810252c034a278a433eb0535b7ead",
    "receiver_user_id": "f83910252c034a278a433eb0535b7ead",
    "txn_amount": 1000.0,
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "wallet_id": "w1234567890abcdef1234567890abcdef"
}

Request Parameters

product_code (string, required): Product code for the transaction
- Example: P2P, IWT, P2M, M2M, etc.
sender_user_id (string, required): User ID of the transaction sender
receiver_user_id (string, required): User ID of the transaction receiver
txn_amount (number, required): Transaction amount (must be greater than 0)
currency_id (string, required): Currency identifier for the transaction
wallet_id (string, required): Wallet identifier for the transaction

cURL Request

curl --location --request POST 'https://api.gafapay.com:8443/gafapay/v3/transaction/validate_threshold' \
--header 'authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlNDk0Njg3N2YxODk0NmIyOTlmZGRmMGYyMTMzZGNiYSIsInJvbGVzIjpbIlJPTEVfQURNSU4iXSwiZXhwIjoxNzU5NjQ2NTU5fQ.NoUhIlH54d-1UbvNzxl5tUKqnqZq2-uH-7Q_XJ86Oug' \
--header 'companyid: 59388167894b4d10a04fe5da3b8a2104' \
--header 'requestid: 5bb30135-1815-41d5-827f-baed3daba4af' \
--header 'Content-Type: application/json' \
--data '{
    "product_code": "P2P",
    "sender_user_id": "e72810252c034a278a433eb0535b7ead",
    "receiver_user_id": "f83910252c034a278a433eb0535b7ead",
    "txn_amount": 1000.0,
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "wallet_id": "w1234567890abcdef1234567890abcdef"
}'

Response

Success Response - Transaction Allowed

{
    "success": 1,
    "error": [],
    "data": {
        "is_transaction_allowed": true,
        "validation_message": "TRANSACTION_ALLOWED",
        "sender_balance": 50000.0,
        "receiver_balance": 25000.0,
        "sender_min_balance": 1000.0,
        "sender_max_balance": 1000000.0,
        "receiver_min_balance": 500.0,
        "receiver_max_balance": 500000.0,
        "daily_limit_remaining": 49000.0,
        "weekly_limit_remaining": 490000.0,
        "monthly_limit_remaining": 4990000.0,
        "daily_txn_limit_remaining": 49,
        "weekly_txn_limit_remaining": 199,
        "monthly_txn_limit_remaining": 999
    }
}

Response - Transaction Not Allowed (Insufficient Balance)

{
    "success": 1,
    "error": [],
    "data": {
        "is_transaction_allowed": false,
        "validation_message": "SENDER_INSUFFICIENT_BALANCE",
        "sender_balance": 500.0,
        "receiver_balance": 25000.0,
        "sender_min_balance": 1000.0,
        "sender_max_balance": 1000000.0,
        "receiver_min_balance": 500.0,
        "receiver_max_balance": 500000.0,
        "daily_limit_remaining": 49000.0,
        "weekly_limit_remaining": 490000.0,
        "monthly_limit_remaining": 4990000.0,
        "daily_txn_limit_remaining": 49,
        "weekly_txn_limit_remaining": 199,
        "monthly_txn_limit_remaining": 999
    }
}

Response - Transaction Not Allowed (Product Not Allowed)

{
    "success": 1,
    "error": [],
    "data": {
        "is_transaction_allowed": false,
        "validation_message": "PRODUCT_NOT_ALLOWED_FOR_SENDER",
        "sender_balance": 50000.0,
        "receiver_balance": 25000.0,
        "sender_min_balance": 1000.0,
        "sender_max_balance": 1000000.0,
        "receiver_min_balance": 500.0,
        "receiver_max_balance": 500000.0,
        "daily_limit_remaining": null,
        "weekly_limit_remaining": null,
        "monthly_limit_remaining": null,
        "daily_txn_limit_remaining": null,
        "weekly_txn_limit_remaining": null,
        "monthly_txn_limit_remaining": null
    }
}

Response - Transaction Not Allowed (Daily Limit Exceeded)

{
    "success": 1,
    "error": [],
    "data": {
        "is_transaction_allowed": false,
        "validation_message": "DAILY_AMOUNT_LIMIT_EXCEEDED",
        "sender_balance": 50000.0,
        "receiver_balance": 25000.0,
        "sender_min_balance": 1000.0,
        "sender_max_balance": 1000000.0,
        "receiver_min_balance": 500.0,
        "receiver_max_balance": 500000.0,
        "daily_limit_remaining": 500.0,
        "weekly_limit_remaining": 490000.0,
        "monthly_limit_remaining": 4990000.0,
        "daily_txn_limit_remaining": 49,
        "weekly_txn_limit_remaining": 199,
        "monthly_txn_limit_remaining": 999
    }
}

Error Response - Validation Failed (Bad Request)

{
    "success": 0,
    "error": ["BAD_REQUEST"],
    "data": {}
}

Response Fields

success (integer): Response status indicator
- 1 = Success
- 0 = Failure
error (array): Array of error messages (empty on success)
data (object): Response data object
- is_transaction_allowed (boolean): Whether the transaction is allowed
- validation_message (string): Detailed validation message
- sender_balance (number): Current sender wallet balance
- receiver_balance (number): Current receiver wallet balance
- sender_min_balance (number): Sender minimum balance limit
- sender_max_balance (number): Sender maximum balance limit
- receiver_min_balance (number): Receiver minimum balance limit
- receiver_max_balance (number): Receiver maximum balance limit
- daily_limit_remaining (number): Remaining daily amount limit
- weekly_limit_remaining (number): Remaining weekly amount limit
- monthly_limit_remaining (number): Remaining monthly amount limit
- daily_txn_limit_remaining (integer): Remaining daily transaction count limit
- weekly_txn_limit_remaining (integer): Remaining weekly transaction count limit
- monthly_txn_limit_remaining (integer): Remaining monthly transaction count limit

Additional Examples

Validate P2P Transfer

curl --location --request POST 'https://api.gafapay.com:8443/gafapay/v3/transaction/validate_threshold' \
--header 'authorization: Token YOUR_TOKEN' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "product_code": "P2P",
    "sender_user_id": "user123",
    "receiver_user_id": "user456",
    "txn_amount": 500.0,
    "currency_id": "currency123",
    "wallet_id": "wallet123"
}'

Validate Merchant Payment

curl --location --request POST 'https://api.gafapay.com:8443/gafapay/v3/transaction/validate_threshold' \
--header 'authorization: Token YOUR_TOKEN' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "product_code": "P2M",
    "sender_user_id": "customer123",
    "receiver_user_id": "merchant456",
    "txn_amount": 2500.0,
    "currency_id": "currency123",
    "wallet_id": "wallet123"
}'

Validation Logic

The API performs comprehensive validation checks:

Wallet Balance Validation:
- Fetches user wallets for both sender and receiver
- For sender: Checks if balance after transaction (current - txn_amount) meets minimum balance requirement
- For receiver: Checks if balance after transaction (current + txn_amount) doesn't exceed maximum balance requirement
Threshold Master Validation:
- Fetches user_threshold_master for both users based on currency_id and user_id
- Validates min_balance and max_balance limits
Threshold Detail Validation:
- Fetches user_threshold_detail for sender based on product_code, user_id, and currency_id
- If not found, returns "PRODUCT_NOT_ALLOWED"
- Validates threshold limits and current usage against transaction amount
Usage Tracking:
- Checks daily, weekly, and monthly limits for both amount and transaction count
- Calculates remaining limits after the proposed transaction

Validation Messages

When is_transaction_allowed is false, the validation_message field will contain one of these messages:

Wallet Balance Messages:

SENDER_WALLET_NOT_FOUND - Sender wallet not found
RECEIVER_WALLET_NOT_FOUND - Receiver wallet not found
SENDER_INSUFFICIENT_BALANCE - Sender doesn't have enough balance for the transaction
SENDER_BALANCE_WILL_BE_BELOW_MINIMUM_AFTER_TRANSACTION - Transaction would violate sender's minimum balance
SENDER_BALANCE_EXCEEDS_MAXIMUM - Sender's current balance exceeds maximum
RECEIVER_BALANCE_WILL_EXCEED_MAXIMUM_AFTER_TRANSACTION - Transaction would violate receiver's maximum balance
RECEIVER_BALANCE_BELOW_MINIMUM - Receiver's current balance is below minimum

Threshold Master Messages:

SENDER_THRESHOLD_MASTER_NOT_FOUND - Sender threshold master configuration not found
RECEIVER_THRESHOLD_MASTER_NOT_FOUND - Receiver threshold master configuration not found

Threshold Detail Messages:

PRODUCT_NOT_ALLOWED_FOR_SENDER - Product code not allowed for sender
TRANSACTION_AMOUNT_BELOW_MINIMUM - Transaction amount below minimum allowed
TRANSACTION_AMOUNT_EXCEEDS_MAXIMUM - Transaction amount exceeds maximum allowed
DAILY_AMOUNT_LIMIT_EXCEEDED - Transaction exceeds daily amount limit
WEEKLY_AMOUNT_LIMIT_EXCEEDED - Transaction exceeds weekly amount limit
MONTHLY_AMOUNT_LIMIT_EXCEEDED - Transaction exceeds monthly amount limit
DAILY_TXN_LIMIT_EXCEEDED - Transaction exceeds daily transaction count limit
WEEKLY_TXN_LIMIT_EXCEEDED - Transaction exceeds weekly transaction count limit
MONTHLY_TXN_LIMIT_EXCEEDED - Transaction exceeds monthly transaction count limit

Success Message:

TRANSACTION_ALLOWED - All validations passed, transaction is allowed

Error Messages (when success = 0):

BAD_REQUEST - Invalid request parameters
THRESHOLD_VALIDATION_ERROR - System error during validation

Notes

Response Structure: The API always returns success: 1 with data object, even when transaction is not allowed
Transaction Decision: Check is_transaction_allowed field to determine if transaction is permitted
Comprehensive Validation: The API checks all relevant threshold limits and wallet balances
Real-time Calculation: Balances are calculated as they would be after the transaction
Product-specific Limits: Each product code can have different threshold configurations
Usage Tracking: Current usage is tracked against daily, weekly, and monthly limits
Balance Projection: For sender, balance is calculated as (current - txn_amount); for receiver, (current + txn_amount)
Required Fields: All request parameters are mandatory
Amount Validation: Transaction amount must be greater than 0
Company Access: Only validates thresholds for users within the authenticated user's company
Detailed Response: Even when transaction is not allowed, response includes all balance and limit information
Error Handling: Only returns success: 0 for system errors or invalid requests, not for threshold violations

Basic Information​

Headers​

Request Body​

Request Parameters​

cURL Request​

Response​

Success Response - Transaction Allowed​

Response - Transaction Not Allowed (Insufficient Balance)​

Response - Transaction Not Allowed (Product Not Allowed)​

Response - Transaction Not Allowed (Daily Limit Exceeded)​

Error Response - Validation Failed (Bad Request)​

Response Fields​

Additional Examples​

Validate P2P Transfer​

Validate Merchant Payment​

Validation Logic​

Validation Messages​

Notes​