Handling Callbacks and Recons

In order to set up the subscription, merchants create a subscription entity and then makes a call to auth/init API to setup the mandate and setup the subscription, Once the transaction is initiated,

  1. Merchants should wait for the S2S callback up to 15 mins.

  2. Post 15 mins, if S2S callback is not received, the Merchant should verify the Subscription state using the status check API (auth/status).

There are three scenarios possible:

  1. Success Scenario
  2. Failure Scenario
  3. Pending Scenario

Success Scenario

When the subscription is set up successfully, expect to receive an S2S callback with the following payload.

Subscription “Auth” callback payload

{
    "response": "ewogICAic3VjY2VzcyI6dHJ1ZSwKICAgImNvZGUiOiJTVUNDRVNTIiwKICAgIm1lc3NhZ2UiOiJZb3VyIHN1YnNjcmlwdGlvbiBpcyBhY3RpdmUuIiwKICAgImRhdGEiOnsKICAgICAgImNhbGxiYWNrVHlwZSI6IkFVVEgiLAogICAgICAibWVyY2hhbnRJZCI6Ik1JRDEyMzQ1IiwKICAgICAgImF1dGhSZXF1ZXN0SWQiOiI4YWU0YjhmNjdhMGMyZDM3MDE3YTEzYzJhOGExNWFkMyIsCiAgICAgICJ0cmFuc2FjdGlvbkRldGFpbHMiOnsKICAgICAgICAgInByb3ZpZGVyUmVmZXJlbmNlSWQiOiJUMjEwNjE2MTMxMzM1MDIzODY5MDg3MyIsCiAgICAgICAgICJhbW91bnQiOjM5OTAwLAogICAgICAgICAic3RhdGUiOiJDT01QTEVURUQiLAogICAgICAgICAicGF5UmVzcG9uc2VDb2RlIjoiU1VDQ0VTUyIsCiAgICAgICAgICJwYXltZW50TW9kZXMiOlsKICAgICAgICAgICAgewogICAgICAgICAgICAgICAibW9kZSI6IkFDQ09VTlQiLAogICAgICAgICAgICAgICAiYW1vdW50IjozOTkwMCwKICAgICAgICAgICAgICAgInV0ciI6IjgxNjYyNjUyMTYxNiIKICAgICAgICAgICAgfQogICAgICAgICBdCiAgICAgIH0sCiAgICAgICJzdWJzY3JpcHRpb25EZXRhaWxzIjp7CiAgICAgICAgICJzdWJzY3JpcHRpb25JZCI6Ik9NUzIwMDYxMTAxMzk0NTAxMjM0NTY3ODkiLAogICAgICAgICAic3RhdGUiOiJBQ1RJVkUiCiAgICAgIH0KICAgfQp9"
}
{
   "success":true,
   "code":"SUCCESS",
   "message":"Your subscription is active.",
   "data":{
      "callbackType":"AUTH",
      "merchantId":"MID12345",
      "authRequestId":"8ae4b8f67a0c2d37017a13c2a8a15ad3",
      "transactionDetails":{
         "providerReferenceId":"T2106161313350238690873",
         "amount":39900,
         "state":"COMPLETED",
         "payResponseCode":"SUCCESS",
         "paymentModes":[
            {
               "mode":"ACCOUNT",
               "amount":39900,
               "utr":"816626521616"
            }
         ]
      },
      "subscriptionDetails":{
         "subscriptionId":"OMS2006110139450123456789",
         "state":"ACTIVE"
      }
   }
}

To mark a subscription as active or success at the merchant's end the following condition can be
checked:

👍

success == true and
data.transactionDetails.state == "COMPLETED" and
data.subscriptionDetails.state == "ACTIVE"

Failure Scenario

When the subscription setup fails due to any reason, expect to receive an S2S callback with the
following payload.

Subscription “Auth” callback payload

{
    "response": "ewogICAic3VjY2VzcyI6dHJ1ZSwKICAgImNvZGUiOiJTVUNDRVNTIiwKICAgIm1lc3NhZ2UiOiJZb3VyIHN1YnNjcmlwdGlvbiBpcyBmYWlsZWQuIiwKICAgImRhdGEiOnsKICAgICAgImNhbGxiYWNrVHlwZSI6IkFVVEgiLAogICAgICAibWVyY2hhbnRJZCI6Ik1JRDEyMzQ1IiwKICAgICAgImF1dGhSZXF1ZXN0SWQiOiI4YWU0ZTY5NjdhMGMyZDQyMDE3YTEzYzhhMGU4NjJkZCIsCiAgICAgICJ0cmFuc2FjdGlvbkRldGFpbHMiOnsKICAgICAgICAgImFtb3VudCI6Mzk5MDAsCiAgICAgICAgICJzdGF0ZSI6IkZBSUxFRCIsCiAgICAgICAgICJwYXlSZXNwb25zZUNvZGUiOiJBVVRIT1JJWkFUSU9OX0ZBSUxFRCIKICAgICAgfSwKICAgICAgInN1YnNjcmlwdGlvbkRldGFpbHMiOnsKICAgICAgICAgInN1YnNjcmlwdGlvbklkIjoiT01TMjEwNjE2MTMxNTUzNTA0ODExNDY0OCIsCiAgICAgICAgICJzdGF0ZSI6IkZBSUxFRCIKICAgICAgfQogICB9Cn0="
}
{
   "success":true,
   "code":"SUCCESS",
   "message":"Your subscription is failed.",
   "data":{
      "callbackType":"AUTH",
      "merchantId":"MID12345",
      "authRequestId":"8ae4e6967a0c2d42017a13c8a0e862dd",
      "transactionDetails":{
         "amount":39900,
         "state":"FAILED",
         "payResponseCode":"AUTHORIZATION_FAILED"
      },
      "subscriptionDetails":{
         "subscriptionId":"OMS2106161315535048114648",
         "state":"FAILED"
      }
   }
}

To mark a subscription failed at the merchant's end the following condition can be checked:

❗️

success == true and
data.transactionDetails.state == "FAILED" and
data.subscriptionDetails.state == "FAILED"

Pending Scenario

There are a few scenarios when the subscription can be in the pending state,

  1. S2S callback is not received at all within 15 mins.

In such cases, the merchant should call the status API (auth/status) as part of the recon process. The status check API also gives the same payload in response and terminal conditions can be checked as mentioned above.

Guidelines for Recon Process

  1. Post the auth/init call, wait for the S2S callback for 15 mins.

  2. Post 15 mins, initiate a recon process by calling status check API (auth/status) with 5 minutes time intervals and check the terminal conditions.

Post 30 minutes if the state is still pending, the merchant can mark the transaction as failed.

🚧

Validations

Validate the amount and checksum which has been passed in the payment request with the response received in the Server to Server callback.