Additional Info. for Recurring Payment APIs

Request parameters for PreDebit Notification API

Parameter NameDescription
statusStatus defines acknowledgment from PayU. Possible values are :
1- This value indicates that pre-debit notification is triggered successfully for customer or deleted successfully in case of action delete.
· 0 – This value indicates pre-debit notification failed to get triggered and merchant should retry after some time to trigger the same or failed to get deleted in case of action delete.
actionAlways returned as “MANDATE_PRE_DEBIT” to highlight the type of action.
messageDescription of the pre-debit notification process
invoiceIdThis is an acknowledgment ID that a pre debit notification has been sent for processing.
invoiceStatusThis is the status of the invoice whether it has been charged for recurring or not. Values can be:
- Paid
- Unpaid
- Deleted
Since these statuses come from a third-party vendor, so these can vary if there is an addition of new status at the vendor end
approvedStatusThis is for cases where the transaction is above 15000 as RBI guideline says approval is required through AFA (Additional Factor authentication) Values can be.:
- Pending

- Approved
- Not_applicable
Since these statuses come from third-party vendors, so these can vary if there is an addition of new status at the vendor end.

var1 JSON fields description

The var1 variable is in JSON format and comprises of the following parameters:

JSON FieldDescription
authpayuid
mandatory
The value of mihpayid returned in the payment response of Registration transaction when transaction is successfully completed. As explained earlier in the document, you need to map this value against customer profile at his end so that correct authPayuid will be passed in the request.
requestId
mandatory
Unique request value generated at merchant’s end to distinguish independent request call.
debitDate
mandatory for cards and UPI
This parameter contains the date of debit when the recurring would be charged by merchant.
*In UPI:**
- For all frequencies (other than Daily and Adhoc), the merchant must send the notification 48 hours before the debit.
- For Daily and Adhoc frequency, the merchant must send the notification 24 hours before the debit. If the notification is sent after these durations, then the debit will fail.
invoiceDisplayNumber
mandatory only for cards
A unique display number by merchant for every subsequent invoice/recurring charge. This can be displayed on the merchant’s panel to the customer. This same value needs to be sent in the recurring api also.
amount
mandatory for cards and UPI
The transaction amount which will be deducted from the customer’s payment instrument.
For Cards:
- In case of Fixed billing plan, this amount should be same as
billingAmount sent during Registration transaction.
- In case of Adhoc billing plan, this amount should be equal to or lesser than billingAmount sent during the Registration transaction.
*Note: The amount mentioned in the Pre-Debit notification API for UPI should be same as the next execution amount. Else, the next recurring execution request will fail.
action
optional
Any of the following actions can be performed:
* Retrieve: Query the status of the pre-debit notification. Only authpayuid and invoice display numbers are mandatory for this action.
* Delete: Delete the already generated pre debit. Only authpayuid and invoice display numbers are mandatory for this action.

Response parameters for Pre-debit Notification API

Parameter NameDescription
statusStatus defines acknowledgment from PayU. Possible values are :
· 1- This value indicates that pre-debit notification is triggered successfully for customer or deleted successfully in case of action delete.

· 0 – This value indicates pre-debit notification failed to get triggered and merchant should retry after some time to trigger the same or failed to get deleted in case of action delete.
actionAlways returned as “MANDATE_PRE_DEBIT” to highlight the type of action.
messageDescription of the pre-debit notification process
invoiceIdThis is an acknowledgment ID that a pre debit notification has been sent for processing.
invoiceStatusThis is the status of the invoice whether it has been charged for recurring or not. Values can be:
- Paid
- Unpaid
- Deleted

Since these statuses come from a third-party vendor, so these can vary if there is an addition of new status at the vendor end
approvedStatusThis is for cases where the transaction is above 15000 as RBI guideline says approval is required through AFA (Additional Factor authentication). Values can be:
- Pending

- Approved
- Not_applicable
Since these statuses come from third-party vendors, so these can vary if there is an addition of new status at the vendor end.

Sample Response

Successful Pre-Debit Notification Response

Successful Pre-Debit notification Response

{
"status": 1,
"action": "MANDATE_PRE_DEBIT",
"message": "Request Processed Successfully",
“invoiceId”:” ADDA049409”
}

Failure Scenarios

  •  Mandate is active in PayU DB and Pre-Debit gets declined from Bank/NPCI
{
"status":  “QC”   ----- >> Bank/NPCI Error Code
"action": "MANDATE_PRE_DEBIT",
"message": “MANDATE HAS BEEN REVOKED”. ---- >> Description against error code
}

Where, the message parameter in the response will display error code according to the scenario

  • Mandate is already Paused/ Revoked in PayU DB
{
"status": 0,
"action": "MANDATE_PRE_DEBIT",
"message": "Mandate is not active” --- >> Description will change based on Scenario
}

Where, the message parameter in the response will display according to the scenario.

Response parameters for Recurring Payment Transaction API

JSON fields description of the Details parameter

