UPI Payout APIs

UPI Payout API Document v1.0

Introduction

Payout Fintech API is organised 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.

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

}

}

UPI Payout API

Initiate the fund transfer to the given account number.

  • URL: /upitransfer
  • 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_-., ]
beneficiaryVPA Max 60 string Y

beneficiaryVPA (UPI handle)

Note: In the sandbox environment all the VPAs will return false except the following VPAs.

9664517972@axis

sheiksha@axis

shiva000@axis

9949858407@axis

Use the above VPAs for testing.
amount Minimum 1 number Y Amount should be less than or equal to 1,00,000
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
beneficiaryVPA 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" :   "out_73d13",

   "beneficiaryName" :   "Demo Company",

   "beneficiaryVPA" :   "sheiksha@axis",

   "amount" :   362.42,

   "purpose" :   "Payou Ref 202201890t"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "out_73d13",

"referenceNo" :   "PFUPsO7FRI5Wh96L08eadhJeBpfmIX",

"beneficiaryName" :   "Demo Company",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   362.42,

"fee" :   3,

"tax" :   0.54,

"totalFee" :   3.54,

"mode" :   "UPI",

"purpose" :   "Payout 202201890t"

}

}

Failure Case

Insufficient balance Response

{

   "code" :   400,

   "errorCode" :   5060,

   "message" :   "Insufficient balance"

}

Other Common validation Response

{

   "code" :   400,

   "errorCode" :   5001,

   "message" :   "beneficiaryVPA is required"

}

UPI Payout Status API

Get the fund transfer status by requestId.

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

Request

N/A

Response

Parameters Datatype Description
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
beneficiaryVPA string Returns the beneficiaryVPA for the requestId
amount number Returns the amount for the requestId
fee number Returns the fee for the upi payout
tax number Returns the tax for the fee
totalFee number Returns the 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
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
nameAtBank string Returns the account name from the beneficiary bank records for UPI VPA (based on availability)

Example

Response - SUCCESS

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "out_73d13",

"referenceNo" :   "PFUPsO7FRI5Wh96L08eadhJeBpfmIX",

"beneficiaryName" :   "Demo Company",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   362.42,

"fee" :   3,

"tax" :   0.54,

"totalFee" :   3.54,

"purpose" :   "Payout",

"utrNumber" :   "",

"mode" :   "UPI",

"statusCode" :   "PENDING",

"status" :   "Pending",

"errorDescription" :   ""

"nameAtBank" :   "sheiksha"

}

}

Response - FAILURE

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "out_73d15",

"referenceNo" :   "PFUPcEPkn8Ofh8kqHN1GQcUZHxejZP",

"beneficiaryName" :   "Demo Company",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   362.48,

"fee" :   3,

"tax" :   0.54,

"totalFee" :   3.54,

"mode" :   "UPI",

"purpose" :   "Payout",

"utrNumber" :   " ",

"statusCode" :   "FAILURE",

"status" :   "Failure",

"errorDescription" :   "N/A"

"nameAtBank" :   ""

}

}

UPI Payout 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.

UPI Verification / UPI VPA Verification

Verify if the UPI VPA / UPI handle exists and return the account name as per bank records if UPI VPA exists.

  • URL: /upivpa
  • 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. Beneficiary information is a mandatory field, merchant can pass what they have for the customer Regular expression: [a-zA-Z0-9_-., ]
beneficiaryVPA Max 60 string Y Customer VPA (UPI handle)

Response

Parameters Datatype Description
requestId string Returns the request value
referenceNo string Unique Reference number generated for the transaction by the Payout Fintech.
beneficiaryName string Returns the request value
beneficiaryVPA string Returns the request value

Example

Request

{

   "requestId" :   "30mar001",

   "beneficiaryName" :   "Sri Krishna",

   "beneficiaryVPA" :   "pftest1@axis"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "30mar001",

"referenceNo" :   "PFUVxBNJ2j8KcufJ5u0t",

"beneficiaryName" :   "Sri Krishna",

"beneficiaryVPA" :   "pftest1@axis"

}

}

