To set up the mandate or accept the first payment from the user on the iOS Platform

Quick Links

Subscription Flow TypeLink to Refer
Subscription - PhonePe Intent FlowSubmit Auth Request - PhonePe Intent Flow
Request ParametersSubmit Auth Request - Request Parameters
Response ParametersSubmit Auth Request - Response Parameters
S2S CallbackSubmit Auth Request - S2S Callback
Integration Steps on App Side (iOS)Submit Auth Request - Integration Steps on App Side

Headers

FieldMandatoryDescription
Content-TypeYesapplication/json
X-VerifyYesSHA256(base64 encoded payload + "/v3/recurring/auth/init" + salt key) + ### + salt index
X-CALLBACK-URLYesThe callback URL to receive the server to server callback response.
X-CALL-MODEYesValue will be POST.

Subscription - PhonePe Intent Flow

{  
  "merchantId" : "MERCHANTUAT",
  "subscriptionId" : "OMS2301191527473651197003",  
  "merchantUserId" : "5330F4FB-C66C-4646-8691-11544B580547",
  "message" : "Payment towards order No. OD139924923",
  "authRequestId" : "D2500CEFBBE481095A43D6D5B7A787F",
  "paymentScope" : "PHONEPE",
  "deviceContext" : {
    "deviceOS" : "IOS",
    "merchantCallBackScheme" : "iOSIntentIntegration",
    "isPPAppPresent" : true
  }
}
{  
  "merchantId" : "MERCHANTUAT",
  "subscriptionId" : "OMS2301191527473651197003",  
  "merchantUserId" : "5330F4FB-C66C-4646-8691-11544B580547",
  "message" : "Payment towards order No. OD139924923",
  "authRequestId" : "D2500CEFBBE481095A43D6D5B7A787F",
  "paymentScope" : "PHONEPE",
  "amount" : 39900,
  "deviceContext" : {
    "deviceOS" : "IOS",
    "merchantCallBackScheme" : "iOSIntentIntegration",
    "isPPAppPresent" : true
  }
}
{
  "request":"e8KgIAogICJtZXJjaGFudElkIiA6ICJNRVJDSEFOVFVBVCIsCsKgICJzdWJzY3JpcHRpb25JZCIgOiAiT01TMjMwMTE5MTUyNzQ3MzY1MTE5NzAwMyIswqAgCsKgICJtZXJjaGFudFVzZXJJZCIgOiAiNTMzMEY0RkItQzY2Qy00NjQ2LTg2OTEtMTE1NDRCNTgwNTQ3IiwKwqAgIm1lc3NhZ2UiIDogIlBheW1lbnQgdG93YXJkcyBvcmRlciBOby4gT0QxMzk5MjQ5MjMiLArCoCAiYXV0aFJlcXVlc3RJZCIgOiAiRDI1MDBDRUZCQkU0ODEwOTVBNDNENkQ1QjdBNzg3RiIsCsKgICJwYXltZW50U2NvcGUiIDogIlBIT05FUEUiLArCoCAiYW1vdW50IiA6IDM5OTAwLArCoCAiZGV2aWNlQ29udGV4dCIgOiB7CsKgIMKgICJkZXZpY2VPUyIgOiAiSU9TIiwKwqAgwqAgIm1lcmNoYW50Q2FsbEJhY2tTY2hlbWUiIDogImlPU0ludGVudEludGVncmF0aW9uIiwKwqAgwqAgImlzUFBBcHBQcmVzZW50IiA6IHRydWUKwqAgfQp9"
}
{
   "request": "e8KgIAogICJtZXJjaGFudElkIiA6ICJNRVJDSEFOVFVBVCIsCsKgICJzdWJzY3JpcHRpb25JZCIgOiAiT01TMjMwMTE5MTUyNzQ3MzY1MTE5NzAwMyIswqAgCsKgICJtZXJjaGFudFVzZXJJZCIgOiAiNTMzMEY0RkItQzY2Qy00NjQ2LTg2OTEtMTE1NDRCNTgwNTQ3IiwKwqAgIm1lc3NhZ2UiIDogIlBheW1lbnQgdG93YXJkcyBvcmRlciBOby4gT0QxMzk5MjQ5MjMiLArCoCAiYXV0aFJlcXVlc3RJZCIgOiAiRDI1MDBDRUZCQkU0ODEwOTVBNDNENkQ1QjdBNzg3RiIsCsKgICJwYXltZW50U2NvcGUiIDogIlBIT05FUEUiLArCoCAiZGV2aWNlQ29udGV4dCIgOiB7CsKgIMKgICJkZXZpY2VPUyIgOiAiSU9TIiwKwqAgwqAgIm1lcmNoYW50Q2FsbEJhY2tTY2hlbWUiIDogImlPU0ludGVudEludGVncmF0aW9uIiwKwqAgwqAgImlzUFBBcHBQcmVzZW50IiA6IHRydWUKwqAgfQp9"
}

📘

Subscription - PhonePe Intent Flow

  • The value of "paymentScope" should be "PHONEPE".
  • The "deviceContext" should be passed. Refer to the function to fetch the deviceContext here
{
  "success": true,
  "code": "SUCCESS",
    "message": "Your request has been successfully completed.",
  "data": {
    "redirectType": "INTENT",
    "redirectURL": "ppe://mandate?pn=SUBSCRIBEMID&[email protected]&tid=YBL6663638d0312408a8f54f7df8f1bd6b9&tr=P1812191027266848105909&am=399.00&mam=399.00&cu=INR&url=https://phonepe.com&mc=7299&tn=Payment%20for%20TXN123456789&utm_source=TXN123456789&utm_medium=MID12345&utm_campaign=SUBSCRIBE_AUTH"
  }
}

