Resource: _payment
This section describes how to use the _payment API to update an existing recurring payment for a card.
Note:
As per RBI guidelines while modifying the recurring payment, taking consent from the customer and doing an additional factor of authentication is mandatory. You must ensure this is done before using this API. You need to pass authPayuId and action fields to modify the billing details as part of JSON using this API as described in this section.
HTTP Method: POST
Request parameters
The following table describes the parameters for modifying the recurring payment details for a card.
Parameter | Description | Example |
---|---|---|
key mandatory |
| Your Test Key |
txnid |
Note: Ensure that the transaction ID sent to us has not been successful earlier. In case of this duplication, the customer would get an error of 'duplicate Order ID.' | fd3e847h2 |
amount |
Note: Type-cast the amount to float type
| 1000 |
productinfo |
| Time Magazine Subscription |
firstname |
| Ashish |
email |
| |
phone |
This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information Also, MIS reporting is shared with few issuing banks where email and mobile number is used to keep track of users using SI transactions. | 9843176540 |
api_version | This parameter must always needs to be passed as 7. | 7 |
si | This parameter must be passed with the value as 2 to modify an already existing subscription/consent. | 3 |
pg |
| |
bankcode | Each payment option is identified with a String unique bank code at PayU. The merchant must post this parameter with the corresponding payment option's bank code value in it. For more information, refer to Card Type Codes and Supported Banks for Cards | |
user_credentials |
| a:b |
store_card_token |
| 1234 4567 2456 3566 |
free_trial | This is mandatory only if the merchant wants to support free trial use case with card and net banking together that too on PayU Hosted Checkout integration. In this case, PayU adjusts the transaction amount as INR 2.00 for cards. INR 0.00 for Net Banking and UPI registration irrespective of what amount is passed against the amount field in the request. | |
si_details | This parameter represents mandatory details which need to be passed to during registration transaction from merchant system to PayU. Note: It is mandatory as per the latest RBI guidelines to pass this information to the payment processor so that same can be forwarded to acquirers and issuers ( for more details refer – https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=11668&Mode=0 ) This is a JSON object and it includes a set of parameters are described in the the si_details Parameter Description table. | Refer the example below the si_details Parameter Description table. |
hash | Hash is a crucial parameter used to ensure that any date is not tampered while redirecting customer from the merchant website to PayU's payment interface while registration transactions. It is SHA512 hash generated by encrypting values of merchant key, txnid, amount, productinfo, firstname, email, udf and si_details by merchant salt. In the case of registration transaction, the formula is used to calculate this hash is similar to the following: |
For network tokens
This is applicable for the following scenarios:
- Merchant has the card token, TAVV(Cryptogram), and the last four digits of the card
- The token could be created by the merchant or through another partner
Note:
This scenario is applicable if you are PCI compliant and got the network token and TAVV from any other aggregator or schemes and then sent the card transaction request in the form of authentication.
Parameter | Description | Value |
---|---|---|
store_card_token mandatory |
| 1234 4567 2456 3566 |
storecard_token_type |
| 1 |
additional_info |
|
|
Notes for additional_info parameter:
The JSON format contains the following fields:
- trid (Token Requestor ID) is the identity given by the networks for creating the tokens. You should be able to get the same from your token provider.
- tokenRefNo (Token Reference Number) is generated along with the network token. . You should be able to get the same from your token provider.
- TAVV is a token authentication verification value given by schemes or interchange. Also, known as cryptogram.
Additional notes:
- The last 4 digits of cards is mandatory for all transactions.
- Some payment gateways require the Token Requester ID (trid) and Token Reference Number (tokenRefNo) to be passed for processing the transaction. Not passing these values will restrict the number of payment gateways available for processing the transaction.
- Token Requester ID (trid) and Token Reference Number (tokenRefNo) are mandatory for Diners token transactions.
si_details Parameter – JSON Details
The description for the si_details parameter (JSON format):
Note:
If the request was to modify a subscription, si_consent_action parameter needs to be validated in the response. The field must return values modify based on the action sent in billing details JSON. Also, the payment source returned in such cases will be payu.
JSON Field | Description | Example |
---|---|---|
billingCycle mandatory | Billing Cycle defines whether the customer needs to be charged over Daily, Weekly basis, Monthly or Yearly basis or one time. | ONCE |
billingInterval | Billing Interval is closely coupled with the billingCycle field and denotes at what frequency, the subscription plan needs to be executed. For monthly subscriptions, parameter values need to be sent in the request are:
Similarly, by keeping the following values, customer will be charged once in every 3 days:
|
|
billingAmount | The billing amount is passed in XX. XX format. | INR 2000 |
billingCurrency | This field must be passed as "INR" . | INR |
paymentStartDate | The start date of the billing plan is specified in this field with the YYYY-MM-DD format. Note: All the subsequent recurring transactions will be processed from this date onwards as per billingCycle and billingInterval fields combination. This date acts as reference point for recurring payments. Note: In case of UPI, send the current date here and any other value will be ignored. | 2022-02-14 |
paymentEndDate | The end date of the billing plan is specified in this field with the YYYY-MM-DD format. Note: Pass the correct end date to PayU. Depending upon start date and end date, number of payment iterations are internally calculated and same information is passed to acquirers or banks. | 2023-01-14 |
siTokenRequestor | This is optional and is only needed before 30th September, 2022 to activate new mandate setups in a controlled manner than activating it completely on all users. This involves creating token at the time of susbcription set. You can include any of the following values::
| 1 |
remarks | This field is used to provide remarks on PSP applications during the registration transaction of UPI. For cards and Net Banking, this parameter has no significance. Character limit = 50. Note: This field is applicable only for UPI. | Subscription for a year |
billingLimit | For UPI, this field is used to decide the period corresponding which the debit from the mandate recurring date can happen and this mandate registration date is confirmed during registration transaction of UPI. Note: This field is applicable only for UPI.
Note: If no value is passed, 'AFTER' is considered by default. | ON = 2022-02-20 |
billingRule | For UPI, this field is used to decide the limitation on the amount of recurring debit against the mandate amount which is set during registration transaction of UPI. Note: This field is applicable only for UPI.
Note: If no value is passed, 'MAX' is considered by default. | MAX = 5000 |
billingDate | Applicable for UPI only: This field is used to decide the date/day, basis which the recurring debit should happen. This can be ignored and the debit will happen as per the start date in every cycle. | FORTNIGHTLY = 7 |
authpayuid | This field is used only to modify an existing subscription/consent. Modification means modifying billing details like startDate, endDate, billing cycle, billing interval, billing amount. | |
action | This field is used to modify or cancel an existing subscription. Include modify to modify a subscription. | modify |
si_details JSON example
For a yearly plan starting from 1st January 2019, having a monthly billing amount of INR 100, the plan details:
{
"billingAmount": "10.00",
"billingCurrency": "INR",
"billingCycle": "MONTHLY",
"billingInterval": 1,
"paymentStartDate": "2022-02-04",
"paymentEndDate": "2022-12-12",
"action": "modify",
"authPayuId": "123"
}
Sample request
curl -X POST "https://test.payu.in/_payment" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "key=JP**g&txnid=56bb2e3fcb510f1c1521&amount=10000&firstname=Payu-Admin&[email protected]&phone=1234567890&productinfo=iPhone&api_version=7&si=3&pg=CC&bankcode=UTIBENCC&surl=https://test.payu.in/admin/test_response&furl=https://test.payu.in/admin/test_response&ccnum=5123456789012346&ccexpmon=05&ccexpyr=2022&ccvv=123&ccname=Test User&si_details={"billingAmount": "100.00","billingCurrency": "INR","billingCycle": "MONTHLY","billingInterval": 1,"paymentStartDate": "2022-09-01","paymentEndDate": "2022-12-01","authpayuid" : "403993715525316543","action":"modify"}&hash=e36568b2dfc460eab0eb3387fb7d90543ed861154f273b9593d6fcc152ed93a91e529c2f4be0965eeb57104e82d58889fa5efb52811ec78cbd1ad646e39c29a0"
Sample response
Array
(
[mihpayid] => 403993715525316543
[mode] => CC
[status] => success
[unmappedstatus] => captured
[key] => JP***g
[txnid] => eF5yY4ArrynoIV
[amount] => 10.00
[cardCategory] => domestic
[discount] => 0.00
[net_amount_debit] => 10
[addedon] => 2022-02-02 15:15:07
[productinfo] => iPhone
[firstname] => Ashish
[lastname] =>
[address1] =>
[address2] =>
[city] =>
[state] =>
[country] =>
[zipcode] =>
[email] => [email protected]
[phone] => 9876543210
[udf1] =>
[udf2] =>
[udf3] =>
[udf4] =>
[udf5] =>
[udf6] =>
[udf7] =>
[udf8] =>
[udf9] =>
[udf10] =>
[hash] => 499fa5f6d9019cc7bda9750b18bf3ba52f161da42cb065cab094595cb9d1c90058a3f1c7f3fcb057c371baa077052522847826be269060140580a7c345206020
[field1] => 4296837871969451239257
[field2] => 601248
[field3] => 10.00
[field4] => 403993715525316543
[field5] => 100
[field6] => 02
[field7] => AUTHPOSITIVE
[field8] =>
[field9] => Transaction is Successful
[payment_source] => payu
[PG_TYPE] => CC-PG
[bank_ref_num] => 4296837871969451239257
[bankcode] => CC
[error] => E000
[error_Message] => No Error
[name_on_card] => payu
[cardnum] => 512345XXXXXX2346
[cardhash] => This field is no longer supported in postback params.
)