Reverse Penny Drop Verification - Retrieve Bank Details API

The following document highlights the details of the Retrieve Bank Details API.

API Description

Objective

The Retrieve Bank Details API fetches the bank account details of the user. It also reflects the details of the initial penny drop transaction and its reversal.

Input	Output
The reference and verification IDs from the Initiate Payment Links API	The details of the user's bank account and the penny drop transaction

Prerequisite

A penny drop transaction done by the user through one of the links generated by the Initiate Payment Links API.

API URL

https://ind-engine.thomas.hyperverge.co/v1/rpdGetDetails

API Endpoint

rpdGetDetails

Overview

The Retrieve Bank Details API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Retrieve Bank Details API.

Headers

Header	Mandatory / Optional	Description	Input Format
Content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Retrieve Bank Details API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
verificationId	Mandatory	string	The unique verification ID for the user	Not Applicable	Not Applicable
rpdVendor	Conditionally optional	string	Specifies the RPD vendor to use. This is the second step in the RPD process; use the same vendor as you did in the Initiate Payment Links API. Accepted values: yesBankRPD: dynamic payment recipient names citiBankRPD: static/fixed recipient name for all payments Optional when used for testing; Mandatory when processing verification requests outside of testing.	One of: yesBankRPD, citiBankRPD	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Retrieve Bank Details API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/rpdGetDetails' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "verificationId": "<Enter_the_Verification_ID>",
    "rpdVendor": "yesBankRPD/citiBankRPD" // use the same value as in the Initiate Payment Links API request

}'

Success Response

The following code snippet demonstrates a success response from the Retrieve Bank Details API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "status": "Success",
    "bankAccount": "<Bank_Account_Number_of_the_user>",
    "ifsc": "<IFSC_Code>",
    "upi": "<UPI_ID>",
    "nameAtBank": "<User_Name>",
    "verificationId": "<Verification_ID>",
    "utr": "<Unique_Transaction_Reference>",
    "addedOn": "<Date_and_time_of_payment>",
    "processedOn": "<Date_and_time_when_payment_processed>",
    "pennyCollectedOn": "<Date_and_time_of_penny_collection>",
    "reversalStatus": "TRANSFER_SUCCESS",
    "accountType": "SAVINGS"
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Success Response Details

The following table outlines the details of the success response from the Retrieve Bank Details API:

Parameter	Type	Description
bankAccount	string	The full bank account number of the user
ifsc	string	The IFSC code associated with the bank account
upi	string	The UPI ID with which the payment is made
nameAtBank	string	The name of the user associated with the bank account
verificationId	string	The unique verification ID for the user
utr	string	The unique Transaction Reference number for the payment
status	string	The payment status of the user. It can have the values "SUCCESS" or "FAILURE".
addedOn	string	The timestamp when the payment was added
processedOn	string	The timestamp when the payment was processed
pennyCollectedOn	string	The timestamp when the Penny (₹1) was collected from the user
reversalStatus	string	The status of reversing the penny back to the user. It can have values like "TRANSFER_INITIATED" or "TRANSFER_SUCCESS".
accountType	string	The user's bank account type

Failure Response

The following code snippet demonstrates a failure response from the Retrieve Bank Details API when the payment fails for some reason:

The following are additional failure responses from the Retrieve Bank Details API (ordered by label ascending):

Payment Failed

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Payment failure",
    "verificationId": "<Verification_ID>",
    "referenceId": "<Reference_ID>",
    "status": "FAILURE",
    "addedOn": "<Date_and_time_of_payment>",
    "processedOn": "<Date_and_time_when_payment_processed>"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Transaction Created

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Created",
    "verificationId": "<Verification_ID>",
    "referenceId": "<Reference_ID>",
    "status": "CREATED",
    "addedOn": "<Date_and_time_of_payment>",
    "processedOn": "<Date_and_time_when_payment_processed>"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Responses

The following are some error responses from the Retrieve Bank Details API:

Bad Request

