PesePay Java SDK

A simple Java SDK for integrating PesePay payments into your application.

---

Installation

To use the Java Pesepay SDK, you need to add it as a dependency to your project. The release version will be in the Maven Central Repository.

Maven

<dependency>
    <groupId>com.pesepay</groupId>
    <artifactId>pesepay</artifactId>
    <version>1.1.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.pesepay:pesepay:1.1.0'
}

---

Getting Started

1. Create the Client

Create an instance of the Pesepay class using your integration key and encryption key as supplied by Pesepay.

Pesepay pesepay = new Pesepay(integrationKey, encryptionKey);

This targets the production environment. To use the sandbox environment (testing only, no real money), pass true as the third argument:

Pesepay pesepay = new Pesepay(integrationKey, encryptionKey, true);

The environment can also be selected explicitly with the Mode enum:

Pesepay testPesepay = new Pesepay(integrationKey, encryptionKey, Pesepay.Mode.TEST);
Pesepay livePesepay = new Pesepay(integrationKey, encryptionKey, Pesepay.Mode.LIVE);

Environment	Base URL
Production	https://api.pesepay.com/api/payments-engine
Sandbox	https://api.test.sandbox.pesepay.com/payments-engine

---

2. Configure Callback URLs

Set the urls that PesePay will use after processing a payment.

pesepay.setResultUrl("https://example.com/gateway/result");
pesepay.setReturnUrl("https://example.com/gateway/return");

• returnUrl – Where the customer is redirected after completing payment.
• resultUrl – Endpoint that receives the payment result.

---

Seamless Payments

Seamless payments allow customers to complete payment directly within your application.

Step 1: Create a Payment

Note: Either the customer's email address or phone number must be provided.

Payment payment = pesepay.createPayment("CURRENCY_CODE", "PAYMENT_METHOD_CODE", "CUSTOMER_EMAIL");

The phone number and name can be added to the customer afterwards:

payment.getCustomer().setPhoneNumber("0770000000");
payment.getCustomer().setName("Customer Name");

---

Step 2: Provide Required Payment Fields

Different payment methods require different fields.

Visa

Map<String, String> requiredFields = new HashMap<>();
requiredFields.put("creditCardExpiryDate", "09/23");
requiredFields.put("creditCardNumber", "4867960000005461");
requiredFields.put("creditCardSecurityNumber", "608");

Mobile Money (EcoCash, InnBucks, etc.)

Map<String, String> requiredFields = new HashMap<>();
requiredFields.put("customerPhoneNumber", "0770000000");

Payment Method	Requirement
EcoCash	customerPhoneNumber is required in the required payment fields.
InnBucks	The required payment fields can be sent as an empty map.

Map<String, String> requiredFields = Collections.emptyMap();

---

Step 3: Submit the Payment

Response response = pesepay.makeSeamlessPayment(payment, "Online Payment", 1.00, requiredFields);

if (response.isSuccess()) {
    // Save the reference number and/or poll url (used to check the status of a transaction)
    String pollUrl = response.getPollUrl();
    String referenceNumber = response.getReferenceNumber();
} else {
    // Get Error Message
    String errorMessage = response.getMessage();
}

---

Redirect Payments

Redirect payments send the customer to the PesePay checkout page to complete payment.

Step 1: Create a Transaction

Transaction transaction = pesepay.createTransaction(AMOUNT, "CURRENCY_CODE", "PAYMENT_REASON");

A merchant reference can be supplied on creation or set afterwards:

Transaction transaction = pesepay.createTransaction(AMOUNT, "CURRENCY_CODE", "PAYMENT_REASON", "MERCHANT_REFERENCE");

---

Step 2: Initiate the Transaction

Response response = pesepay.initiateTransaction(transaction);

if (response.isSuccess()) {
    // Save the reference number and/or poll url (used to check the status of a transaction)
    String referenceNumber = response.getReferenceNumber();
    String pollUrl = response.getPollUrl();

    // Get the redirect url and redirect user to complete transaction
    String redirectUrl = response.getRedirectUrl();
} else {
    // Get Error Message
    String errorMessage = response.getMessage();
}

---

Split Payments

Split payments let you act as an aggregator: you collect payments on behalf of another (beneficiary) merchant, and Pesepay settles your agreed share (commission/service fee) and the beneficiary's share according to the configured split arrangement.

Both the redirect and seamless flows support split payments. Attach the payment metadata to your transaction or payment before submitting it.

Redirect Flow

Transaction transaction = pesepay.createTransaction(100.00, "USD", "School fees", "MERCHANT_REFERENCE");

// Identify the beneficiary merchant receiving the main payment.
transaction.setSplitPayment("beneficiary@example.com");

Response response = pesepay.initiateTransaction(transaction);

Seamless Flow

Payment payment = pesepay.createPayment("USD", "PAYMENT_METHOD_CODE", "CUSTOMER_EMAIL");

payment.setSplitPayment("beneficiary@example.com");

Response response = pesepay.makeSeamlessPayment(payment, "Online Payment", 100.00, requiredFields);

splitAmountMode

splitAmountMode determines how your configured master merchant share is applied to the request amount:

Mode	Description
PRINCIPAL	The request amount is the total charged to the customer. Your share is deducted from it and the beneficiary receives the balance.
ADD_ON	The request amount is the beneficiary's principal. They receive it in full and your share is added on top for the customer.

setSplitPayment defaults to PRINCIPAL when no mode is supplied, and the mode is always sent alongside the beneficiary:

transaction.setSplitPayment("beneficiary@example.com", SplitAmountMode.ADD_ON);

Aliases are accepted and normalised automatically: PRINCIPAL_AMOUNT → PRINCIPAL; ADDON, ADDED_ON_TOP, ON_TOP → ADD_ON.

SplitAmountMode mode = SplitAmountMode.fromValue("ON_TOP");
transaction.setSplitPayment("beneficiary@example.com", mode);

For full control over the metadata, build it yourself:

PaymentMetadata paymentMetadata = PaymentMetadata.builder()
        .beneficiaryMerchantEmail("beneficiary@example.com")
        .splitAmountMode(SplitAmountMode.ADD_ON)
        .build();

transaction.setPaymentMetadata(paymentMetadata);

Note: When your application is configured for split payments, beneficiaryMerchantEmail is required on every transaction. An IllegalArgumentException is thrown for a missing or malformed beneficiary email, or when an unsupported split amount mode is supplied.

---

Checking Payment Status

You can verify a payment using either the transaction reference number or the poll url returned when the payment was created.

Option 1: Check by Reference Number

Response response = pesepay.checkPayment("REFERENCE_NUMBER");

if (response.isSuccess()) {
    if (response.paid()) {
        // Payment was successful
    }
} else {
    // Get Error Message
    String errorMessage = response.getMessage();
}

Option 2: Check by Poll URL

Response response = pesepay.pollTransaction("POLL_URL");

if (response.isSuccess()) {
    if (response.paid()) {
        // Payment was successful
    }
} else {
    // Get Error Message
    String errorMessage = response.getMessage();
}

---

Response Methods

Responses provide the following helper methods:

Method	Description
isSuccess()	Returns true if the request completed successfully.
getMessage()	Returns the error message if the request failed.
getReferenceNumber()	Returns the PesePay transaction reference.
getPollUrl()	Returns the polling URL used to check payment status.
getRedirectUrl()	Returns the checkout URL for redirect payments.
getTransactionStatus()	Returns the status of the transaction.
paid()	Returns true if the payment has been completed successfully.