Fund Transfer APIs

Fund Transfer API Document v1.0

Introduction

Payout Fintech API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request and returns response, and uses standard HTTP response codes, authentication, and verbs.

You can use our API in the sandbox and production environment. We provide two different API urls and tokens for sandbox and production(Live).

Pass API token and content-type for all the requests in header, token will be shared to you in an email.

  • content-type: application/json
  • authorization: Bearer <Token>

HTTP Status Code

Always check the HTTP status code, for successful requests we return HTTP status as 200, incase of any error in request we return the HTTP status as 400, assume if you are receiving 400 the request is not accepted.

Available Balance API

Get the current available balance from the Payout Fintech Payout account.

  • URL: /balance
  • Method: GET

Request

N/A

Response

Parameters Datatype Description
availableBalance number Returns the available balance

Example

Request

N/A

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"availableBalance" :   7015773.70

}

}

Fund Transfer API

Initiate the fund transfer to the given account number.

  • URL: /transfer
  • Method: POST

Request

Parameters Range Datatype Required Description
requestId Max 36 string Y Unique identifier to identify request, it should be unique to avoid duplicate transactions
beneficiaryName Max 35 string Y Beneficiary name.Regular expression:[a-zA-Z0-9_-., ]
accountNo Max 30 string Y Beneficiary account number
ifscCode Exact 11 characters string Y Beneficiary ifsc code
amount Minimum 1 number Y Amount to be transferred, Minimum and maximum amount vary by mode IMPS - Min 1 & Max 5,00,000 NEFT - Min 1 & Max 250,000,000 RTGS - Min 2,00,000 & Max 250,000,000
mode IMPS/NEFT/RTGS string Y Only the three modes allowed
purpose Max 25 string Y Purpose of the fund transfer. E.g payout, refund,reward, etc…

Response

Parameters Datatype Description
requestId string Returns the request value
referenceNo string Reference number generated for the transaction.
beneficiaryName string Returns the request value
accountNo string Returns the request value
ifscCode string Returns the request value
amount number Returns the request value
fee number Returns the fee for the payout
tax number Returns the tax for the fee
totalFee number Returns the sum of fee and tax
mode string Returns the request value
purpose string Returns the request value

Example

Success Case

Request

{

   "requestId" :   "pfin202008260002",

   "beneficiaryName" :   "Demo Company",

   "accountNo" :   "900900900900",

   "ifscCode" :   "UTIB0002951",

   "amount" :   5000,

   "mode" :   "IMPS",

   "purpose" :   "Payout"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "pfin202008260002",

"referenceNo" :   "PFBAgMlRcOO8nC86ccMj8awdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900900",

"ifscCode" :   "UTIB0002951",

"amount" :   5000,

"fee" :   3.50,

"tax" :   0.63,

"totalFee" :   4.13,

"mode" :   "IMPS",

"purpose" :   "Payout"

}

}

Failure Case

Insufficient balance Response

{

   "code" :   400,

   "errorCode" :   5060,

   "message" :   "Insufficient balance"

}

Other Common validation Response

{

   "code" :   400,

   "errorCode" :   5001,

   "message" :   "accountNo is required"

}

Fund Transfer Status API

Get the fund transfer status by requestId.

  • URL: /status/{requestId}
  • Method: GET

Request

N/A

Response

Parameters Datatype Description
requestId string Unique value to identify the fund transfer request
beneficiaryName string Returns the beneficiaryName for the requestId
accountNo string Returns the accountNo for the requestId
ifscCode string Returns the ifscCode for the requestId
amount number Returns the amount for the requestId
mode string Returns the mode for the requestId
purpose string Returns the purpose for the requestId
utrNumber string Unique transaction reference number returned by bank for the fund transfer
referenceNo string Reference number generated for the fund transfer.
statusCode string Returns the fund transfer statusCode
status string Returns the fund transfer status, such as initiated, success and failure.
errorDescription string Returns error description for the FAILURE/ ERROR / RETURNED_FROM_BENEFICIARY statuses Empty for other statuses

Example

Response - SUCCESS

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "pfin202008260002",

"referenceNo" :   "PFBAgMlRcOO8nC86ccMj8awdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900900",