UPI Verification Status API

Get the verification status of the UPI VPA by request Id, return actual name at bank and statusCode returns "SUCCESS" along with nameAtBank field if UPI VPA exist.

We recommend to compare the nameAtBank and beneficiaryName and decide. In case UPI VPA does not exist statusCode returns FAILURE along with errorDescription

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

GET Request

Merchant have to pass the requestId in the GET request as mentioned above.

Request Body

N/A

Response

Parameters Datatype Description
requestId string Returns the request value
referenceNo string Unique Reference number generated for the transaction by the Payout Fintech.
nameAtBank string Account name from the beneficiary bank records associated with UPI VPA
statusCode string Returns the statusCode
  • SUCCESS
  • FAILURE
errorDescription string Returns only for the failure case based on availability. Describe the reason for the error the description returned by bank. You can ignore and relay the statusCode

Example 1

Success Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "30mar001",

"referenceNo" :   "PFUVxBNJ2j8KcufJ5u0t",

"nameAtBank" :   "Krishna",

"statusCode" :   "SUCCESS",

"errorDescription" :   ""

}

}

Example 2

Failure Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "30mar002",

"referenceNo" :   "PFUVf2Wc5pG3U20uwIyb",

"nameAtBank" :   "",

"statusCode" :   "FAILURE",

"errorDescription" :   "REJECTED-INVALID VIRTUAL ADDRESS"

}

}

UPI Payout 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
beneficiaryVPA string Returns the beneficiaryVPA 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
beneficiaryVPA string Returns the beneficiaryVPA 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" :   "batch_Xa06A4ZiiE9bTf5mh0NPu824N3_0",

"referenceNo" :   "PFUPB1E1ckDyFzae44cc7PhebCa02c",

"beneficiaryName" :   "Rakesh",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   1000,

"fee" :   10.00,

"tax" :   1.80,

"totalFee" :   11.80,

"mode" :   "UPI",

"purpose" :   "Payout",

"utrNumber" :   "AXISCN0155605853",

"statusCode" :   "SUCCESS",

"status" :   "Success",

"errorDescription" :   "",

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

Example 2

Failure Case

Request

    {  

"tranType" :   "DEBIT",

"requestId" :   "21527",

"referenceNo" :   "PFUPQ19thDCrfJ6tk8Ne9ZNv7htfuE",

"beneficiaryName" :   "Rakesh",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   1,

"fee" :   0.5,

"tax" :   0.09,

"totalFee" :   0.59,

"mode" :   "UPI",

"purpose" :   "payout",

"utrNumber" :   "220016110284",

"statusCode" :   "FAILURE",

"status" :   "Failure",

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

 "attemptCount" : 1

   }

Response

{

   "code" :   200,

   "message" :   "success"

}

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" :   "21527",

"referenceNo" :   "PFUPQ19thDCrfJ6tk8Ne9ZNv7htfuE",

"beneficiaryName" :   "Rakesh",

"beneficiaryVPA" :   "sheiksha@axis",

"amount" :   1,

"fee" :   0,

"tax" :   0,

"totalFee" :   0,

"utrNumber" :   "REV-220016110284",

"mode" :   "UPI",

"purpose" :   "Recredit",

"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 required
requestId maximum length should not exceed 36 characters
beneficiaryName is required
beneficiaryName maximum length should not exceed 35 characters
beneficiaryName should contains only [a-zA-Z0-9_-., ] character sets
beneficiaryVPA is required
beneficiaryVPA maximum length should not exceed 30 characters
Invalid beneficiaryVPA
amount is required
amount should not be less than INR 1
purpose is required
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
5001 amount should not be more than INR 100000 per transaction
5060 Insufficient balance

Postman Collection

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