Redemption – Callback

This callback will be received via POST method.

Merchants can configure the Webhook/S2S Callback URLs along with username & password.

PROD – Merchants can configure URL, Username and Password on the PhonePe dashboard.

• URL – Merchant’s Webhook URL
• Username – Merchant configure their own username
• Password – Merchant configure their own password
  Note: Merchants should ensure the configured username and password is being used in the code to validate the Authorization header.

UAT – Merchants can reach out to the Integration Team.

• Once the username and password is configured, PhonePe will pass the same SHA256 (username:password) as the “Authorization” header in s2s response.
• Merchants should calculate using the same logic and match with the one passed by PhonePe. If both are matching, then the response payload can be consumed by the merchant. Otherwise, merchants should ignore the response.

Callback Validation/Verification

For the incoming request, extract the basic authorization header “Authorization”, verify it with the one which you have shared with us and accept the response if Username and password matches.

Authorization : SHA256(username:password)

Callback Types

Key Notes

• Merchants should rely only on the root level “payload.state” parameter for the status confirmation.
• Avoid Strict Deserialization
• Don’t rely on “type” parameter in the webhook response (This will be deprecated) instead rely on the “event” parameter only for the webhook event name.
• expireAt and timestamp parameters will be a epoch timestamp ( in milliseconds)

Callbacks – Notification

Notification Success

Note: Merchants should rely only on the highlighted “payload.state” parameter for the Notitication status confirmation.

{
  "type": "SUBSCRIPTION_NOTIFICATION_COMPLETED",
  "payload": {
    "merchantId": "SWIGGY8",
    "merchantOrderId": "MO1708797962855",
    "orderId": "OMO12344",
    "amount": 100,
    "state": "NOTIFIED",
    "expireAt": 1620891733101,
    "paymentFlow": {
      "type": "SUBSCRIPTION_REDEMPTION",
      "merchantSubscriptionId": "MS121312",
      "redemptionRetryStrategy": "CUSTOM",
      "autoDebit": true,
      "validAfter": 1628229131000,
      "validUpto": 1628574731000,
      "notifiedAt": 1622539751586
    }
  }
}

Callbacks – Redemption

Sample Callback for Redeemed state

Note: Merchants should rely only on the highlighted “payload.state” parameter for the payment status confirmation.

{
  "type": "SUBSCRIPTION_REDEMPTION_ORDER_COMPLETED/SUBSCRIPTION_REDEMPTION_ORDER_FAILED",
  "payload": {
   "merchantId": "SWIGGY8",
    "merchantOrderId": "MO1708797962855"
    "orderId": "OMO12344",
    "state": "COMPLETED",
    "amount": 100,
   "expireAt": 1620891733101,
    "paymentFlow": {
      "type": "SUBSCRIPTION_REDEMPTION",
      "merchantSubscriptionId": "MS121312",
      "redemptionRetryStrategy": "CUSTOM",
      "autoDebit": true,
      "validAfter": 1628229131000,
      "validUpto": 1628574731000,
      "notifiedAt": "1622539751586"
    },
    "errorCode": <PRESENT ONLY IF STATE IS FAILED>
    "detailedErrorCode": <PRESENT ONLY IF STATE IS FAILED>  
    "paymentDetails": [
        {
            "amount": 100
            "paymentMode": "UPI_AUTO_PAY",
            "timestamp": 1620891733101      
            "transactionId": "OM124",
            "state": "COMPLETED", // FAILED, PENDING
            "rail": {
                "type": "UPI",
                "utr": "2",
                "vpa": "abcd@ybl",
                "umn": "544fcc8819d04cb08e26faa1fb07eee7@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "XXX2312",
                "ifsc": "VISA",
                "accountHolderName": "Venkat",
                "accountType": "SAVINGS"
            },
            "errorCode": <PRESENT ONLY IF ATTEMPT IS FAILED>
           "detailedErrorCode": <PRESENT ONLY IF ATTEMPT IS FAILED>
        }
    ]
  }
}

Sample Callback for Redemption Attempt

{
  "type": "SUBSCRIPTION_REDEMPTION_TRANSACTION_COMPLETED/SUBSCRIPTION_REDEMPTION_TRANSACTION_FAILED",
  "payload": {
   "merchantId": "SWIGGY8",
    "merchantOrderId": "MO1708797962855"
    "orderId": "OMO12344",
    "state": "PENDING",
    "amount": 100,
   "expireAt": 1620891733101,
    "paymentFlow": {
      "type": "SUBSCRIPTION_REDEMPTION",
      "merchantSubscriptionId": "MS121312",
      "redemptionRetryStrategy": "CUSTOM",
      "autoDebit": true,
      "validAfter": 1628229131000,
      "validUpto": 1628574731000,
      "notifiedAt": 1622539751586
    },
    "errorCode": <PRESENT ONLY IF STATE IS FAILED>
    "detailedErrorCode": <PRESENT ONLY IF STATE IS FAILED>  
    "paymentDetails": [
        {
            "amount": 100
            "paymentMode": "UPI_AUTO_PAY",
            "timestamp": 1620891733101      
            "transactionId": "OM124",
            "state": "COMPLETED", // FAILED, PENDING
            "rail": {
                "type": "UPI",
                "utr": "2",
                "vpa": "abcd@ybl",
                "umn": "544fcc8819d04cb08e26faa1fb07eee7@ybl"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "XXX2312",
                "ifsc": "VISA",
                "accountHolderName": "Venkat",
                "accountType": "SAVINGS"
            },
            "errorCode": <PRESENT ONLY IF ATTEMPT IS FAILED>
           "detailedErrorCode": <PRESENT ONLY IF ATTEMPT IS FAILED>
        }
    ]
  }
}