Payout V2

This a collection of API's used for Payout V2.

Initialize Transaction

POST https://dashboard.finzen.money/api/v2/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"
    }
}

Before creating a payout, you must first create a beneficiary and wait up to 24 hours for it to be "Active." Once approved, the beneficiary will be ready for use.

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

Create Beneficiary

POST https://dashboard.finzen.money/api/v1/public/beneficiary/create

Name	Type	Description
transfer_type*	String	Transfer Type, For now use BANK
beneficiary_name*	String	The beneficiary name to be added.
beneficiary_email*	String	The beneficiary email to be added.
beneficiary_mobile*	String	The beneficiary mobile number to be added.
account_number*	String	The beneficiary Account Number
ifsc_code*	String	The beneficiary IFSC code

200 Beneficiary added successfully

{
    "success": true,
    "http_code": 200,
    "message": "Beneficiary added successfully",
    "data": {
        "beneficiary_id": "31136943520894742991"
    }
}

401 Unauthorized

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

Note:- After Creating a beneficiary it take up to 24 hours to be "Active".

Get Beneficiary

POST https://dashboard.finzen.money/api/v1/public/beneficiary/get

Name	Type	Description
beneficiary_id	String	The id generated when a beneficiary is created (If beneficiary_id is available Then beneficiary_name and account_number are not required)
beneficiary_name	String	The beneficiary name added ( If beneficiary_id not available )
account_number	String	The beneficiary account number added ( If beneficiary_id not available )

200 Beneficiary details retrieved successfully

{
    "success": true,
    "http_code": 200,
    "message": "Beneficiary details retrieved successfully",
    "data": {
        "bene_id": "68660837276775201234",
        "email_id": "[e-mail]",
        "bene_name": "ABC XYZ",
        "bene_email": "[e-mail]",
        "bene_mobile_no": "9898989898",
        "bank_name": "STATE BANK OF INDIA",
        "bank_account_number": "00123456898",
        "ifsc_code": "SBIN0001234",
        "vpa_address": null,
        "status": "Pending",
        "timestamp": "20/09/2024 04:24:05 PM"
    }
}

400 Bad Request

{
    "success": false,
    "http_code": 400,
    "message": "Beneficiary not found in system using provided details"
}

Note:- Initially, the beneficiary status is "Pending," and after approval, it changes to "Active."

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