Body
Push to VPA API
This api will be used for initiating a new Push to VPA request to transfer money directly to customer. Also used for Penny Drop use case.
Before initiating this API, it is recommended to do Verify VPA API request to the PSP to check the validity of customer’s VPA or UPI ID. If a valid response is received, then only initiate the Push to VPA API request.
Payout can be also done based on Account Number & IFSC code combination by passing the value in customerVpa as Global Address i.e. account-no@ifsc-code.ifsc.npci (e.g.12345@HDFC0000001.ifsc.npci)
Warning
Only one of customerVpa or upiNumber (UPI ID) is allowed in the request. Both or none are not allowed.
This API can be used only after onboarding from the bank end.
gatewayResponseStatus anything other than SUCCESS and FAILURE to be considered PENDING. For PENDING & DEEMED cases, keep doing status check for next 3-5 days to get the terminal status.
Request
Response
API Endpoints
Production Link
POST
{{host}}/api/{{uri}}/merchants/transactions/pushToVpa
Headers
jpupi-routing-id
*
String
Mandatory
Header value should be same as of merchantRequestId sent in request body
Request Schema: application/json
Request parameters
merchantRequestId
*
String
Mandatory
Request id for PushToVpa request.
Constraints: Max 35 characters & Alphanumeric.
customerVpa
*
String
Mandatory
VPA of the customer to be used for transaction.
Constraint: VPA should only contain a-z, 0-9, . (dot), - (hyphen).
amount
*
String
Mandatory
Amount for the transaction.
Constraint: Amount in two decimals. Decimals are mandatory.
merchantVpa
*
String
Mandatory
VPA of the merchant from which amount has to be deducted.
Constraint: VPA should only contain a-z, 0-9, . (dot), - (hyphen).
remarks
*
String
Mandatory
Remarks sent by merchant for the transaction.
Constraint: The transaction note must be alphanumeric, with a minimum length of 1 character and a maximum length of 50 characters.
iat
*
String
Mandatory
Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.
Example: 1496918882000.
udfParameters
Stringified JSON
optional
Merchant Defined Parameters
Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
Note: Few special characters are not allowed. Regex for the characters which are not allowed : ^[^/#-()*!%~`]+$
200 : Success
Response Body
status
*
String
Mandatory
Status of the API.
Example:- Values: SUCCESS | FAILURE.
responseCode
*
String
Mandatory
PSP response code for the API.
Values: Refer Codes Guide in Resource Section.
responseMessage
*
String
Mandatory
PSP response message for the API.
Values: Refer Codes Guide in Resource Section.
payload
*
Json
Mandatory
customerVpa
*
String
Mandatory
Vpa of the customer to be used for transaction.
merchantId
*
String
Mandatory
Unique id for merchant.
merchantChannelId
*
String
Mandatory
Unique id for the channel via which request is made.
merchantRequestId
*
String
Mandatory
Request id used for the transaction.
transactionAmount
*
String
Mandatory
The amount for which transaction was performed.
gatewayReferenceId
*
String
Mandatory
RRN for the transaction.
gatewayTransactionId
*
String
Mandatory
UPI request id returned by gateway for the transaction.
gatewayResponseCode
*
String
Mandatory
Response code returned by gateway for the transaction.
gatewayResponseMessage
*
String
Mandatory
Response message returned by gateway for the transaction.
bankAccountHash
String
optional
Hashed value of accounts passed to merchant. Present if transaction is Success.
Hashing logic:
bankAccountHash = sha256( account Number + first 4 digit of account IFSC)
From account Number the leading zeros are removed and then the hash is calculated.
Eg: Account No. = 0000123456789 & IFSC = ABCD0000345
Hash will be calculated on 123456789ABCD.
payeeMaskedAccountNumber
String
optional
Containing the account number of Customer in masked format. Present if transaction is Success.
payeeName
String
optional
Name of the UPI user who received the payment. Only if payment is done to a non A/C+IFSC Global VPA. Present if transaction is Success.
payeeIfsc
String
optional
Account IFSC of the customer who received the payment. Present if transaction is Success.
gatewayResponseStatus
*
String
Mandatory
Response status returned by gateway for the transaction.
Values : SUCCESS, FAILURE, PENDING or DEEMED.
Warning
Anything other than SUCCESS and FAILURE to be considered PENDING.
udfParameters
Stringified Json
Optional
Merchant Defined Parameters
Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
Have questions?
- Need help? Contact support
- LLM? Read llms.txt