"ifscCode" :   "UTIB0002951",

"amount" :   5000,

"fee" :   3.50,

"tax" :   0.63,

"totalFee" :   4.13,

"mode" :   "IMPS",

"purpose" :   "Payout",

"utrNumber" :   "CB0001997620",

"statusCode" :   "SUCCESS",

"status" :   "Success",

"errorDescription" :   ""

}

}

Response - FAILURE

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "pfin202008260003",

"referenceNo" :   "PFBAgMlRcOO8nC86ccMj8bwdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900900",

"ifscCode" :   "UTIB0002952",

"amount" :   3000,

"fee" :   10,

"tax" :   1.8,

"totalFee" :   11.8,

"mode" :   "IMPS",

"purpose" :   "Payout",

"utrNumber" :   " ",

"statusCode" :   "RETURNED_FROM_BENEFICIARY",

"status" :   "Returned from beneficiary",

"errorDescription" :   "RETURN - ACCOUNT CLOSED"

}

}

Fund Transfer Status List

status_code Status Meaning
READY ready In queue not yet initiated
INITIATED initiated Payment Initiated
FAILURE failure Fund transfer failed
ERROR error Fund transfer error
SUCCESS success Fund transfer completed successfully
PENDING pending Temporary status, it may change
INSUFFICIENT_BALANCE Insufficient balance Unable to process the transaction due to Insufficient balance
RETURNED_FROM_BENEFICIARY Returned from beneficiary Amount returned from beneficiary
OTHER Other Miscellaneous status, usually it does not occur

Note: Failure, Success,Insufficient balance and returned from beneficiary are final statuses.

Fund Transfer Webhook

Our system will call your webhook url and post the payment status when payment is transferred. In case your webhook does not respond, our system will call your url for maximum four times in a 15 minutes interval if all four attempts failed, you will receive email notification about the issue.

Payment Success Case

Parameters Datatype Description
tranType string Returns DEBIT / CREDIT / RECREDIT For fund transfer status DEBIT - For every debit transaction CREDIT - For every credit transaction, After loading funds via virtual account, RECREDIT - For every failure transaction after the re-credit, recredit webhook will fire
requestId string Unique value to identify the fund transfer request
referenceNo string Reference number generated for the fund transfer.
beneficiaryName string Returns the beneficiaryName for the requestId
accountNo string Returns the accountNo for the requestId
ifscCode string Returns the ifscCode for the requestId
amount number Returns the amount for the requestId
fee number Fee for the transaction
tax number Tax for the transaction fee
totalFee number Sum of fee and tax
mode string Returns the mode for the requestId
purpose string Returns the purpose for the requestId
utrNumber string Unique transaction reference number returned by bank for the fund transfer
statusCode string Returns the fund transfer statusCode as SUCCESS
status string Returns the fund transfer status as Success
errorDescription string N/A
attemptCount number Number of times the webhook invoked

Payment Non Success Case

Parameters Datatype Description
tranType string Returns DEBIT / CREDIT / RECREDIT For fund transfer status DEBIT - For every debit transaction CREDIT - For every credit transaction, After loading funds via virtual account, RECREDIT - For every failure transaction after the re-credit, recredit webhook will fire
requestId string Unique value to identify the fund transfer request
referenceNo string Reference number generated for the fund transfer.
beneficiaryName string Returns the beneficiaryName for the requestId
accountNo string Returns the accountNo for the requestId
ifscCode string Returns the ifscCode for the requestId
amount number Returns the amount for the requestId
fee number Fee for the transaction
tax number Tax for the transaction fee
totalFee number Sum of fee and tax
mode string Returns the mode for the requestId
purpose string Returns the purpose for the requestId
utrNumber string Unique transaction reference number returned by bank for the fund transfer
statusCode string Returns the fund transfer statusCode FAILURE/ ERROR / RETURNED_FROM_BENEFICIARY
status string Returns the fund transfer status, such as failure error,returned_from_beneficiary.
errorDescription string Returns error description
attemptCount number Number of times the webhook invoked

Example 1

Success Case

