Payout V1

This a collection of API's used for Payout.

Initialize Transaction

POST https://dashboard.finzen.money/api/v1/public/payment/transfer

Initialize new transaction (Payout) to beneficiary

Headers

Name	Type	Description
x-merchant-email*	String	Registered merchant email
x-api-key*	String	API Key, Can be generated from dashboard
x-api-secret*	String	API Secret, Can be generated from dashboard

Request Body

Name	Type	Description
client_ref_id*	String (5, 30)	Unique client ref id for transaction identification at client side
transfer_type*	String	Transfer Type, For now use BANK
amount*	Double	Transaction amount in rupees, up to 2 decimal places is allowed
payment_method*	String	Use one of the below code: 1001 -> For IMPS 1002 -> For NEFT 1003 -> For RTGS
debit_from*	String (20, 20)	Request to pass the VAN account number you want to debit from
beneficiary_id	String (20, 20)	If you have created a beneficiary before then pass beneficiary ID
beneficiary_email	String	Required in case of beneficiary ID is not provided and transfer type is BANK, String should be a valid email address
beneficiary_mobile	String (10, 10)	Optional
beneficiary_name	String	Required in case of beneficiary ID is not provided and transfer type is BANK, Only alphanumeric value is allowed
account_number	String	Required in case of beneficiary ID is not provided and transfer type is BANK
ifsc_code	String	Required in case of beneficiary ID is not provided and transfer type is BANK
purpose*	String	Use any of the following: CASHBACK, REWARDS, VENDOR_PAYOUT, SALARY
remarks*	String (1, 50)	Any remarks

200 Transaction initiated successfully

{
    "success": true,
    "http_code": 200,
    "message": "Transaction is pending, kindly check the status of this transaction after some time",
    "data": {
        "ref_id": "6167942537",
        "client_ref_id": "12314545100",
        "status": "Pending"
    }
}

401 Unauthorized

{
    "success": false,
    "http_code": 401,
    "message": "API Credentials is not valid"
}

400: Bad Request

{
    "status": false,
    "message": "Duplicate Client Reference ID",
    "error": {
        "code": "GENERIC_EXCEPTION",
        "message": "Duplicate Client Reference ID"
    }
}

Transaction Status Check

GET https://dashboard.finzen.money/api/v1/public/payment/transfer/status

Check status of transaction using client reference id or finzen transaction reference id

Headers

Name	Type	Description
x-merchant-email*	String	Registered merchant email
x-api-key*	String	API Key, Can be generated from dashboard
x-api-secret*	String	API Secret, Can be generated from dashboard

Request Body

Name	Type	Description
client_ref_id	String (5, 30)	Client Ref ID used for initiating transaction, Required if ref_id is not provided
ref_id	String (10, 10)	Transaction Ref ID generated after initialization of transaction, Required if client_ref_id is not provided

200 Transaction Status retrieved

{
    "success": true,
    "http_code": 200,
    "message": "This transaction has been processed successfully",
    "data": {
        "transaction": {
            "ref_id": 7576506414,
            "client_ref_id": "12314545100",
            "purpose": "CASHBACK",
            "amount": 5,
            "fees": 2,
            "tax": 0.36,
            "type": "Debit",
            "status": "Success",
            "payment_method": "1001",
            "bank_ref_number": "403926206668",
            "bank_res_msg": "",
            "beneficiary": {
                "id": "37533781978632548982",
                "name": "Xya Abc",
                "email_id": "[e-mail]",
                "mobile_no": "9898989898"
            },
            "transaction_date": "2024-02-08 17:30:22",
            "created_at": "08/02/2024 05:30:22 PM"
        }
    }
}

401: Unauthorized

{
    "success": false,
    "http_code": 401,
    "message": "API Credentials is not valid"
}

429: Too Many Requests

{
    "success": false,
    "http_code": 429,
    "message": "Too Many Attempts."
}

500: Internal Server Error

{
    "status": false,
    "message": "Unable to find transaction using provided ID",
    "error": {
        "code": "GENERIC_EXCEPTION",
        "message": "Unable to find transaction using provided ID"
    }
}

400 Bad Request

{
    "success": false,
    "http_code": 400,
    "message": "The ref id field is required when client ref id is not present."
}

Rate Limite: 3 calls per minute per transaction for the Status Check API

Balance Check

GET https://dashboard.finzen.money/api/v1/public/balance/check?account_no=00016459824780000

Headers

Name	Type	Description
x-merchant-email*	String	Registered merchant email
x-api-key*	String	API Key, Can be generated from dashboard
x-api-secret*	String	API Secret, Can be generated from dashboard

Query Params

Name	Type	Description
account_no*	String	Check the balance of the account number you passed

200 Balance retrieved successfully

{
    "success": true,
    "http_code": 200,
    "message": "Balance retrieved successfully",
    "data": {
        "current_balance": 15.83
    }
}

401 Unauthorized

{
    "success": false,
    "http_code": 401,
    "message": "API Credentials is not valid"
}

Rate Limite: 10 calls per minute per account for balance checks

WebHook Sample Request

{
    "success": true,
    "http_code": 200,
    "message": "This transaction has been processed successfully",
    "data": {
        "transaction": {
            "ref_id": 7576506414,
            "client_ref_id": "12314545100",
            "purpose": "CASHBACK",
            "amount": 5,
            "fees": 2,
            "tax": 0.36,
            "type": "Debit",
            "status": "Success",
            "payment_method": "1001",
            "bank_ref_number": "403926206668",
            "bank_res_msg": "",
            "beneficiary": {
                "id": "37533781978632548982",
                "name": "Xya Abc",
                "email_id": "[e-mail]",
                "mobile_no": "9898989898"
            },
            "transaction_date": "2024-02-08 17:30:22",
            "created_at": "08/02/2024 05:30:22 PM"
        }
    }
}

Error Codes

Code	Message
TRANSACTION_LIMIT_EXCEEDED	Allowed per transaction limit exceeded, please try initiating transaction with smaller amount
INSUFFICIENT_BALANCE	Your account does not have sufficient balance to perform this transaction
ACCOUNT_NOT_ACTIVE	Your account is not active and hance can’t perform real transactions
TRANSACTION_AMOUNT_NOT_COMPATIBLE_WITH_PAYMENT_MODE	Transaction amount is not within the allowed limit for requested payment method, ie. For 1001 (IMPS) amount should be between 1 to 200000.
INVALID_BENEFICIARY	Provided beneficiary does not have a valid account detail to perform this transaction
INVALID_TRANSFER_ID	Provided transfer ID is not valid
GENERIC_EXCEPTION	This is the generic exception code, error message should have more details regarding the exception or you can reach out to [e-mail] if this error persist