Custom Apps SDK Documentation

Date of Publication: 22nd January, 2025

Version Number: 1.0.0

1 Table of Contents
2 Introduction
- 2.1 Key Features and Benefits
- 2.2 Sample Use Cases
3 Getting Started
- 3.1 Prerequisites
- 3.2 Setup
- 3.3 Quick Start
  - 3.3.1 Initialize the SDK:
  - 3.3.2 Configuration:
  - 3.3.3 Enabling Features:
4 Core Features
- 4.1 Card Payment
  - 4.1.1 Making Card Payments:
  - 4.1.2 Response Codes:
- 4.2 POS Transfer
  - 4.2.1 Listening for Transfers:
  - 4.2.2 Accepting Transfers:
  - 4.2.3 Declining a Transfer:
  - 4.2.4 Retrieving a List of Transactions
- 4.3 Receipt Printing
  - 4.3.1 Customizing Receipts:
  - 4.3.2 Steps To Print:
- 4.4 Getting POS Terminal Data
  - 4.4.1 Accessing Terminal Information:
- 4.5 Contact and Support

Introduction

The PaaP SDK empowers developers to extend the functionality of Moniepoint Android POS terminals by enabling the creation of custom applications. It supports essential payment features such as card payments, POS transfers, and receipt printing while offering seamless tools for accessing terminal-specific data, designing customized receipts, and securely managing transactions. For instance, developers can use the SDK to build an application that processes loyalty card payments, deducts points from a customer's balance, and prints detailed, branded receipts displaying the payment summary, remaining points, and rewards earned—enhancing both the terminal’s capabilities and the overall payment experience for businesses and customers.

Key Features and Benefits

Card Payment: Secure and fast transaction processing.
POS Transfer: Simplify accepting and managing instant transfers.
Receipt Printing: Easily customizable receipt templates.
Terminal Data: Access unique terminal information for better application management.

Sample Use Cases

Receipt Customization for Branding: Leverage the SDK’s receipt printing capabilities to create tailored, branded receipts with itemized details, logos, and promotional messages. Ideal for enhancing brand identity and improving customer engagement.
Healthcare Billing: Use the SDK in hospitals and clinics for processing patient payments. Generate detailed receipts for treatments, prescriptions, and services while maintaining compliance with healthcare regulations.

Getting Started

Prerequisites

Moniepoint Android Terminal (Model P8).
Authentication credentials and access to SDK registry.

Setup

To use the Moniepoint PaaP SDK in your application, add the SDK dependency to your app's build.gradle file. Replace *.*.* with the desired version of the SDK, if applicable.
Add the following line to the dependencies section:
implementation("com.moniepoint:paap:*.*.*")
Once added, you can start using the features provided by the Moniepoint Paap SDK in your application.

Important: Authentication is required to download from the registry. Kindly contact your Integration Support Engineer.

Quick Start

Initialize the SDK:

To initialize the Moniepoint Paap SDK, you need to pass a context and a config object to the initialize method, as shown below:

val moniepointPaapSdk = MoniepointPaapSdk.initialize(this, config)

Configuration:

The config object is created using the MoniepointPaapConfig.Builder() class, which allows you to enable specific features for your application. Below is an example of how to build the configuration:

val config = MoniepointPaapConfig.Builder()
    .enableCardPayment(true)
    .enablePosTransfer(true)
    .enablePrinting(true)
    .build()

Method	Function

Method	Function
`enableCardPayment`()	This enables the Card Payment feature of the SDK when set to true. It allows the application to process card-based transactions
`enablePosTransfer()`	This activates the POS Transfer feature when set to true. It enables the application to handle instant transfers, such as accepting or declining transactions and retrieving transaction history.
`.enablePrinting()`	This enables the Receipt Printing functionality when set to true. It allows the application to generate and print receipts using the POS terminal's printer.

Important: The PaaP SDK must be initialized before using any of its features.

Enabling Features:

Features can be enabled by calling their respective methods on the builder and passing true. For example:

enableCardPayment(true) enables card payment functionality.
enablePosTransfer(true) enables POS transfer functionality.
enablePrinting(true) enables printing functionality

Important: It is mandatory to enable a feature in the configuration before attempting to access it. If you attempt to use a feature that has not been explicitly enabled in the config during initialization, the Paap SDK will throw an exception.

Core Features

Card Payment

Card payment must be explicitly enabled in the configuration during initialization. Attempting to use card payment without enabling it will result in an exception.

Making Card Payments:

When building a custom application and you need to use the card payment feature via the SDK, you can do so by invoking the makeCardPayment method of the cardPaymentService. Simply pass the transaction amount and provide a lambda function to handle the response after the transaction is completed.

To receive payment, use the following method:

moniepointPaapSdk.cardPaymentService.makeCardPayment(amount) { transactionResponse ->
    // Handle the transaction response
}

When a card transaction is processed via the SDK, the response is provided as a TransactionResponse object. This object contains details about the transaction, such as the business, card information, transaction details, and status. See the object below

data class TransactionResponse(
    val business : String? = null,
    val cardScheme : String? = null,
    val cardExpiry : String? = null,
    val maskedPan: String? = null,
    val aid : String? = null,
    val transactionType : String? = null,
    val reference : String? = null,
    val responseCode: String,
    val message : String? = null,
    val stan: String? = null,
    val rrn: String? = null,
    val accountName : String? = null,
    val accountNumber : String? = null,
    val bank : String? = null,
    val sender : String? = null,
    val senderAccount : String? = null,
    val amount : String? = null
)

