Pause or Unpause Subscription

Customers can Pause/Unpause their subscription anytime by going to the Autopay section in their PSP (Payment Service Provider) app and selecting “Pause/Unpause” for the active mandate. When this happens, the subscription will be Paused/Unpaused, and PhonePe will send an Webhook callback to notify you that the subscription has been paused/unpaused from the customer’s end.

Webhook Setup & Configuration

You can configure your webhook using one of two authentication methods. Both methods follow the same initial setup but require slightly different details on the configuration form.

• Using Basic Authentication (SHA): A method where a configured username and password are hashed (SHA-256) and sent in the authorization header.
• Using HMAC Authentication: A secure approach that allows the receiver to verify both the authenticity and integrity of the payload using a shared secret key.

Configuration Steps

Follow these steps to set up your webhook:

• Log in to your PhonePe Business Dashboard.
• Set the Environment Mode using the Test Mode toggle on the dashboard:
  • Sandbox (Testing): Switch the toggle ON.
  • Production (Live): Switch the toggle OFF.
• Navigate to Developer Settings from the side menu.
• Select the Webhook tab and click the Create Webhook button.
• Fill in the Configuration Details based on your preferred authentication type:
  • Option A: HMAC
    • Select Authentication Type as HMAC.
    • Provide your Webhook URL (your server’s endpoint), select the Events you wish to subscribe to, and add a brief Description.
    • Secret Key Generation: Once you click create, a Secret Key will be automatically generated. You can view and access this key at any time by clicking on the created webhook in your dashboard.
    • Editing the Webhook: You can edit an existing webhook at a later time; however, you will only be able to update the Webhook URL, selected Events, and Description.
  • Option B: SHA (Username & Password)
    • Select Authentication Type as SHA.
    • Provide your Webhook URL, Username, Password, and a brief Description.
    • Select Active Events.
• Click Create to save. Your webhook is now active!

Authorization & Verification

How you verify incoming webhooks depends on the method you chose:

If you chose HMAC:

• Credentials: Upon creation of the HMAC webhook, a Checksum Secret Key and a Webhook ID will be generated. You must save these securely on your end.
• Authorization: During the transactional flow, PhonePe encrypts the plain text payload using the secret key and transmits two specific parameters in the headers:
  • The generated checksum X-phonepe-checksum-key-id
  • The phonepe-checksum-signature value.

Verification:

• When your server receives the plain text payload, extract the x-phonepe-checksum-key-id and x-phonepe-checksum-signature headers.
• Use the x-phonepe-checksum-key-id to identify and retrieve the specific Checksum Secret Key you saved earlier.
• Generate your own checksum by encrypting the received plain text payload with that Secret Key.
• Compare your generated checksum against the x-phonepe-checksum-signature header. If they match, the payload is valid and authentic. If they do not match, you must reject the payload.

If you chose SHA:

• Authorization: PhonePe will use your configured credentials to create an Authorization header in the webhook response using the SHA256(username:password) method.
• Verification: For incoming requests, extract the Authorization header. Generate your own hash using the username and password you configured and compare it. If the hashes match, the update is valid. If they do not match, the response should be ignored.

Supported Events

Select only the specific events you need to reduce unnecessary server load and processing “Events.”

Responses

{
    "type": "SUBSCRIPTION_PAUSED",
    "payload": {
        "merchantSubscriptionId": "MS1708797962855",
        "subscriptionId": "OMS2402242336054995042603",
        "state": "PAUSED",
        "authWorkflowType": "TRANSACTION",
        "amountType": "FIXED",
        "maxAmount": 200,
        "frequency": "ON_DEMAND",
        "expireAt": 1737278524000,
        "pauseStartDate": 1708798426196,
        "pauseEndDate": 1708885799000
    }
}

{
    "type": "SUBSCRIPTION_UNPAUSED",
    "payload": {
        "merchantSubscriptionId": "MS1708797962855",
        "subscriptionId": "OMS2402242336054995042603",
        "state": "ACTIVE",
        "authWorkflowType": "TRANSACTION",
        "amountType": "FIXED",
        "maxAmount": 200,
        "frequency": "ON_DEMAND",
        "expireAt": 1737278524000,
        "pauseStartDate": null,
        "pauseEndDate": null
    }
}

UNPAUSE Subscription

User can pause/unpause via the PSP app where the mandate was originally set up. You will not be able to unpause the subscription.

• If you receive a pauseEndDate in the Pause Callback and that date has passed, you can unpause the subscription automatically.
• If Redemption Notify has been successfully completed and then the user pauses the subscription, redemption cannot be executed while the subscription is paused.
• After a successful Redemption Notify, if the user pauses and then unpauses the subscription, you cannot execute redemption immediately. You need to send Redemption Notify again, and then execute redemption only after 24 hours from the successful notification.
• You can cancel or revoke the mandate even when the subscription is in the paused state.

Best Practice:
Before calling Redemption Notify or Redemption Execute, always check the subscription status using the Subscription Status API. Proceed only if the subscription state is ACTIVE to avoid failures.

What’s Next?

Now that you’ve learned how to pause and unpause an active subscription, the next step is to understand how to revoke an active subscription.