--- page_title: Beneficiary Validation / Creation product: Payout page_source: https://juspay.io/in/docs/payout/docs/integration/beneficiary-validation--creation openapi: v2: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fpayout%2Fdocs%2Fintegration%2Fbeneficiary-validation--creation%3Fversion%3Dv2 v1: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fpayout%2Fdocs%2Fintegration%2Fbeneficiary-validation--creation%3Fversion%3Dv1 llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/payout/llms.txt --- ## Available API Versions - [v2](#api-version-v2) - [v1](#api-version-v1) ## API Version: v2 # 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](https://juspay.io/in/docs/payout/docs/resources/banks-supported-on-penniless-validation)) and routing logic. Please note this is available only for Juspay account based validation. ## Endpoints: - Sandbox: https://sandbox.juspay.in/payout/merchant/v2/benedetails - Production: https://api.juspay.in/payout/merchant/v2/benedetails ## Request Type: POST ## Authorization: #### Basic Auth: Consists of two parts. * Username: API Key obtained from Juspay dashboard * Password: Empty string Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg== - Tags: String, Mandatory ## Headers: #### x-merchantid: Please pass merchant id provided by Juspay - Tags: string ## Sample Code Snippets: ### Sample Request: #### Account IFSC Code Snippet: ```account ifsc curl --location 'https://sandbox.juspay.in/payout/merchant/v2/benedetails' \ --header 'Content-Type: application/json' \ --header 'x-merchantId: ' \ --header 'Authorization: ••••••' \ --data-raw '{ "beneId":"339178511401", "beneDetails" : { "details": { "name": "Aditya Kadrolkar", "ifsc": "CITI0000001", "account": "02014457596967" }, "type": "ACCOUNT_IFSC" }, "command" : "VALIDATE", "customerId" : "cth_59Yibs1JauYP6WJP", "email": "test@gmail.com", "phone": "9999999999" }' ``` #### UPI Code Snippet: ```upi curl --location 'https://sandbox.juspay.in/payout/merchant/v2/benedetails' \ --header 'Content-Type: application/json' \ --header 'x-merchantId: ' \ --header 'Authorization: ••••••' \ --data-raw '{ "beneId":"339178511402", "beneDetails" : { "details": { "name": "Aditya Kadrolkar", "vpa": "success@upi" }, "type": "UPI_ID" }, "command" : "VALIDATE", "customerId" : "cth_59Yibs1JauYP6WJP", "email": "test@gmail.com", "phone": "9999999999" }' ``` #### ACCOUNT_IFSC with PAN Code Snippet: ```account_ifsc with pan curl --location 'https://sandbox.juspay.in/payout/merchant/v2/benedetails' \ --header 'Content-Type: application/json' \ --header 'x-merchantId: ' \ --header 'Authorization: ••••••' \ --data-raw '{ "beneId":"339178511401", "beneDetails" : { "details": { "name": "Aditya Kadrolkar", "ifsc": "CITI0000001", "account": "02014457596967", "payeeAdditionalDetails":{ "documents": [{ "docId" : "OACPS2488J", "docType" : "PAN" }] } }, "type": "ACCOUNT_IFSC" }, "command" : "VALIDATE", "customerId" : "cth_59Yibs1JauYP6WJP", "email": "test@gmail.com", "phone": "9999999999" }' ``` ### Sample Response: #### Account IFSC: ```json { "status": "VALID", "uniqueId": "339178511401", "beneDetails": { "details": { "name": "Aditya Kadrolkar", "account": "02014457596967", "ifsc": "CITI0000001" }, "type": "ACCOUNT_IFSC" }, "nameAtBank": "Aditya Kadrolkar", "responseCode" : "ACCOUNT_IS_VALID", "responseMessage": "VALIDATION_SUCCESSFULL", "validationType": "PennyDrop", "createdAt": "2024-05-29T13:57:00Z", "updatedAt": "2024-05-29T13:59:33Z", "transactions": [ { "transactionRef": "a3c95727ea24bde9ede56704504e71", "createdAt" : "2024-05-29T13: 58: 07Z", "updatedAt" : "2024-05-29T13: 59: 02Z", "nameAtBank ": "Aditya Kadrolkar", "status" : "VALID", "responseCode" : "ACCOUNT_IS_VALID", "responseMessage" : "VALIDATION_SUCCESSFULL", "validateResp" : { "subCode": "200", "status": "SUCCESS", "message": "VALIDATION_SUCCESSFULL", "data": { "nameAtBank": "Aditya Kadrolkar", "accountExists": "YES" }, "validationMethod" : "KOTAK'JUSPAY_IMPS", "gatewayRefId" : "786652737", "gatewayCredRefId" : "2142101245111" } } ] } ``` #### UPI: ```json { "status": "VALID", "uniqueId": "339178511402", "beneDetails": { "details": { "name": "Aditya Kadrolkar", "vpa": "success@upi" }, "type": "UPI_ID" }, "nameAtBank": "Aditya Kadrolkar", "responseCode": "VALID_VPA", "responseMessage": "Vpa is valid", "validationType": "UPI", "createdAt": "2024-05-29T13:57:00Z", "updatedAt": "2024-05-29T13:59:33Z", "transactions": [ { "transactionRef": "2184138101023940213491", "createdAt": "2024-05-29T13: 58: 07Z", "updatedAt": "2024-05-29T13: 59: 02Z", "nameAtBank ": "Aditya Kadrolkar", "status": "VALID", "responseCode": "VALID_VPA", "responseMessage": "Vpa is valid", "validateResp": { "subCode": "200", "status": "SUCCESS", "message": "Vpa is valid", "data": { "nameAtBank": "Aditya Kadrolkar", "accountExists": "YES" }, "validationMethod": "YESBIZ_UPI", "gatewayRefId": "87419437121", "gatewayCredRefId": "YJP3E294E19100E8347" } } ] } ``` ## Body Parameters: ### Parameters: #### beneId: - Description: For each verification to have a unique reference - Tags: string, Required #### customerId: - Description: Merchant customerId - Tags: string, Required #### beneDetails: - Description: Json Object for bene details - Value: - **Details**: - Value: - **Name**: - Description: name of beneficiary - Value: *Do not pass any special characters in name - Tags: String - **Ifsc**: - Description: IFSC code of bene bank account. Required for ACCOUNT_IFSC - Tags: String, Required - **Account**: - Description: Account number of beneficiary. Required for ACCOUNT_IFSC - Tags: String, Required - **Vpa**: - Description: VPA to be verified. Required for UPI_ID type when mobile is not being passed - Tags: String, Required - **Mobile**: - Description: Mobile number against which primary VPA needs to be fetched. Required for UPI_ID type when vpa is not being passed - Tags: String, Required - **PayeeAdditionalDetails**: - Value: - **Documents**: - Description: Recommended to pass docType as PAN and docId as PAN no. if merchant is using YESBANK FTX APIs. - Value: - **DocId**: - Value: "OACPS2488J" - Tags: String - **DocType**: - Value: Possible values: "PAN" - Tags: String - Tags: Array of JSON Objects - Tags: JSON Object - Tags: object - **Type**: - Description: Type of beneficiary validation. UPI_ID/ACCOUNT_IFSC/IFSC - Tags: string, Required - Tags: object #### command: - Description: 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 - Tags: string #### email: - Description: Email id of beneficiary - Tags: string #### phone: - Description: Phone number of beneficiary - Tags: string #### metadata: - Description: Additional information to be passed - Value: - **WebhookDetails**: - Description: Dynamic webhook detail - Value: - **Url**: - Description: URL to which callback needs to be sent - Tags: String - **Username**: - Description: Please provide username if there is any authorization - Tags: String - **Password**: - Description: Please provide password if there is any authorization - Tags: String - **CustomHeader**: - Description: Please provide headers that are required mandatorily - Tags: String - Tags: Json Object - Tags: Object ## API Responses: ### 200: #### status: - Description: Status of the validation. - Value: VALID | INVALID | ERROR | TIMEOUT | PENDING - Tags: String #### uniqueId: - Description: beneId passed by the merchant in the request - Value: 339178511402 - Tags: String #### beneDetails: - Description: Details of beneficiary included in the request - Value: - **Details**: - Description: Details of beneficiary included in the request - Value: - **Name**: - Description: Name of beneficary passed in the request - Value: Aditya Kadrolkar - Tags: String - **Vpa**: - Value: success@upi - Tags: String - **Account**: - Tags: String - **Ifsc**: - Tags: String - Tags: Object - **Type**: - Description: Type of validation performed by the merchant - Value: UPI_ID | ACCOUNT_IFSC - Tags: String - Tags: Object #### nameAtBank: - Description: Name derived from the beneficiary bank - Value: Aditya Kadrolkar - Tags: String #### responseCode: - Description: 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 - Value: VALID_VPA - Tags: String #### responseMessage: - Description: Juspay Response Message for Validation.responseMessage will be a description of the responseCode.Below are some of the sample response messages: - Value: The beneficiary's bank is currently offline. Please try again after some time | Validation is successful - Tags: String #### validationType: - Description: Type of Validation Performed - Value: UPI | PennyDrop | Pennyless | UPIACCIFSC - Tags: String #### createdAt: - Description: Validation transaction creation timestamp - Value: 2024-05-29T13:57:00Z - Tags: String #### updatedAt: - Description: Validaiton transaction updation timestamp - Value: 2024-05-29T13:59:33Z - Tags: String #### transactions: - Description: Validation transaction(s) details - Value: - **ValidationMethod**: - Description: Gateway through which the validation was done. - Tags: String - **Status**: - Description: Status of the validation transaction - Tags: String - **ValidateResp**: - Description: Response received from gateway - Tags: JSON - **CreatedAt**: - Description: Transaction created value - Tags: String - **TransactionRef**: - Description: Reference no. of the transaction - Tags: String - **ResponseMessage**: - Description: Message received from gateway - Tags: String - **ResponseCode**: - Description: Code received from gateway - Tags: String - **NameAtBank**: - Description: Name of the payee as per bank records - Tags: String - **UpdatedAt**: - Description: Transaction updated value - Tags: String - **PayeeIfsc**: - Description: ifsc of the payee bank - Tags: String - Tags: Array #### ifscInfo: - Description: ifsc details of the payee bank - Value: - **State**: - Description: state of the payee bank - Tags: String - **Contact**: - Description: contanct no. of the payee bank - Tags: String - **Address**: - Description: address of the payee bank - Tags: String - **Branch**: - Description: branch name of the payee bank - Tags: String - **Ifsc**: - Description: ifsc value of the payee bank - Tags: String - **City**: - Description: city of the payee bank - Tags: String - **Micr**: - Description: micr value of the payee bank - Tags: String - **BankCode**: - Description: bank code of the payee bank - Tags: String - **Centre**: - Tags: String - **District**: - Description: district of the payee bank - Tags: String - **BankName**: - Description: name of the payee bank - Tags: String - Tags: JSON , Optional ### 400: #### error: - Tags: boolean #### errorCode: - Description: E05 - Tags: string #### errorMessage: - Description: Duplicate BeneId. - Tags: string #### userMessage: - Description: Bad request - Tags: string --- ## API Version: v1 # Bank Account Validation Merchant can validate beneficiary bank account, VPA using this API## Endpoints: - Production: https://api.juspay.in/payout/merchant/v1/benedetails ## Request Type: POST ## Authorization: #### Basic Auth: Consists of two parts. * Username: API Key obtained from Juspay dashboard * Password: Empty string Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg== - Tags: String, Mandatory ## Headers: #### x-merchantid: Please pass merchant id provided by Juspay - Tags: string ## Sample Code Snippets: ### Sample Request: #### Account IFSC Code Snippet: ```account ifsc curl --location --request POST 'https://api.juspay.in/payout/merchant/v1/benedetails' \ -u your_api_key: \ --header 'Content-Type: application/json' \ --header 'x-merchantId: ' \ --data-raw '{ "beneId":"ravibene4", "beneDetails" : { "details": { "name": "Shubham Kumar", "ifsc": "YESB0000262", "account": "026291800001191" }, "type": "ACCOUNT_IFSC" }, "preferredGateway" : "CFGEN", "command" : "validate", "customerId" : "ravi1", "email": "dummy@gmail.com", "phone": "9999999999" }' ``` #### UPI Code Snippet: ```upi curl --location --request POST 'https://api.juspay.in/payout/merchant/v1/benedetails' \ -u your_api_key: \ --header 'Content-Type: application/json' \ --header 'x-merchantid: ' \ --data-raw '{ "beneId":"ravibene1", "beneDetails" : { "details": { "name": "Shubham Kumar", "vpa": "success@upi" }, "type": "UPI_ID" }, "preferredGateway" : "CFGEN", "command" : "validate", "customerId" : "ravi1", "email": "dummy@gmail.com", "phone": "9999999999" }' ``` #### Mobile Number to VPA Code Snippet: ```mobile number to vpa curl --location 'https://api.juspay.in/payout/merchant/v1/benedetails' \ --header 'Content-Type: application/json' \ --header 'x-merchantid: ' \ --header 'Authorization: Basic (b64 encoded API key)' \ --data-raw '{ "beneId":"beneID11", "beneDetails" : { "details": { "name": "Aditya Kadrolkar", "mobile": "8088375524" }, "type": "UPI_ID" }, "preferredGateway" : "YESBIZ", "command" : "resolve", "customerId" : "14212551", "email": "test@gmail.com", "phone": "8088375524" }' ``` #### ACCOUNT IFSC with PAN Code Snippet: ```account ifsc with pan curl --location 'https://sandbox.juspay.in/payout/merchant/v2/benedetails' \ --header 'Content-Type: application/json' \ --header 'x-merchantId: ' \ --header 'Authorization: ••••••' \ --data-raw '{ "beneId":"339178511401", "beneDetails" : { "details": { "name": "Aditya Kadrolkar", "ifsc": "CITI0000001", "account": "02014457596967", "payeeAdditionalDetails":{ "documents": [{ "docId" : "OACPS2488J", "docType" : "PAN" }] } }, "type": "ACCOUNT_IFSC" }, "command" : "VALIDATE", "customerId" : "cth_59Yibs1JauYP6WJP", "email": "test@gmail.com", "phone": "9999999999" }' ``` ### Sample Response: #### Account IFSC: ```json { "validateResp": { "subCode": "200", "status": "SUCCESS", "message": "Bank Account details verified successfully", "data": { "utr": "1643701127355992", "refId": "1063069", "nameAtBank": "JOHN DOE", "micr": 400532038, "city": "GREATER BOMBAY", "branch": "SANTACRUZ, MUMBAI", "bankName": "YES BANK", "amountDeposited": "1" }, "accountStatusCode": "ACCOUNT_IS_VALID", "accountStatus": "VALID" }, "uniqueId": "ravibene4", "status": "VALID", "remark": "Bank Account details verified successfully", "nameAtBank": "JOHN DOE", "fulfillmentMethod": "CFGEN_IMPS", "beneDetails": { "details": { "name": "Shubham Kumar", "ifsc": "YESB0000262", "account": "026291800001191" }, "type": "ACCOUNT_IFSC" } } ``` #### UPI: ```json { "validateResp": { "subCode": "200", "status": "SUCCESS", "message": "VPA verification successful", "data": { "nameAtBank": "JOHN SNOW", "accountExists": "YES" } }, "uniqueId": "ravibene5", "status": "VALID", "remark": "VPA verification successful", "nameAtBank": "JOHN SNOW", "fulfillmentMethod": "CFGEN_UPI", "beneDetails": { "details": { "vpa": "success@upi", "name": "Shubham Kumar" }, "type": "UPI_ID" } } ``` #### Mobile Number to VPA: ```json { "validateResp": { "status": "SUCCESS", "responseMessage": "SUCCESS", "responseCode": "SUCCESS", "payload": { "vpa": "test@upi", "name": "Aditya", "merchantId": "ECYBUPITEST", "merchantChannelId": "ECYBUPITESTAPP", "isMerchant": "false", "iin": "500007", "ifsc": "AABD0000011", "gatewayTransactionId": "fdbb7168f9d4e90945fa032823f7ea", "gatewayResponseStatus": "SUCCESS", "gatewayResponseMessage": "Your transaction is successful", "gatewayResponseCode": "00" } }, "uniqueId": "beneID11", "status": "VALID", "responseCode": "VALID_VPA", "resolvedVpa": "test@upi", "remark": "Mobile Number Resolved Successfully", "nameAtBank": "Aditya", "gatewayRefId": "fdbb7168f9d4e90945fa032823f7ea", "fulfillmentMethod": "YESBIZ_UPI", "beneDetails": { "details": { "mobile": "8088375524" }, "type": "UPI_ID" } } ``` ## Body Parameters: ### Parameters: #### beneId: - Description: For each verification to have a unique reference - Tags: string, Required #### customerId: - Description: Merchant customerId - Tags: string, Required #### beneDetails: - Description: Json Object for bene details - Value: - **Details**: - Value: - **Name**: - Description: name of beneficiary - Value: *Do not pass any special characters in name - Tags: String - **Ifsc**: - Description: IFSC code of bene bank account. Required for ACCOUNT_IFSC - Tags: String, Required - **Account**: - Description: Account number of beneficiary. Required for ACCOUNT_IFSC - Tags: String, Required - **Vpa**: - Description: VPA to be verified. Required for UPI_ID type when mobile is not being passed - Tags: String, Required - **Mobile**: - Description: Mobile number against which primary VPA needs to be fetched. Required for UPI_ID type when vpa is not being passed - Tags: String, Required - **PayeeAdditionalDetails**: - Value: - **Documents**: - Description: Recommended to pass docType as PAN and docId as PAN no. if merchant is using YESBANK FTX APIs. - Value: - **DocId**: - Value: "OACPS2488J" - Tags: String - **DocType**: - Value: Possible values: "PAN" - Tags: String - Tags: Array of JSON Object - Tags: JSON object - Tags: object - **Type**: - Description: Type of beneficiary validation. UPI_ID/ACCOUNT_IFSC/IFSC - Tags: string, Required - Tags: object #### preferredGateway: - Description: Preffered gateway through which bene validation should happen - Tags: string #### metadata: - Description: Additional metadata - Tags: string #### command: - Description: 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‘resolve’ - this command will fetch primary VPA linked to the mobile number passed in beneficiary details - Tags: string #### email: - Description: Email id of beneficiary - Tags: string #### phone: - Description: Phone number of beneficiary - Tags: string ## API Responses: ### 200: #### 200 : UPI_ID: - Value: - **ValidateResp**: - Value: - **SubCode**: - Tags: String - **Status**: - Tags: String - **Message**: - Tags: String - **Data. nameAtBank**: - Tags: String - **Data. accountExists**: - Tags: String - Tags: Object - **UniqueId**: - Tags: String - **Status**: - Tags: String - **Remark**: - Tags: String - **NameAtBank**: - Tags: String - **FulfillmentMethod**: - Tags: String - **BeneDetails**: - Value: - **Details.vpa**: - Tags: String - **Details.name**: - Tags: String - **Type**: - Tags: String - Tags: Object - Tags: Object #### 200 : Account_IFSC: - Value: - **ValidateResp**: - Value: - **SubCode**: - Tags: String - **Status**: - Tags: String - **Message**: - Tags: String - **Data. utr**: - Tags: String - **Data. refId**: - Tags: String - **Data. nameAtBank**: - Tags: String - **Data. micr**: - Tags: Integer - **Data. city**: - Tags: String - **Data.branch**: - Tags: String - **Data.bankName**: - Tags: String - **Data. amountDeposited**: - Tags: String - **AccountStatusCode**: - Tags: String - **AccountStatus**: - Tags: String - Tags: Object - **UniqueId**: - Tags: String - **Status**: - Tags: String - **Remark**: - Tags: String - **NameAtBank**: - Tags: String - **FulfillmentMethod**: - Tags: String - **BeneDetails**: - Value: - **Details.name**: - Tags: String - **Details.ifsc**: - Tags: String - **Details.account**: - Tags: String - **Type**: - Tags: String - Tags: Object - Tags: Object ### 400: #### error: - Tags: boolean #### errorCode: - Description: E05 - Tags: string #### errorMessage: - Description: Duplicate BeneId. - Tags: string #### userMessage: - Description: Bad request - Tags: string --- ## See Also - [Attempt API [Encrypted]](https://juspay.io/in/docs/payout/docs/integration/attempt-api-encrypted) - [Beneficiary Validation Status Check](https://juspay.io/in/docs/payout/docs/integration/beneficiary-validation-status-check)