JAVA SDK – Introduction

Backend JAVA SDK to integrate PhonePe PG.

Installation

Requirements:

Java 8 or later

Maven users

Add the dependency to your project’s POM file:

<dependency>
    <groupId>com.phonepe</groupId>
    <artifactId>pg-sdk-java</artifactId>
    <version>2.1.0</version>
</dependency>

Add the PhonePe repository where the PhonePe SDK artifact is hosted to the distributionManagement:

<repositories>
    <repository>
        <id>io.cloudrepo</id>
        <name>PhonePe JAVA SDK</name>
        <url>https://phonepe.mycloudrepo.io/public/repositories/phonepe-pg-sdk-java</url>
    </repository>
</repositories>

Gradle users

Add the following to your project’s build.gradle file.

In the repositories section, add the URL for the PhonePe repository, and include the pg-sdk-java JAR in your dependencies.

repositories {
    maven {
        url "https://phonepe.mycloudrepo.io/public/repositories/phonepe-pg-sdk-java"
    }
}
 
dependencies {
    implementation 'com.phonepe:pg-sdk-java:2.1.0'
}

Onboarding

To get started with the keys,  you will need three details. Reach out to the Integration team.

String clientId = "<clientId>";
String clientSecret = "<clientSecret>";
Integer clientVersion = "<clientVersion>";

Quick start:

Class Initialisation

To create an instance of the CustomCheckoutClient class, you need to provide the keys received at the time of onboarding.

Example usage:

import com.phonepe.sdk.pg.Env;
import com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient;
 
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);

For details information on Class Initialisation – Refer here

Initiate an order

To init a pay request, we make a request object using PgPaymentRequest builder. Multiple builders are
implemented according to the instruments.

You will get to initiate the order using the pay() function:

UPI Intent

Example :

import com.phonepe.sdk.pg.common.models.request.PgPaymentRequest;
import com.phonepe.sdk.pg.common.models.response.PgPaymentResponse;
 
String merchantOrderId = UUID.randomUUID()
        .toString();
long amount = 100;
String deviceOS = "IOS";
String merchantCallbackScheme = "<merchantCallbackScheme>";
String targetApp = "PHONEPE";
 
PgPaymentRequest pgPaymentRequest = PgPaymentRequest.UpiIntentPayRequestBuilder()
        .merchantOrderId(merchantOrderId)
        .amount(amount)
        .targetApp(targetApp)
        .deviceOS(deviceOS)
        .build();
 
PgPaymentResponse pgPaymentResponse = customCheckoutClient.pay(pgPaymentRequest);
String intentUrl = pgPaymentResponse.getIntentUrl();

The response object will be pgPaymentResponse. Extract the intentUrl from the response received

For details information on Payment: UPI Intent – Refer here

UPI COLLECT

Example :

import com.phonepe.sdk.pg.common.models.request.PgPaymentRequest;
import com.phonepe.sdk.pg.common.models.response.pgPaymentResponse;
 
String merchantOrderId = UUID.randomUUID()
        .toString();
long amount = 100;
String deviceOS = "IOS";
String vpa = "<ENTER_YOUR_VPA>";
 
PgPaymentRequest pgPaymentRequest = PgPaymentRequest
        .UpiCollectPayViaVpaRequestBuilder()
        .merchantOrderId(merchantOrderId)
        .vpa(vpa)
        .deviceOS(deviceOS)
        .amount(amount)
        .message("collect_message")
        .build();
 
PgPaymentResponse pgPaymentResponse = customCheckoutClient.pay(pgPaymentRequest);

The response object will be PgPaymentResponse. It will raise a collect request on above-mentioned VPA.

For details information on Payment: UPI Collect – Refer here

UPI QR

Example:

import com.phonepe.sdk.pg.common.models.request.PgPaymentRequest;
import com.phonepe.sdk.pg.common.models.response.PgPaymentResponse;
 
String merchantOrderId = UUID.randomUUID()
        .toString();
long amount = 100;
String deviceOS = "IOS";

PgPaymentRequest pgPaymentRequest = PgPaymentRequest.UpiQrRequestBuilder()
        .amount(amount)
        .deviceOS(deviceOS)
        .merchantOrderId(merchantOrderId)
        .build();
 
PgPaymentResponse pgPaymentResponse = customCheckoutClient.pay(pgPaymentRequest);
String qrData = pgPaymentResponse.getQrData();

The response object will be PgPaymentResponse.Extract the qrData from the response received

For details information on Payment: UPI QR – Refer here

Create Order SDK Integration

This doc outlines the usage of create order method.

Use case – When your backend is in Java and you are using a Frontend SDK as well

The createSdkOrder() function is used to create a order.

import com.phonepe.sdk.pg.common.models.request.AccountConstraint;
import java.util.Arrays;
import java.util.UUID;
import com.phonepe.sdk.pg.payments.v2.models.request.CreateSdkOrderRequest;
import com.phonepe.sdk.pg.payments.v2.models.response.CreateSdkOrderResponse;
 
String merchantOrderId = UUID.randomUUID()
        .toString();
long amount = 100;
String accountNumber = "<ACCOUNT_NUMBER>";
String ifsc = "<IFSC_CODE>";
 
AccountConstraint constraints = AccountConstraint.builder()
        .accountNumber(accountNumber)
        .ifsc(ifsc)
        .build();
 
CreateSdkOrderRequest createSdkOrderRequest = CreateSdkOrderRequest.CustomCheckoutBuilder()
        .merchantOrderId(merchantOrderId)
        .amount(amount)
        .constraints(Arrays.asList(constraints))
        .build();
 
CreateSdkOrderResponse createSdkOrderResponse = customCheckoutClient.createSdkOrder(createSdkOrderRequest);
String token = createSdkOrderResponse.getToken();

Merchant should retrieve the token from the response object CreateSdkOrderResponse

For details information on Created Order SDK – Refer here

Check Status of a order

View the state for the order we just initiated.

import com.phonepe.sdk.pg.common.models.response.OrderStatusResponse;
 
String merchantOrderId = "<merchantOrderId>";  //created at the time of order creation
 
OrderStatusResponse orderStatusResponse = customCheckoutClient.getOrderStatus(merchantOrderId);
String state = orderStatusResponse.getState();

Returns an OrderStatusResponse Object

For details information on Check Order Status – Refer here

Order Callback Handling

You will receive a callback on the URL that you have configured on the business dashboard.
It is important to check the validity of the callback received from PhonePe using the validateCallback() function.

Example:

import com.phonepe.sdk.pg.common.models.response.CallbackResponse;
 
String username = "<username>";
String password = "<password>";
String authorization = "<authorization";
String responseBody = "<responseBody>";
 
CallbackResponse callbackResponse = customCheckoutClient.validateCallback(username, password, authorization, responseBody);
String orderId = callbackResponse.getPayload().getOrderId();
String state = callbackResponse.getPayload().getState();

The validateCallback will throw PhonePeException, if the callback is invalid.

Possible order callback states:

  1. pg.order.completed
  2. pg.order.failed
  3. pg.transaction.attempt.failed

For details information on Order Callback Handling – Refer here

Updated on May 29, 2024