Webhook Handling

Overview

Use callback verification to confirm that the callback you received from PhonePe is authentic.

The validateCallback() method is used to validate webhook or callback responses. You can use this method by passing all the necessary parameters.

Request

Request Parameters

Parameter Name	Data Type	Mandatory (Yes/NO)	Description
`username`	String	Yes	Your unique username configured for the callback URL
`password`	String	Yes	Your unique password configured for the callback URL
`authorization`	String	Yes	Value of the Authorization header under the callback response.
`responseBody`	String	Yes	The response body received in the callback as a string

Sample Request

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient;
import com.phonepe.sdk.pg.common.models.response.CallbackResponse;
 
String clientId = "<clientId>";
String clientSecret = "<clientSecret>";
Integer clientVersion = clientVersion;  //insert your client version here
Env env = Env.SANDBOX;      //change to Env.PRODUCTION when you go live
 
CustomCheckoutClient customCheckoutClient = CustomCheckoutClient.getInstance(clientId, clientSecret,
        clientVersion, env);
 
String username = "<username>";
String password = "<password>";
String authorization = "<authorization>";
String responseBody = "<responseBody>";
 
CallbackResponse callbackResponse = customCheckoutClient.validateCallback(username, password, authorization,
        responseBody);
String callbackType = callbackResponse.getType();
String orderId = callbackResponse.getPayload()
        .getOrderId();
String state = callbackResponse.getPayload()
        .getState();

Response

The function returns a CallbackResponse object containing two main parameters: type, which indicates the event type, and payload, which holds all the event-specific details.

Parameter Name	Data Type	Description
type	CallbackType	Tells you what type of event happened (e.g., order completed, refund failed, etc.)
payload	CallbackData	Contains all the details related to that event

The event type are explained below:

Event Type	Description
`PG_ORDER_COMPLETED`	The payment was successfully completed
`PG_ORDER_FAILED`	The payment failed
`PG_REFUND_COMPLETED`	A refund was successfully processed
`PG_REFUND_FAILED`	A refund request failed

The payload details are explained below:

Parameter Name	Data Type	Description
`merchantId`	String	Merchant ID from which the request was initiated
`orderId`	String	Order ID generated by PhonePe Payment Gateway (only for order callbacks)
`originalMerchantOrderId`	String	Order ID generated by you (only for order callbacks)
`refundId`	String	Refund ID generated by PhonePe PG (only for refund callbacks)
merchantRefundId	String	Refund ID generated by you (only for refund callbacks)
`state`	String	The current state of the order or refund.
`amount`	Long	The amount processed in paisa.
`expireAt`	Long	The expiry timestamp in epoch format
`errorCode`	String	The error code (only for failed transactions)
`detailedErrorCode`	String	A more detailed error code (only for failures)
`metaInfo`	MetaInfo	Metadata passed during order initialization
`paymentDetails`	List<PaymentDetail>	The Payment details of the transaction

The PaymentRefundDetail property contains a list of payment details for each payment attempt made against an order. The details of each payment are explained in the table below.

Attribute	Data Type	Description
`transactionId`	String	Merchant ID from which the request was initiated
`paymentMode`	String	Order ID generated by PhonePe Payment Gateway (only for order callbacks)
`timestamp`	Long	Order ID generated by you (only for order callbacks)
`state`	String	Attempted transaction state. It can be any one of the following states: • COMPLETED • FAILED • PENDING
`errorCode`	String	Error code (only present when the state is failed)
`detailedErrorCode`	String	A more specific error code (only present when the state is failed)

JAVA SDK – Exception Handling

This document outlines the exception handling for the exceptions that might incur.

PhonePeException

Exception raised for errors related to PhonePe APIs.

Attribute	Type	Description
`code`	String	The status code of the response.
`message`	String	The error message.
`http_status_code`	Integer	The http status received from the API
`data`	Map<String, String>	The details of the error that happened while calling phonepe.

Example Usage :

import com.phonepe.sdk.pg.Env;

import com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient;

import com.phonepe.sdk.pg.payments.v2.models.request.CustomCheckoutPayRequest;

import com.phonepe.sdk.pg.payments.v2.models.response.CustomCheckoutPayResponse;
 
String clientId = "<clientId>";
String clientSecret = "<clientSecret>";
Integer clientVersion = 1;      //insert your client version here
Env env = Env.SANDBOX;          //change to Env.PRODUCTION when you go live
 
CustomCheckoutClient customCheckoutClient = CustomCheckoutClient.getInstance(clientId, clientSecret, clientVersion, env);
 
String merchantOrderId = "<duplicateId>";  //will throw exception
long amount = 100;
String redirectUrl = "https://merchant.com/redirectUrl";
 
CustomCheckoutPayRequest request = CustomCheckoutPayRequest.UpiQrRequestBuilder()
        .merchantOrderId(merchantOrderId)
        .amount(amount)
        .redirectUrl(redirectUrl)
        .build();
 

try{
    StandardCheckoutPayResponse standardCheckoutPayResponse = standardCheckoutClient.pay(standardCheckoutPayRequest);
}

catch(PhonePeException phonePeException)
{
    Integer httpStatusCode = phonePeException.getHttpStatusCode();
    String message = phonePeException.getMessage();
    Map<String, Object> data = phonePeException.getData()
    String code = phonePeException.getCode()
}

Java SDK – Response Models

Use the following response model structure to access payment related details after calling getOrderStatus():

Payment Rail

The rail attribute within the PaymentDetail object indicates the type of payment rail used for the transaction. This value helps you identify the payment method such as UPI, Card, or Wallet through which the transaction was processed.

UPI RAIL

Property	Type
`type`	PaymentRailType
`utr`	String
`upiTransactionId`	String
`vpa`	String

PG RAIL

Property	Type
`type`	PaymentRailType
`transctionId`	String
`authorizationCode`	String
`serviceTransactionId`	String

PPI WALLET RAIL

Property	Type
`type`	PaymentRailType

PPI EGV RAIL

Property	Type
`type`	PaymentRailType

PaymentInstrumentV2
- Represents the instrument used to initiate a payment. Various instrument types are listed below:

ACCOUNT

Property	Type
`type`	PaymentInstrumentType
`ifsc`	String
`accountType`	String
`maskedAccountNumber`	String
`accountHolderName`	String

CREDIT_CARD

Property	Type
`type`	PaymentInstrumentType
`bankTransactionId`	String
`bankId`	String
`arn`	String
`brn`	String

DEBIT_CARD

Property	Type
`type`	PaymentInstrumentType
`bankTransactionId`	String
`bankId`	String
`arn`	String
`brn`	String

NET_BANKING

Property	Type
`type`	PaymentInstrumentType
`bankTransactionId`	String
`bankId`	String
`arn`	String
`brn`	String

EGV

Property	Type
`type`	PaymentInstrumentType
`cardNumber`	String
`programId`	String

WALLET

Property	Type
`type`	PaymentInstrumentType
`walletId`	String

Instrument Constraints

ACCOUNT

Property	Type
`type`	Account
`accountNumber`	String
`ifsc`	String