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

Transaction Status

Status	Description
Success	Payment has been processed successfully
Failed	Payment has been failed due to any reason
Pending	Payment has been processed by Finzen but awaiting status from bank, Please retry status check after some interval
NEW	Payment is still not processed by Finzen, Please retry status check after some interval
Unknown	Payment status is not clear and is marked for reconciliation, Please retry status check after some interval

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

{
    "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