Redemption – Notify

This is the second part post Subscription setup to charge the Redemption amount as per the subscription cycle chosen.

Redemption has 2 steps:

Notify: This step is used to notify the user about the next payment debit.
Execute: This step is to debit the amount from the user.

Notify

Host Details

Environment	Value
`UAT`	https://api-preprod.phonepe.com/apis/pg-sandbox
PROD	https://api.phonepe.com/apis/pg

API Endpoint

/subscriptions/v2/notify

Complete Host URL

Http Method: POST

Environment	Value
`UAT`	https://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/notify
PROD	https://api.phonepe.com/apis/pg/subscriptions/v2/notify

Request Details

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`Authorization`	O-Bearer <access_token>

Note: access_token can be generated using the Auth Token API. Refer here

Request Parameters

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`merchantOrderId`	STRING	Unique merchant order id generated by merchant	Yes	Max Length = 63 characters No Special characters allowed except underscore “_” and hyphen “-“
`amount`	LONG	Order amount in paisa	Yes	The MAXIMUM debit/redemption amount for the mandate. The amount is in Paise. Note: ● For VARIABLE recurring debit, this amount would be considered as Max Cap Amount ● For PENNY_DROP flow, the amount should be greater than or equal to 200 (In Paise) ● For TRANSACTION flow, the amount should be greater than or equal to 100 (In Paise)
`expireAt`	DateTime	Order expireAt epoch after which order will auto fail/skipped if not terminal. (in milliseconds)	No	Default Value – 48 hours
`paymentFlow.type`	STRING	Type of payment flow	Yes	Possible Values ● SUBSCRIPTION_REDEMPTION
`paymentFlow.merchantSubscriptionId`	STRING	Merchant reference subscription ID passed during setup of the subscription	Yes
`paymentFlow.redemptionRetryStrategy`		Redemption retry strategy in case attempts fail	No	Possible Values: ● STANDARD – Internal retries ● CUSTOM – Merchant needs to retry. Default Value – STANDARD
`paymentFlow.autoDebit`		Auto debit redemption 24 hours after notify success Can’t be true for CUSTOM redemptionRetryStrategy	No	Possible Values – true false Default Value – false
`metaInfo`		User defines fields propagated in status check & callbacks	No	Default Value – null

Send the above payload and headers to the API via HTTP POST method.

Sample Payload

{
  "merchantOrderId": "MO1709025691805",
  "amount": 1000,
  "expireAt": 1620891733101,
  "metaInfo": {
    "udf1": <some meta info of max length 256>
    "udf2": <some meta info of max length 256>
    "udf3": <some meta info of max length 256>
    "udf4": <some meta info of max length 256>
    "udf5": <some meta info of max length 256>
  }  
  "paymentFlow": {
    "type": "SUBSCRIPTION_REDEMPTION",
    "merchantSubscriptionId": "MS121312",
    "redemptionRetryStrategy": "CUSTOM",
    "autoDebit": true
  }
}

Note:

If paymentFlow.redemptionRetryStrategy is passed as CUSTOM, then merchants has to retry the redemption until you get COMPLETED/FAILED (Terminal Status) . Maximum Time window for getting the terminal status is 48 hours and Maximum of 10 retries are allowed.
If paymentFlow.redemptionRetryStrategy is passed as STANDARD, then PhonePe will take care of the internal retires for redemption. Maximum Time window for getting the terminal status is 48 hours and these retries are handled by PhonePe internally.
Default Value – STANDARD

Sample CURL

curl --location 'https://api-preprod.phonepe.com/apis/pg-sandbox/subscriptions/v2/notify' \
--header 'Accept: application/json' \
--header 'Authorization: O-Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MTIyNTM2MjU2NDQsIm1lcmNoYW50SWQiOiJWMlNVQlVBVCJ9.7aVzYI_f_77-bBicEcRNuYx093b2wCsgl_WFNkKqAPY' \
--header 'Content-Type: application/json' \
--data '{
 "merchantOrderId": "MO1709025691805",
 "amount": 1000,
 "expireAt": 1620891733101,
 "paymentFlow": {
   "type": "SUBSCRIPTION_REDEMPTION",
   "merchantSubscriptionId": "MS121312",
   "redemptionRetryStrategy": "CUSTOM",
   "autoDebit": true
 }
}'

Response from the API

{
    "orderId" : "OMO12344",
    "state" : "NOTIFICATION_IN_PROGRESS",
    "expireAt": 1707116484762
}

Response Parameters

Field Name	Description
`orderId`	PhonePe reference order ID
`state`	Order state
expireAt	Expiry in Epoch Timestamp (in milliseconds)