Submit Auth Request (iOS)

Sequence

Subscription Flow Type	Link to Refer
Subscription – PhonePe Intent Flow	Submit Auth Request – PhonePe Intent Flow
Request Parameters	Submit Auth Request – Request Parameters
Response Parameters	Submit Auth Request – Response Parameters
S2S Callback	Submit Auth Request – S2S Callback
Integration Steps on App Side (iOS)	Submit Auth Request – Integration Steps on App Side

Headers

Field	Mandatory	Description
`Content-Type`	`Yes`	application/json
`X-Verify`	`Yes`	SHA256(base64 encoded payload + “/v3/recurring/auth/init” + salt key) + ### + salt index
`X-CALLBACK-URL`	`Yes`	The callback URL to receive the server to server callback response.

Subscription – PhonePe Intent Flow

PhonePe Intent – When authWorkflowType is TRANSACTION

{  
  "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
  }
}

Convert the JSON Payload to Base64 Encoded Payload

The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.

{
  "request":"e8KgIAogICJtZXJjaGFudElkIiA6ICJNRVJDSEFOVFVBVCIsCsKgICJzdWJzY3JpcHRpb25JZCIgOiAiT01TMjMwMTE5MTUyNzQ3MzY1MTE5NzAwMyIswqAgCsKgICJtZXJjaGFudFVzZXJJZCIgOiAiNTMzMEY0RkItQzY2Qy00NjQ2LTg2OTEtMTE1NDRCNTgwNTQ3IiwKwqAgIm1lc3NhZ2UiIDogIlBheW1lbnQgdG93YXJkcyBvcmRlciBOby4gT0QxMzk5MjQ5MjMiLArCoCAiYXV0aFJlcXVlc3RJZCIgOiAiRDI1MDBDRUZCQkU0ODEwOTVBNDNENkQ1QjdBNzg3RiIsCsKgICJwYXltZW50U2NvcGUiIDogIlBIT05FUEUiLArCoCAiYW1vdW50IiA6IDM5OTAwLArCoCAiZGV2aWNlQ29udGV4dCIgOiB7CsKgIMKgICJkZXZpY2VPUyIgOiAiSU9TIiwKwqAgwqAgIm1lcmNoYW50Q2FsbEJhY2tTY2hlbWUiIDogImlPU0ludGVudEludGVncmF0aW9uIiwKwqAgwqAgImlzUFBBcHBQcmVzZW50IiA6IHRydWUKwqAgfQp9"
}

PhonePe Intent – When authWorkflowType is PENNY_DROP

{  
  "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
  }
}

Convert the JSON Payload to Base64 Encoded Payload

The above JSON request payload should be converted to the Base64 Encoded Payload and then the request should be sent in the below format.

{
   "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

{
  "success": true,
  "code": "SUCCESS",
	"message": "Your request has been successfully completed.",
  "data": {
    "redirectType": "INTENT",
    "redirectURL": "ppe://mandate?pn=SUBSCRIBEMID&pa=MID12345@ybl&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 Name	Data Type	Mandatory	Description
`merchantId`	`String`	`Yes`	MID provide by PhonePe
`merchantUserId`	`String`	`Yes`	User’s unique Id maintained by merchant
`subscriptionId`	`String`	`Yes`	PhonePe subscription Id
`authRequestId`	`String`	`Yes`	Merchant’s unique transaction Id
`amount`	`Long`	`Conditional`	● Mandatory when authWorkflowType is TRANSACTION ● Do not pass when authWorkflowType is PENNY_DROP
`paymentScope`	`String`	`No`	Default: PHONEPE ● PHONEPE – for PhonePe Intent
`deviceContext`	`Object`	`Yes` (Optional)	Mandatory for SDKLess Intent flow. Refer to the function to fetch the deviceContext
`deviceContext.deviceOS`	`String`	`Yes`	Value will be “IOS”
`deviceContext.merchantCallBackScheme`	`String`	`Yes`	Callback 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 Name	Data Type	Description
`redirectType`	`String`	Values: ● INTENT
`redirectUrl`	`String`	An intent url to launch the PhonePe app
`code`	`String`	“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

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>

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.

{“method”:”post”,”url”:”/v3/recurring/auth/init”,”auth”:”required”,”results”:{“codes”:[{“name”:”PhonePe Intent”,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n\t\”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”redirectType\”: \”INTENT\”,\n \”redirectURL\”: \”ppe://mandate?pn=SUBSCRIBEMID&pa=MID12345@ybl&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\”\n }\n}”,”language”:”json”,”status”:200},{“code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n\t\”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”redirectType\”: \”INTENT\”,\n \”redirectURL\”: \”upi://mandate?mn=Autopay&ver=01&purpose=14&mid=SWIGGY8&am=499.00&pa=SWIGGY8%40ybl&cu=INR&mc=5812&mg=ONLINE&pn=Swiggy&Rev=Y&QRts=2022-01-17T11%3A27%3A01.168%2B05%3A30&Mode=24&QRexpire=2022-01-17T11%3A32%3A01.168%2B05%3A30&Amrule=MAX&txnType=CREATE&Validitystart=17012022&Validityend=17012023&qrMedium=00&Block=N&Share=Y&Tr=TX312131232223231234&Recur=ASPRESENTED&orgid=500044&sign=MEYCIQDjgF5nN2zh67CfJZ80/M1Tb4ElF+6QKiUoIsNSMf5X9QIhAJBDW0WPIStMzCIzLfsNM7xX1cRTUBzExBUGIPFT8RrZ\”\n }\n}”,”language”:”json”,”status”:200,”name”:”Open Intent”},{“code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n\t\”message\”: \”Your request has been successfully completed.\”,\n \”data\”: null\n}”,”language”:”json”,”name”:”Collect Flow”,”status”:200},{“code”:”{\n \”success\”: false,\n \”code\”: \”SUBSCRIPTION_NOT_FOUND\”,\n \”message\”: \”No Subscription found with the given details.\”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”60ae0a6955a0b40191b799b9″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v3/recurring/auth/init\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”60ae0a6955a0b40191b799b8″},{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”60b75a868b7dff0029b91340″},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Dynamic callback URL for server to server callback”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60ed7fc9cab3580064c20cb9″},{“name”:”X-CALL-MODE”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”POST”,”required”:false,”in”:”header”,”ref”:””,”_id”:”60ed7fc9cab3580064c20cb8″}],”apiSetting”:”5a1563aec32b6d002a16fb67″,”examples”:{“codes”:[]}}

https://api-preprod.phonepe.com/apis/pg-sandbox

Sequence

Headers

Subscription – PhonePe Intent Flow

PhonePe Intent – When authWorkflowType is TRANSACTION

PhonePe Intent – When authWorkflowType is PENNY_DROP

Request Parameters

Response Parameters

S2S Callback – Submit Auth Request

S2S Callback – ACTIVE state

S2S Callback – FAILED state

Integration Steps on App Side

Updated on Sep 22, 2023