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 and user action is completed, you will get the control back to the merchant app. Post that 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 and the status might reach the terminal state in some time. For such transactions, the following Recon process has to be setup.

Guidelines for Recon Process

1. Post the auth/init call and receiving UI control back to the merchant app,

• Merchant app should check with their backend server if the S2S callback is received.
• If the S2S callback is not received, then Merchant should initiate a recon process by calling status check API (auth/status) with 5 minutes time intervals and check until the terminal status is reached. Meanwhile, if the S2S callback is received, merchants can update the status and remove the transaction from Recon Scheduler.

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.