API Reference

Create Payout

Payout endpoint allows merchants to make a payout to their customers through UPI or IMPS payment methods.

Endpoint URL:

https://pg.nippy.co.in/api/payout/

HTTP Method:

POST

HTTP Headers:

Authorization: Bearer <access_token>
Content-Type: application/json
Request Body:

  • mid: (integer) The ID of the merchant making the payout.
  • paymentMethod: (string) The payment method to be used for the payout. Valid values are UPI and IMPS.
  • beneficiaryUPI: (string) The UPI ID of the beneficiary (required for UPI payment method).
  • amount: (float) The amount to be paid out.
  • remark: (string) A remark or note to be included with the payout.
  • beneficiaryBankACNumber: (string) The bank account number of the beneficiary (required for IMPS payment method).
  • beneficiaryBankIFSC: (string) The IFSC code of the beneficiary's bank (required for IMPS payment method).
  • udf1 : (string) User-defined field

Transaction Statuses

Here is a list of the transaction statuses:

  • failed: The transaction has failed due to an error or an issue with the payment method.
  • accept: The transaction has been accepted but is still being processed.
  • rejected: The transaction has been rejected due to invalid or insufficient information provided.
  • success: The transaction has been completed successfully.
  • pending: The transaction is still being processed and the final status is not yet determined.
  • reversed: The transaction has been reversed or refunded.

Please note that the actual status values might differ based on your implementation. Adjust the documentation accordingly if necessary.

UDF1: User Defined Field 1

UDF1 (User Defined Field 1) is a customizable field in a software application, API, or database schema, which allows users or developers to store additional information specific to their use case. This field provides the flexibility to add extra data or metadata that is not covered by the predefined fields in a system.

Usage

UDF1 can be used in various scenarios, such as:

Adding custom metadata to transactions, like a project name, department name, or any other relevant context.
Storing a custom identifier or reference that links the transaction to an external system.
Saving any additional information that may be required for reporting, auditing, or compliance purposes.

Sample Request Body for UPI Payment Method:

{
    "mid": 3,
    "paymentMethod": "UPI",
    "udf1":"324382784923",
    "beneficiaryUPI": "fahadnasar579@okaxis",
    "amount": 10342.1,
    "remark": "fahad"
}

Sample Request Body for IMPS Payment Method:

{  
    "mid": 3,  
    "paymentMethod": "IMPS",  
    "udf1":"23478923423",
    "amount": 10.1,  
    "remark": "fahad",  
    "beneficiaryBankACNumber" : "8802091850",  
    "beneficiaryBankIFSC" : "KKBK0000677"  
}

Response Body:

  • status: (boolean) Whether the payout was successful or not.
  • lognumber: (string) The log number for the payout.
  • tranrefno: (string) The transaction reference number for the payout.
  • transactionId: (string) The transaction ID for the payout.
  • RRN: (string) The RRN number for the payout.

Sample Successful Response Body:

{
    "status": true,
    "txn_status": "success",
    "udf1":"23478923423",
    "lognumber": "QUICK_FUND_UPI289976567870",
    "tranrefno": "76019032050",
    "transactionId": "289976567870",
    "RRN": "310001795993"
}

Sample Error Response Body:

{
    "status": false,
    "txn_status": "rejected",
    "message": "Insufficient balance",
    "error_code": 400
}

Curl Example:

curl --location 'https://pg.nippy.co.in/api/payout/' \
--header 'Authorization: Bearer <AUTHTOKEN>' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=98ao23t0j3at0r85lt01r72rle' \
--data-raw '{
    "mid":2,
    "paymentMethod":"UPI", 
    "udf1":"234234823",
    "beneficiaryUPI":"fahadnasar579@okaxis",
    "amount":10.1,
    "remark":"fahad"
}'

In the above example, the Authorization header is used to pass the bearer token for authentication purposes. The Content-Type header is used to indicate that the request payload is in JSON format. The Cookie header is used to pass the session ID. The request payload contains the data required for performing the payout transaction.

Code Sample:

<?php

// Define the API URL
$url = 'https://pg.nippy.co.in/api/payout/';

// Define the request body
$data = array(
    "mid" => 2,
    "paymentMethod" => "UPI", // IMPS,UPI,NEFT,RTGS
    "beneficiaryUPI" => "fahadnasar579@okaxis",
    "udf1":"234234823", // unique order id or any user defined content 
    "amount" => 10.1,
    "remark" => "fahad",
    "beneficiaryBankACNumber" => "8802091850",
    "beneficiaryBankIFSC" => "KKBK0000677"
);

// Convert the request body to JSON
$json_data = json_encode($data);

$AUTHTOKEN= '';    // replace your auth token

// Define the headers
$headers = array(
    'Content-Type: application/json',
    'Authorization: Bearer ' . $AUTHTOKEN // replace your auth token
);

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_ENCODING, '');
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_TIMEOUT, 0);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

// Execute the cURL request and get the response
$response = curl_exec($curl);

// Check if there was an error
if(curl_errno($curl)) {
    echo 'Error: ' . curl_error($curl);
} else {
    // Get the HTTP status code
    $http_status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    
    // Close the cURL session
    curl_close($curl);

    // Check the response status code
    if($http_status_code == 200) {

     		 // Print the response
        echo $response;

        // Decode the JSON response
        $response_data = json_decode($response, true);

        // Print the desired values
        echo "lognumber: " . $response_data['lognumber'] . "\n";
        echo "txn_status: " . $response_data['txn_status'] . "\n"; //  current state of a transaction, such as whether it's pending, accepted, rejected, failed, successful, or reversed
        echo "udf1: " . $response_data['udf1'] . "\n";
        echo "tranrefno: " . $response_data['tranrefno'] . "\n";
        echo "transactionId: " . $response_data['transactionId'] . "\n";
        echo "RRN: " . $response_data['RRN'] . "\n";

    } else {
        // There was an error
        echo 'Error: ' . $http_status_code;
    }
}

Errors

If the API encounters any errors, it will return an appropriate HTTP status code and an error message in the response body. Some common error codes are:

Status StatusMessageDescription
400Bad RequestThe request was malformed or missing a parameter
401UnauthorizedThe authorization token was invalid or expired
500Internal Server ErrorAn error occurred while processing the request
200SuccessNo issue