Payment Flow

• User visits merchant mobile application.

• Merchants ask the user to link the PhonePe wallet.

• Merchant calls TRIGGER OTP API and VERIFY OTP & LINKING API. Once the PhonePe Wallet is authorized, PhonePe sends userAuthToken in the response that will be used in the subsequent APIs.

• User adds goods or services and proceeds to checkout.

• Before displaying PhonePe Wallet on the checkout page, the merchant calls GET WALLET BALANCE API to check the balance of the user’s PhonePe wallet. Based on the following combinations, you can display either Pay or Top-up & Pay button.

Sample cases where a message can be shown to the user

📘

Note

These messages will come as the message field in the response. There may be more of these cases in the future, so please display these messages as they are received.

• Merchant displays PhonePe wallet and balance accordingly on the checkout page.

• Merchant calls DIRECT WALLET DEBIT API. If the user’s PhonePe wallet balance is sufficient, the amount will be debited, and a success message will be shared with the merchant by PhonePe. In case of insufficient balance, PhonePe sends the redirection URL for Add Money into the PhonePe wallet.

• Merchant redirects user on PhonePe App for Add Money • Users add money into PhonePe wallet and status is shared with the merchant.

• Merchant calls DIRECT WALLET DEBIT API again to make successful debit from user’s PhonePe Wallet. In case of failure, appropriate messaging is displayed to the user.

PhonePe Wallet Linking Flow

1. Trigger OTP API: This API will send OTP to verify the phone number. This API needs to be
   called with the same phone number as the PhonePe app is logged into. This can be a
   manual confirmation to be done by User
   Example: Please ensure the user’s PhonePe App is logged in using the same phone number

2. Verify OTP and Linking API: API to verify the OTP given by the customer and otpToken
   given by the merchant. Once verified, the merchant account is linked to the PhonePe
   account. This doesn’t involve any UI flow. The UX for accepting OTP and Linking needs to
   be implemented by Merchant.

📘

Note:

userAuthToken will be issued against the device id.
DeviceId has to be passed for every Get Wallet Balance API and Direct Wallet Debit API

UI Flow - Wallet Linking and Balance Display

Wallet Top up Direct Debit Flow

1. Get Wallet Balance API - This wallet Balance API can be used to check the balance of the user’s PhonePe Wallet.

Case 1 - In case PhonePe Wallet is active, KYC is active, and has sufficient balance, then the value of debitPossible will be true. Hence, the Pay button can be shown.

Case 2 - If the wallet is active but the user doesn’t have a valid instrument to top up the wallet, then the value of topupPossible and debitPossible will be false. Hence, wallet top-up is not recommended and the message field can be displayed with PhonePe Greyed out.

2. Direct Wallet Debit – Direct Wallet Debit API is used to debit the money directly from the PhonePe wallet.

"deviceContext:"{                // Object Mandatory
  "phonePeVersionCode": 303391   //Long Mandatory returns intent URI
}

If the user’s PhonePe wallet balance is sufficient, the amount will be debited, and a success message will be shared with the merchant by PhonePe In case of insufficient balance, PhonePe returns the URL for Add Money into PhonePe wallet. Debit API will also pass a flag to identify whether it is an HTTP URL, intent URL, or deep link.

3. Add Money Flow Steps
a. Pass the top-up URL received from the direct debit call to the merchant App.

b. Launch Wallet Top-up flow using the URL to launch wallet top-up flow using PhonePe App.

Uri deeplink Uri.parse(receivedDeeplink);
Intent intent new Intent(Intent.ACTION_VIEW, deeplink);
//9002 is requestCode to expect result in onActivityResult
startActivityForResult(intent, 9002);

c. Wait for Topup to complete

d. Once top-up is completed (success/failure), PhonePe App will give the result back to the Merchant App only. There is no server-to-server call-back available as of now.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data){
   super.onActivityResult(requestCode, resultCode, data);
   if (requestCode 9002){
      //inform backend PhonePe app has returned
   }
}

Note: PhonePe can provide a helper method as part of our SDK or we can provide a library
in source format.

e. Inform merchant backend about the top-up result.

f. Complete payment post Add Money.

g. If successful, make a direct debit call again to complete the transaction for the merchant’s order. If failure, provide an appropriate message to the user.

Additional Requirements from Merchants

1. Device ID: This is the unique device id that needs to be sent as HTTP Header "x-device-id” with all the above APIs

2. Recommended Headers: Merchants are expected to pass other parameters in headers
   to identify user block suspected frauds. Details are mentioned in the API Document.

UI Flow - In case of Sufficient PhonePe Wallet Balance

UI Flow - In case of Insufficient PhonePe Wallet Balance