Request Parameters

Field NameData TypeMandatoryDescription
merchantIdStringYesMID provide by PhonePe
merchantUserIdStringYesUser's unique Id maintained by merchant
subscriptionIdStringYesPhonePe subscription Id
authRequestIdStringYesMerchant's unique transaction Id
amountLongConditional● Mandatory when
authWorkflowType is
TRANSACTION

● Do not pass when
authWorkflowType is
PENNY_DROP
paymentScopeStringNoDefault: PHONEPE
● PHONEPE - for PhonePe Intent
deviceContextObjectYes
(Optional)
Mandatory for SDKLess
Intent flow. Refer to the function to fetch the deviceContext here
deviceContext.deviceOSStringYesValue will be "IOS"
deviceContext.merchantCallBackSchemeStringYesCallback Scheme for returning the control back to the merchant app

🚧

merchantCallBackScheme

The merchantCallBackScheme can be passed only for the PhonePe App ("paymentScope": "PHONEPE") that helps to open the merchant app after the completion of the Payment.

Response Parameters

Field NameData TypeDescriptionComments
redirectTypeStringValues:
● INTENT
redirectUrlStringAn intent url to launch the PhonePe app
codeString"SUCCESS",
"INTERNAL_SERVER_ERROR",
"SUBSCRIPTION_NOT_FOUND",
"SUBSCRIPTION_EXPIRED",
"INVALID_SUBSCRIPTION_STATE",
"BAD_REQUEST",
"INVALID_TRANSACTION_ID"

S2S Callback - Submit Auth Request

📘

Callback for Submit Auth Request

The server to server callback for Submit Auth Request will have the "callbackType": "AUTH".

🚧

Validations

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

S2S Callback - ACTIVE state

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

S2S Callback - FAILED state

{
   "response": "ewogICJzdWNjZXNzIjogdHJ1ZSwKICAiY29kZSI6ICJTVUNDRVNTIiwKICAibWVzc2FnZSI6ICJZb3VyIHN1YnNjcmlwdGlvbiBpcyBmYWlsZWQuIiwKICAiZGF0YSI6IHsKICAgICJjYWxsYmFja1R5cGUiOiAiQVVUSCIsCiAgICAibWVyY2hhbnRJZCI6ICJNSUQxMjM0NSIsCiAgICAiYXV0aFJlcXVlc3RJZCI6ICJUWDEyMzQ1Njc4OSIsCiAgICAidHJhbnNhY3Rpb25EZXRhaWxzIjogewogICAgICAicHJvdmlkZXJSZWZlcmVuY2VJZCI6ICJQMTgwNjE1MTMyMzA5MzkwMDU1NDk1NyIsCiAgICAgICJhbW91bnQiOiAzOTkwMCwKICAgICAgInN0YXRlIjogIkZBSUxFRCIsCiAgICAgICJwYXlSZXNwb25zZUNvZGUiOiAiQVVUSE9SSVpBVElPTl9GQUlMRUQiLAogICAgICAicGF5bWVudE1vZGVzIjogWwogICAgICAgIHsKICAgICAgICAgICJtb2RlIjogIkFDQ09VTlQiLAogICAgICAgICAgImFtb3VudCI6IDM5OTAwLAogICAgICAgICAgInV0ciI6ICI4MTY2MjY1MjE2MTYiCiAgICAgICAgfQogICAgICBdCiAgICB9LAogICAgInN1YnNjcmlwdGlvbkRldGFpbHMiOiB7CiAgICAgICJzdWJzY3JpcHRpb25JZCI6ICJPTVMyMDA2MTEwMTM5NDUwMTIzNDU2Nzg5IiwKICAgICAgInN0YXRlIjogIkZBSUxFRCIKICAgIH0KICB9Cn0="
}
{
  "success": true,
  "code": "SUCCESS",
  "message": "Your subscription is failed.",
  "data": {
    "callbackType": "AUTH",
    "merchantId": "MID12345",
    "authRequestId": "TX123456789",
    "transactionDetails": {
      "providerReferenceId": "P1806151323093900554957",
      "amount": 39900,
      "state": "FAILED",
      "payResponseCode": "AUTHORIZATION_FAILED",
      "paymentModes": [
        {
          "mode": "ACCOUNT",
          "amount": 39900,
          "utr": "816626521616"
        }
      ]
    },
    "subscriptionDetails": {
      "subscriptionId": "OMS2006110139450123456789",
      "state": "FAILED"
    }
  }
}

Integration Steps on App Side

  1. In your Info.plist, create or append a new Array type node LSApplicationQueriesSchemes to append the following values:
<array>
        <string>ppemerchantsdkv1</string>
        <string>ppemerchantsdkv2</string>
        <string>ppemerchantsdkv3</string>
</array>
2210
  1. Create a URLType for your app (Deeplink), if not already present.
    For example, we have used: iOSIntentIntegration. (You can create your own identifier for your app) and pass it in the deviceContext.merchantCallBackScheme of Submit Auth request.
2194