Usage Example

Bill Submission

Generating Bill Submission Request Object

private static GepgBillSubReq createBillSubReq() {
    // instantiate the apiClient
    GepgApiClient gepgApiClient = new GepgApiClient();

    GepgBillHdr billHdr = new GepgBillHdr("SP023", true);
    GepgBillItem item1 = new GepgBillItem("788578851", "N", 7885.0, 7885.0, 0.0, "140206");
    GepgBillItem item2 = new GepgBillItem("788578852", "N", 7885.0, 7885.0, 0.0, "140206");

    GepgBillTrxInf billTrxInf = new GepgBillTrxInf(
            UUID.fromString("11ae8614-ceda-4b32-aa83-2dc651ed4bcd"), "2001", "tjv47", 7885.0, 0.0, gepgApiClient.getFutureDateTimeInDays(15), formatter), "Palapala",
            "Charles Palapala",
            "Bill Number 7885", gepgApiClient.getCurrentDateTime(), "100", "Hashim",
            "0699210053",
            "charlestp@yahoo.com",
            "TZS", 7885.0, true, 1, Arrays.asList(item1, item2));

    return new GepgBillSubReq(billHdr, billTrxInf);
}

Using the parseToXml and signMessage methods

public void submitBill() throws Exception {

    // instantiate the apiClient
    GepgApiClient gepgApiClient = new GepgApiClient();

    // create the GepgBillSubReq object and populate it with data
    GepgBillSubReq billSubRequestMapper = createBillSubReq();

    // convert it to an xml string
    String billXml = gepgApiClient.parseToXml(billSubReq);

    // sign the message
    String signedXml = gepgApiClient.signMessage(billXml, GepgBillSubReq.class);

    // submit Bill to Gepg
    GepgBillSubReqAck gepgBillSubResp = gepgApiClient.submitBill(signedXml);

    // check the response received from Gepg
    log.info("Bill Submission responses:{}", gepgBillSubResp);
 }

Alternatively you can use the generatePayload method which merges the two methods above into one

public void submitBill() throws Exception {

    // instantiate the apiClient
    GepgApiClient gepgApiClient = new GepgApiClient();

    // create the GepgBillSubReq object and populate it with data
    GepgBillSubReq gepgBillSubReq = createBillSubReq();

    // convert it to an xml string, add signature and return it
    String billXml = gepgApiClient.generatePayload(billSubReq);

    // submit Bill to Gepg
    GepgBillSubReqAck gepgBillSubResp = gepgApiClient.submitBill(billXml);

    // check the response received from Gepg
    log.info("Bill Submission responses:{}", gepgBillSubResp);
 }

Control Number Reuse

For Control Number Reuse (we use the same dtos as the bill submission request above with the only difference being that,the GepgBillTrxInf Dto has an extra field payCntrNum, which you can just set using the setPayCntrNum(String controlNumber) method everything else stays the same)

    private static GepgBillControlNoReuse createBillControlNoReuse() {
        GepgBillHdr billHdr = new GepgBillHdr("SP023", true);
        GepgBillItem item1 = new GepgBillItem("788578851", "N", 7885.0, 7885.0, 0.0, "140206");
        GepgBillItem item2 = new GepgBillItem("788578852", "N", 7885.0, 7885.0, 0.0, "140206");

        GepgBillTrxInf billTrxInf = new GepgBillTrxInf(
                UUID.fromString("11ae8614-ceda-4b32-aa83-2dc651ed4bcd"), "2001", "tjv47", 7885.0, 0.0,
                gepgApiClient.getFutureDateTimeInDays(10), "Palapala",
                "Charles Palapala",
                "Bill Number 7885", gepgApiClient.getCurrentDateTime(), "100", "Hashim",
                "0699210053",
                "charlestp@yahoo.com",
                "TZS", 7885.0, true, 1, Arrays.asList(item1, item2));

        billTrxInf.setPayCntrNum("990239121373");

        return new GepgBillControlNoReuse(billHdr, billTrxInf);
    }

Receiving Control Number

This is the callback url you will provide to GePG so that they can send control numbers to your system, here we are using Springboot Rest API

@PostMapping(value = "/submit-control-numbers")
@Transactional
public String postGepgBillSubResps(@RequestBody String xml) throws Exception {
    return billService.receiveControlNumber(xml);
}

The service method that will handle the request

@Override
public String receiveControlNumber(String gepgBillSubReqRespXml) throws Exception {
    // instantiate the api client
    GepgApiClient gepgApiClient = new GepgApiClient();

    // convert the xml string into a readable java object
    GepgBillSubResp gepgBillSubResp = gepgApiClient.receiveControlNumber(gepgBillSubReqRespXml);

    // probably use this data to update control number and message to bill

GepgBillSubRespAck gepgBillSubRespAck = new GepgBillSubRespAck();
    // respond by returning the signed response the ack xml
    return gepgApiClient.generateResponseAck(gepgBillSubRespAck);
}

Receiving Payment Notifications

This is the callback url you will provide to GePG so that they can send payment notifications to your system, again, we are using Springboot Rest API

@PostMapping(value = "/submit-payment-notifications")
@Transactional
public String receivePaymentNotifications(@RequestBody String xml) throws Exception {
    return billService.receiveControlNumber(xml);
}

The service method that will handle the request from the rest API

@Override
public String receivePaymentNotifications(String responseXml) throws Exception {
    GepgApiClient gepgApiClient = new GepgApiClient();

    // convert this into an a readable java object
    GepgPmtSpInfo gepgPaymentSpInfo = gepgApiClient.receivePaymentNotification(responseXml);

    // do something with the payment info
    // eg. update payment/bill

    // return the acknowledgement
    return gepgApiClient.generateResponseAck(new GepgPmtSpInfoAck());
}

Posting Payments

Generate the payload

    private static GepgPmtSpInfo createPaymentSpInfo() {
        // Creating and populating the Payment Transaction Information

        GepgPymtTrxInf pymtTrxInf = new GepgPymtTrxInf(
                "TRX123456", // trxId
                "SP001", // spCode
                "PAYREF123456", // payRefId
                UUID.fromString("74c7c4ee-b9d1-4a90-bb71-c999b7b6b09c"), // billId
                "PAYCTR123456", // payCtrNum
                1000.0, // billAmt
                1000.0, // paidAmt
                "1", // billPayOptString (corresponds to FULL payment option)
                "TZS", // CCy
                "2022-01-01T12:00:00", // trxDtTm
                "MOBILE", // usdPayChn
                "255712345678", // pyrCellNum
                "JohnDoe", // pyrName
                "johndoe@example.com", // pyrEmail
                "PSPREC123456", // pspReceiptNumber
                "PSPName", // pspName
                "CTRACC123456" // ctrAccNum
        );
        // Creating and populating the Payment Service Provider Information
        GepgPmtSpInfo pmtSpInfo = new GepgPmtSpInfo(pymtTrxInf);

        return pmtSpInfo;
    }

Method to handle Payment Submissions

    public void submitPayment() throws Exception {
        // Create a sample message
        GepgPmtSpInfo gepgPmtSpInfo = createPaymentSpInfo();

        // generate payload
        String message = gepgApiClient.generatePayload(gepgPmtSpInfo);

        // submit payment and receive ack from Gepg
        GepgPmtSpInfoAck ack = gepgApiClient.submitPayment(signedXml);

        // check the response status & update your data, maybe also log it here
        log.info("Payment Submission Response from Gepg:{}", ack);
    }