{
  "status": "failure",
  "statusCode": 400,
  "error": "Bad request",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Verification ID Exists

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "verificationId already exists"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Input Length Error

{
  "message": "Input Validation Error: does not meet minimum length of 1",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Input

{
  "message": "Input Validation Error: is not one of enum values: citiBankRPD,yesBankRPD",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Partner Key

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid Partner Key",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Reference ID

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Please enter a valid referenceId"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Verification ID

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Please enter a valid verificationId"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid verificationId Format

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid verificationId format",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing Verification/Reference ID

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Please provide verificationId or referenceId"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing Path Variable

{
  "status": "failure",
  "statusCode": 400,
  "error": "Missing path variable",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing Request Parameter

{
  "status": "failure",
  "statusCode": 400,
  "error": "Missing request parameter",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Partner is Inactive

{
  "status": "failure",
  "statusCode": 400,
  "error": "Partner is inactive",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Payment Link Expired

{
  "statusCode": 400,
  "status": "failure",
  "error": {
    "message": "Payment link expired",
    "verificationId": "<Verification_ID>",
    "referenceId": "<Reference_ID>",
    "status": "EXPIRED",
    "addedOn": "<Date_and_time_of_payment>",
    "processedOn": "<Date_and_time_when_payment_processed>"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Transaction Already Completed

{
  "status": "failure",
  "statusCode": 400,
  "error": "Transaction already completed",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Transaction in Progress

{
  "status": "failure",
  "statusCode": 400,
  "error": "Transaction in progress",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Unable to Fetch UPI Intent Status

{
  "status": "failure",
  "statusCode": 400,
  "error": "Unable to fetch upi intent status, please try again later",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

verificationId Required

{
  "status": "failure",
  "statusCode": 400,
  "error": "verificationId required",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Forbidden Access

{
  "status": "failure",
  "statusCode": 403,
  "error": "Forbidden access",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Service Not Assigned

{
  "status": "failure",
  "statusCode": 403,
  "error": "Service not assigned",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Rate Limit Exceeded

{
  "statusCode": 429,
  "status": "failure",
  "error": "Rate limit exceeded",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

External Vendors Unavailable

{
  "status": "failure",
  "statusCode": 503,
  "error": "All external vendors are currently unavailable. Please try again later.",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Payment failure	The payment has failed.	Retry the transaction or contact the HyperVerge team for resolution
400	Created	The transaction record already exists with status CREATED (payment link created but payment not yet completed).	Wait for the user to complete the payment, or use the same verificationId/referenceId to poll for status
400	Bad request	The request is malformed or invalid.	Check the request URL, headers, and body and retry
400	Input Validation Error: does not meet minimum length of 1	The request did not meet the minimum length requirement of 1.	Ensure the input parameters meet the required validation criteria
400	Input Validation Error: is not one of enum values: citiBankRPD,yesBankRPD	The rpdVendor value is not allowed. Only citiBankRPD or yesBankRPD are accepted.	Set rpdVendor to either citiBankRPD or yesBankRPD (same as in the Initiate Payment Links API request)
400	Invalid Partner Key	The partner key (credentials) is invalid or not recognized.	Verify your appId and appKey or contact the HyperVerge team
400	Payment link expired	The payment link associated with the provided verification ID has expired.	Use the Initiate Payment Links API to generate new payment links
400	verificationId already exists	The provided verification ID already exists in the system.	Use a different verification ID or wait for the existing verification to expire
400	Please enter a valid verificationId	The provided verification ID is invalid.	Provide a valid verification ID from the Initiate Payment Links API response
400	Please provide verificationId or referenceId	The request is missing either the verification ID or the reference ID.	Include either verificationId or referenceId in the request body
400	Please enter a valid referenceId	The provided reference ID is invalid.	Provide a valid reference ID from the Initiate Payment Links API response
400	Missing path variable	A required path variable is missing from the request.	Ensure the request URL includes all required path parameters
400	Missing request parameter	A required request parameter is missing.	Include all mandatory query or body parameters in the request
400	verificationId required	The verificationId parameter is required but was not provided.	Include verificationId in the request body (or use referenceId if supported)
400	Invalid verificationId format	The verificationId value does not match the expected format.	Provide a verification ID in the correct format (from the Initiate Payment Links API response). Exclude the usage of any special characters
400	Transaction in progress	The transaction is still being processed; details are not yet available.	Retry the request after a short delay
400	Transaction already completed	The transaction has already been completed; duplicate or repeated submission is not allowed.	Use the existing result or start a new verification with a new transactionId
400	Partner is inactive	The partner integration for the supplied credentials is inactive. The RPD vendor integration may be suspended or inactive for a defined period.	Contact the HyperVerge team to reactivate the partner or RPD vendor integration
400	Unable to fetch upi intent status, please try again later	The system could not retrieve the UPI intent status; the operation may be temporarily unavailable.	Retry the request after a short delay or contact the HyperVerge team if it persists
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials.	Provide valid appId and appKey credentials in the request
403	Service not assigned	The service (e.g. RPD) is not assigned to the partner or credentials.	Contact the HyperVerge team to get the service enabled for your credentials
403	Forbidden access	Access to the resource or operation is forbidden for the supplied credentials.	Verify your permissions or contact the HyperVerge team
429	Rate limit exceeded	You have exceeded the configured rate limit for transactions per minute.	Wait before making another request or contact the HyperVerge team to adjust rate limits
500	Internal Server Error	There was an error with HyperVerge's server.	Check the request headers or contact the HyperVerge team for resolution
503	All external vendors are currently unavailable. Please try again later.	External RPD or payment vendors are temporarily unavailable.	Retry the request after some time or contact the HyperVerge team if the issue persists