API Reference
Start typing to search…

Update SI API

API Command: update_SI

The Update SI API allows you to perform the following:

  • RBI Tokenization guideline for 30th June requires every subscription card to be tokenized. Hence, this API must be used to update the subscription with the network token. 
  • This API updates subscriptions with network tokens when PayU is not the token requestor. Merchants must tokenize the card (within T+4 where T is the date of transaction) and share the token through this API after receiving the authorization response.
  • For cases where PayU is the token requestor, PayU will do the bulk migration on behalf of merchant. So, this API should not be implemented for such cases. PayU will share the migration result in an excel format to merchants.

📘

Notes:

  • This API is helpful for migrating mandates to achieve the 30th June deadline to update card numbers with tokens for subscription setups. 
  • This API should be used where tokenizing the subscription card is not done by PayU but rather by a different token requestor.

Request Parameters

Parameter

Description

Example

key  mandatory

This parameter is the unique Merchant Key provided by PayU for your merchant account. The Merchant Key acts as the unique identifier (primary key) to identify a Merchant Account in our database. 

YbfVda

command 
mandatory

The value of the parameter will be passed as “subscription_with_payu”

update_SI

var1 
mandatory

This parameter is in a JSON format as described in the JSON Fields in var1 section.

Refer to the JSON Fields in var1 section.

hash 
mandatory

The 512 SHA hash strings generated by encrypting request parameters so that any tampering can be avoided.  The format of the is similar to the following:
hash = sha512(key|command|var1|SALT)

a6105d0e5c8726fd37713d02ace8f63652bfe1337f14e4a3652084ba9787e4ee601a503bcc42ba101fb1c378b910d5637e9806b92fc89322db01806 97ff906b3

JSON Fields in var1

The sample JSON in the var1 parameter is similar to the following:

{
'authPayuId': '10731087875',
'requestId': '23123abut12123osd14',
'isExistingMandate':'1',
'token':{
'type': 'network',
'number':'5506900490467221',
'expiry_month':'10',
'expiry_year':'2022',
'tsp':'002'
}
}

The description for the fields in the JSON are:

Field

Description

authPayuId mandatory for cards 

The value of mihpayid returned in the payment response of Registration transaction when transaction is successfully completed. As explained earlier in the document, merchant needs to map this value against consumer profile at his end so that correct authPayuid will be passed in the request.

requestId
mandatory for cards

Unique request value generated at merchant’s end to distinguish independent request call.

isExistingMandate
mandatory for cards

This field must be passed with value as 1.

token
mandatory for cards

The value for this parameter is in a JSON format and includes the following:
type: This must contain the token type of the token generated for the card earlier. Value should be network

  • number: This is the network token returned at the time of tokenising the card post successful payment.
  • expiry_month: This is the expiry month of the token. For example, 01, 02, 11, 12.
  • expiry_year: This is the expiry year of the token. For example, 2022, 2023, 2028.
    tsp: This is the type of scheme/ network and you need to pass the values according to card network:
    - VISA: Pass 001 for this card network
    - Mastercard: Pass 002 for this card network
  • *Note**: The above fields are mandatory for cards.

siTokenRequestor
optional

This field can include any of the following values:

- 1: PayU will tokenize the card and share it in same subscription setup call with issuers for subscription setup.

  • 2: PayU will do the authorization on plain card. Then, the same response will be shared to merchant. Merchant will now use the update_SI API (link) to update the token.

Sample request

curl --location --request POST 'https://test.payu.in/merchant/postservice?form=2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'key=JPM7Fg' \
--data-urlencode 'command=update_SI' \
--data-urlencode 'var1={"authPayuId":"403993715526578563","requestId":"updateApiTest0123","isExistingMandate":"1","token":{"type":"network","number":"5506900490764569","expiry_month":"05","expiry_year":"2025","tsp":"001"}}' \
--data-urlencode 'hash=20a150189af9c86b3029136a5bd8bf01ba7feb35a65682baca1f6452cd5310d6b261cdfa4e621d7f4e211915b657a99bd7ce7d57ba076888dad683867760d8c5'

Response parameters

Parameter

Description

status

The status defines acknowledgement from PayU. The possible values are: 

  • 1: This value indicates that migration was successful.
  • 0: This value indicates that migration was not successful.

authPayuId

This is the subscription registration id that is used as reference for subscription and was returned at the time of subscription setup.

message

The message will be listed here for successful and failure reason.

Sample response

Success scenario

{ 
"status": 1, 
"authPayuId": "490490459", 
"message": "Request Processed Successfully" 
}

Failure scenarios

  • Failed to update network token

Failed to update network token

{ 
"status": 0, 
"authPayuId": "490490459", 
"message": "Failed to update network token" 
}
  • Mandate is not active

Mandate is not active

{ 
"status": 1, 
"authPayuId": "490490459", 
"message": "Mandate is not active" 
}