Request

    {  

"tranType" :   "DEBIT",

"requestId" :   "pfin202008260002",

"referenceNo" :   "PFBAgMlRcOO8nC86ccMj8awdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900900",

"ifscCode" :   "UTIB0002951",

"amount" :   5000,

"fee" :   3.5,

"tax" :   0.63,

"totalFee" :   4.13,

"mode" :   "IMPS",

"purpose" :   "Payout",

"utrNumber" :   "CB0001997620",

"statusCode" :   "SUCCESS",

"status" :   "Success",

"errorDescription" :   "",

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

Example 2

Failure Case

Request

    {  

"tranType" :   "DEBIT",

"requestId" :   "pfin202008260005",

"referenceNo" :   "PFBAgMlRcOO8nC86cdMj8awdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900901",

"ifscCode" :   "UTIB0002953",

"amount" :   5000,

"fee" :   3.5,

"tax" :   0.63,

"totalFee" :   4.13,

"mode" :   "IMPS",

"purpose" :   "payout",

"utrNumber" :   "CB0001987620",

"statusCode" :   "FAILURE",

"status" :   "Failure",

"errorDescription" :   "REJECTED - Incorrect beneficiary account detail",

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

Example 3

Credit case

Optional call back, notified after fund loaded to account via virtual account

Request

    {  

"tranType" :   "CREDIT",

"requestId" :   "DEPTf559961bff3f96960bd125906b5970b6",

"referenceNo" :   "DEPTf559961bff3f96960bd125906b5970b6",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900901",

"ifscCode" :   "UTIB0002953",

"amount" :   5000,

"fee" :   0,

"tax" :   0,

"totalFee" :   0,

"mode" :   "IMPS",

"purpose" :   "Bank Transfer",

"utrNumber" :   "CB0001987621",

"statusCode" :   "SUCCESS",

"status" :   "Success",

"errorDescription" :   "",

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

Example 4

Recredit Case

Optional call back notified after the amount re-credited for the failure transaction

Request

    {  

"tranType" :   "RECREDIT",

"requestId" :   "pfin202008260005",

"referenceNo" :   "PFBAgMlRcOO8nC86cdMj8awdL92eqR",

"beneficiaryName" :   "Demo Company",

"accountNo" :   "900900900901",

"ifscCode" :   "UTIB0002953",

"amount" :   5000,

"fee" :   0,

"tax" :   0,

"totalFee" :   0,

"mode" :   "NEFT",

"purpose" :   "Recredit",

"utrNumber" :   "REV-CB0001987621",

"statusCode" :   "SUCCESS",

"status" :   "Success",

"errorDescription" :   "",

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

API Success and Error Messages

Http Status Code

200 - Success

400 - Error

Sample Error Response

     {

      "code" :   400,

      "errorCode" :   5002,

      "message" :   "requestId already exists. Duplicate not allowed"

    }

Possible Errors

Common Validation Error

Error code 5001 is same for all validation errors

Error Messages
requestId is mandatory
requestId maximum length should not exceed 36 characters
beneficiaryName is mandatory
beneficiaryName maximum length should not exceed 35 characters
beneficiaryName should contains only [a-zA-Z0-9_-., ] character sets
accountNo is mandatory
accountNo maximum length should not exceed 30 characters
ifscCode is mandatory
ifscCode format is invalid
amount is mandatory
amount should not be less than INR 1
mode is mandatory
mode is invalid, mode should be IMPS / NEFT / RTGS
purpose is mandatory
purpose length should not be more than 25
Other Possible Errors
Error Codes Error Messages
5002 requestId already exists. Duplicate not allowed
5004 requestId not found
5011 Payout not allowed to nodal account
5012

The bank does not exist so payments to this IFSC code is not allowed.

For the following IFSC Codes payment is not allowed as per RBI notice, because the banks merged with some other banks.

ANDB0,ALLA0,ORBC0,UTBI0,CORP0,SYNB0,VIJB0,BKDN0
5013 Payout is not allowed to this account due to your black list policy
5033 For IMPS amount should be less than or equal to 500000.
5034 For RTGS amount should be greater than 200000
5035 Your maximum per transaction limit is 9,90,000 as per your account policy. Amount should not exceed the maximum per transaction limit
5060 Insufficient balance

Postman Collection

Login to your Sandbox / Production environment and Fund Transfer API Postman Collection download from the dashboard.