JSON FieldDescription
transactionidThis field contains the value of transaction ID parameter which is echoed back in the response. This is unique transaction ID generated by merchant during calling recurring API.
amountThis field contains the requested transaction amount is echoed back in the payment response.
payuidThis field contains the PayU’s transaction ID for processed recurring transaction. Merchant can use this field for reference point in the settlement report.
statusThis field gives the status of the transaction. Hence, the value of this field depends on whether the transaction was successful or not.
field9This field returns the description of transaction status which can help the merchant in providing better customer communication.
phoneThe mobile number of the customer echoed back.
emailEmail ID of the customer echoed back.
udf2Extra information received in the request echoed back.
udf3Extra information received in the request echoed back.
udf4Extra information received in the request echoed back.
udf5Extra information received in the request echoed back.

status field description

This field gives the status of the transaction. Hence, the value of this field depends on whether the transaction was successful or not.
You must map the order status using this parameter only. The possible values of this parameter are:

  • captured: If the transaction is successful, the value will be captured. In some cases, the response of Net banking recurring can be captured over real-time basis (ICICI bank in the specific scenario).
  • pending: This is common with most Net Banking (except ICICI in the specific scenario) or UPI recurring transaction. In that case, the merchant should consider this as successful initiation of payment with bank / NPCI. The status will be notified back to the merchant over payment processing with individual bank gets completed.
    For UPI, “pending” transactions get usually get converted into captured or failed within 10 mins from the time of initiation. The Query API can be called post 10 mins from initiation, whereas for Net Banking, it can be called up to T+2 once a day. For more information, refer to Capture response of Recurring Transaction.
    For Net Banking, “pending” transaction gets converted into “captured” or “failed” from the same day till T+2 anytime, depending upon the bank account used by the customer in setting up registration. 

  • failed: The value of the status as “failed” or blank must be treated as a failed transaction only.
  • in-progress: The status of transaction is in progress.

To capture the final status of “pending” transaction to either “captured” or “failed”, PayU recommends merchants to either implement Webhook URL or call verify_payment API after regular intervals. For more information on:

📘

Note:

For UPI, call the verify_settlement API after 10 mins from time of initiation whereas for Net Banking it can be called up to T+2 once in a day.

Sample response

Success scenario

Here is a sample response object returned against recurring payment API when the transaction is successfully charged.

{ 
     "status": 1, 
     "message": "Transaction Processed successfully", 
     "details": { 
         "REC15113506209": { 
             "transactionid": "REC15113506209", 
             "amount": "3", 
             "payuid": "6611427463", 
             "status": "captured", 
             "field9": "Transaction Completed Successfully", 
             "phone": "9999999999", 
             "email": "[email protected]", 
             "udf2": "", 
             "udf3": "", 
             "udf4": "", 
             "udf5": "" 
         } 
     } 
} 

Failure scenarios

  • Invalid hash
{
    "status": 0,
    "msg": "Invalid Hash."
}
  • Basic authentication check failed
{
    "status": 1,
    "message": "Transaction Processed successfully",
    "details": {
        "REC9812123123": {
            "authpayuid": "6611192559",
            "transactionid": "REC9812123123",
            "amount": "1",
            "user_credentials": " ",
            "card_token": " ",
            "payuid": "",
            "status": "failed",
            "field9": "Basic authentication check failed",
            "phone": "",
            "email": ""
        }
    }

Capture response of Recurring Transaction for Net Banking and UPI

In the case of recurring payments for Cards, the transaction’s status is conveyed over a real-time basis as the process is synchronous. However, most of the Net Banking and UPI recurring payments are not synchronous, and the final response of the transaction is not communicated over real-time.

When PayU receives such recurring requests against Net Banking or UPI, it validates the request parameters and associated registration details for a given “authpayuid.” If they are valid, PayU returns “pending” status to the merchant over real-time API response.

From here onwards, there are two approaches the merchant can follow in capturing the final status of the transaction.

Capturing Status over Webhook

For pending cases, PayU can notify you of the exact status of the transaction as either “success” or “failure” over Server-to-Server if the merchant exposes a webhook.

To get the status of transactions notification, you need to expose a webhook and you need to request PayU’s integration team to configure the same against the ws_online_response parameter.

If this webhook is configured, the merchant will receive the above response object over HTTP form post method as mentioned below –

unmappedstatus=success&phone=9999999999&txnid=FCDA1R100870163781&hash=84e335094bbcb2ddaa0f9a488eb338e143b273765d89c9dfa502402562d0b6f3c7935e28194ca92f380be7c84c3695415b106dcf52cb016a15fcf6adc98d724&status=success&curl=https://www.abc.in/payment/handlepayuresposne&firstname=NA&card_no=519619XXXXXX5049&furl=https://www.abc.in/payment/handlepayuresposne&productinfo=2&mode=DC&amount=800.00&field4=6807112311042810&field3=6807112311042810&field2=838264&field9=SUCCESS&email=NA&mihpayid=175477248&surl=https://www.ABC.in/payment/handlepayuresposne&card_hash=9e88cb0573d4a826b61d808c0a870ed4a990682459b0ec9e95ea421e8e47be8c&field1=42812

If by any means transaction is rejected from banks, then the status will be returned as “failure” over webhook. For more information on webhooks, refer to Webhooks.