Body
Beneficiary Validation / Creation
Merchant can create and validate beneficiary bank account, UPI VPA using this API.
Note
If the merchant only intends to create the beneficiary, use command “CREATE”
Juspay chooses penniless or Penny drop validation depending on banks supported (List here
) and routing logic. Please note this is available only for Juspay account based validation.
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/payout/merchant/v2/benedetails
Production Link
POST
https://api.juspay.in/payout/merchant/v2/benedetails
Authorization Header
Basic Auth
*
String
Mandatory
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
x-merchantid
string
Please pass merchant id provided by Juspay
Parameters
beneId
*
string
Required
For each verification to have a unique reference
customerId
*
string
Required
Merchant customerId
beneDetails
object
Json Object for bene details
details
object
name
String
name of beneficiary
Example:- *Do not pass any special characters in name
ifsc
*
String
Required
IFSC code of bene bank account. Required for ACCOUNT_IFSC
account
*
String
Required
Account number of beneficiary. Required for ACCOUNT_IFSC
vpa
*
String
Required
VPA to be verified. Required for UPI_ID type when mobile is not being passed
mobile
*
String
Required
Mobile number against which primary VPA needs to be fetched. Required for UPI_ID type when vpa is not being passed
payeeAdditionalDetails
JSON Object
documents
Array of JSON Objects
Recommended to pass docType as PAN and docId as PAN no. if merchant is using YESBANK FTX APIs.
docId
String
Example:- "OACPS2488J"
docType
String
Example:- Possible values: "PAN"
type
*
string
Required
Type of beneficiary validation. UPI_ID/ACCOUNT_IFSC/IFSC
command
string
Action recommended to Juspay on provided beneficiary details.
‘VALIDATE’ - this command will create and validate the beneficiary
‘CREATE’ - this command will create the beneficiary at Juspay end
email
string
Email id of beneficiary
phone
string
Phone number of beneficiary
metadata
Object
Additional information to be passed
webhookDetails
Json Object
Dynamic webhook detail
url
String
URL to which callback needs to be sent
username
String
Please provide username if there is any authorization
password
String
Please provide password if there is any authorization
customHeader
String
Please provide headers that are required mandatorily
200 : Success
Response Body
status
String
Status of the validation.
Example:- VALID | INVALID | ERROR | TIMEOUT | PENDING
uniqueId
String
beneId passed by the merchant in the request
beneDetails
Object
Details of beneficiary included in the request
details
Object
Details of beneficiary included in the request
name
String
Name of beneficary passed in the request
vpa
String
account
String
ifsc
String
type
String
Type of validation performed by the merchant
Example:- UPI_ID | ACCOUNT_IFSC
nameAtBank
String
Name derived from the beneficiary bank
responseCode
String
Juspay Response Code for Validation.
Below are the possible values of responseCode in Juspay Validation Suite:
ACCOUNT_BLOCKED_OR_FROZEN, ACCOUNT_CLOSED, ACCOUNT_DOES_NOT_EXIST, ACCOUNT_IS_VALID, AUTHORIZATION_FAILURE, BANK_OFFLINE, BENEFICIARY_BANK_OR_PSP_NOT_REGISTERED, DATA_VALIDATION_ERROR, INSUFFICIENT_FUNDS, INVALID_BANK_ACCOUNT, INVALID_BENEFICIARY_DETAILS, INVALID_IFSC, INVALID_VPA, JUSPAY_DECLINED, LIMIT_EXCEEDED, MEMO_PRESENT, NON_RESIDENT_EXTERNAL_ACCOUNT, RESTRICTED_OR_NOT_ALLOWED, REVERSED, RISK_DECLINE, UNABLE_TO_VALIDATE, VALIDATION_IN_PROGRESS, VALID_VPA, VPA_EXPIRED
responseMessage
String
Juspay Response Message for Validation.
responseMessage will be a description of the responseCode.
Below are some of the sample response messages:
Example:- The beneficiary's bank is currently offline. Please try again after some time | Validation is successful
validationType
String
Type of Validation Performed
Example:- UPI | PennyDrop | Pennyless | UPIACCIFSC
createdAt
String
Validation transaction creation timestamp
updatedAt
String
Validaiton transaction updation timestamp
transactions
Array
Validation transaction(s) details
validationMethod
String
Gateway through which the validation was done.
status
String
Status of the validation transaction
validateResp
JSON
Response received from gateway
createdAt
String
Transaction created value
transactionRef
String
Reference no. of the transaction
responseMessage
String
Message received from gateway
responseCode
String
Code received from gateway
nameAtBank
String
Name of the payee as per bank records
updatedAt
String
Transaction updated value
payeeIfsc
String
ifsc of the payee bank
ifscInfo
JSON
Optional
ifsc details of the payee bank
state
String
state of the payee bank
contact
String
contanct no. of the payee bank
address
String
address of the payee bank
branch
String
branch name of the payee bank
ifsc
String
ifsc value of the payee bank
city
String
city of the payee bank
micr
String
micr value of the payee bank
bankCode
String
bank code of the payee bank
centre
String
district
String
district of the payee bank
bankName
String
name of the payee bank
400 : Invalid Input data
Response Body
error
boolean
errorCode
string
E05
errorMessage
string
Duplicate BeneId.
userMessage
string
Bad request