Response Codes:

The responseCode field in the TransactionResponse provides the status of the transaction. Below are the common response codes and their descriptions:

Response Codes	Description

Response Codes	Description
00	Transaction Approved
17	Transaction Declined
21	Transaction cancelled

POS Transfer

Your custom application can use the Moniepoint Paap SDK to receive, accept, or decline instant transfers, as well as retrieve a list of transactions.

Listening for Transfers:

To listen for incoming transfers, use the following method:

moniepointPaapSdk.posTransferService.listen {}

Accepting Transfers:

Once a transfer is received, you can accept it using the acceptPosTransferTransaction method. This method emits the result using a Flow, allowing you to handle success or error responses effectively.

 moniepointPaapSdk.posTransferService
        .acceptPosTransferTransaction(transactionReference)
        .catch {
            _message.value = it.message
        }
        .collect {
            _message.value = it.responseMessage
        }

Declining a Transfer:

If you choose to decline a transfer, you can use the declinePosTransferTransaction method in a similar way:

   moniepointPaapSdk.posTransferService
          .declinePosTransferTransaction(transactionReference)
          .catch {
              _message.value = it.message
          }
          .collect {
              _message.value = it.responseMessage
          }

Retrieving a List of Transactions

To fetch a paginated list of POS transfer transactions, use the getPosTransferTransactions method:

moniepointPaapSdk.posTransferService
          .getPosTransferTransactions(pageNumber = 1)
          .catch {
              _message.value = it.message
          }
          .collect {
              _transactions.value = it.posTransferTransactions
          }

Receipt Printing

Customizing Receipts:

Your custom application can leverage the SDK to print receipts using a predefined object, ReceiptItem, which represents a row of receipt data. This allows for easy customization of receipts with different types of content.

ReceiptItem is a data class used to define individual rows of receipt content:

@Parcelize
data class ReceiptItem(
    val type: ReceiptItemType,
    val key: String? = null,
    val value: String? = null
) : Parcelable

Receipt Item Type	Description	Example

Receipt Item Type	Description	Example
`IMAGE`	Image file in base64	A company’s logo
`KEY_VALUE`	Displayed in pairs	`Item : ₦90,000`
`LABEL`	A text aligned at the centre of the receipt	Transaction Summary
`SEPARATOR`	For clear sections between items	`--------------------------`
`TITLE`	A title or subtitle, a bold label	MONIEPOINT
`SPACING`	Provides vertical spacing between rows.
`QR`	Prints a QR code where you pass in the content you want to encode

Steps To Print:

Create a List of Document Items
Define the rows of receipt data using ReceiptItem objects. Each item represents a line on the receipt.
Example:
val documentItems = listOf( ReceiptItem(ReceiptItemType.IMAGE, value = image?.toBase64String()), ReceiptItem(ReceiptItemType.LABEL, value = "Moniepoint"), ReceiptItem(ReceiptItemType.KEY_VALUE, key = "Customer Name", value = "John Doe"), ReceiptItem(ReceiptItemType.SPACING), ReceiptItem(ReceiptItemType.SEPARATOR), ReceiptItem(ReceiptItemType.SPACING) )
Pass the list of document items to the SDK's print function to print the receipt.
moniepointPaapSdk.printerService.print(documentItems)
This setup automatically processes the printing request via the SDK, ensuring a smooth and user-friendly experience. You can customize receipts by adding different ReceiptItemType elements to match your application’s requirements.
**visual example of a receipt generated using the provided ReceiptItem types to help developers visualize the output.

Getting POS Terminal Data

Accessing Terminal Information:

Each terminal has unique identifiers and additional data that your custom application can use to operate more efficiently. The SDK provides on-demand access to terminal data, ensuring critical information is always available when required. By leveraging fields such as serialNumber, model, and posTransferAccountDetails, businesses can streamline operations, enhance customer support, and gain valuable insights for better decision-making.

To retrieve the terminal data, use the following method:

moniepointPaapSdk.terminalDataService.getTerminalInfo()

The method returns a TerminalInfo object containing the following fields:

serialNumber: String?: The terminal's unique serial number.
androidVersion: String?: The version of the Payment App running on the terminal.
manufacturer: String?: The terminal's manufacturer.
model: String?: The model name or identifier of the terminal.
posTransferAccountDetails: PosTransferAccountDetails?: Account details related to POS transfers.

 TerminalInfo(
    val serialNumber: String?,
    val androidVersion: String?,
    val manufacturer: String?,
    val model: String?,
    val posTransferAccountDetails: PosTransferAccountDetails?
)

where the posTransferAccountDetails field is an object of type PosTransferAccountDetails, which contains:

accountNumber: String: The POS transfer account number.
accountName: String: The name associated with the POS transfer account.
bankName: String: The name of the bank for the POS transfer account.

PosTransferAccountDetails(
    val accountNumber: String,
    val accountName: String,
    val bankName: String
)

Contact and Support

Support email: pos-integrations@moniepoint.com

Moniepoint POS Apps Developer Support