To set up the mandate or accept the first payment from the user on the iOS Platform
Quick Links
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 here
{
"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 here |
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 | Comments |
---|---|---|---|
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.
