SDK API Reference

Using the Account Base PayContactless Embed SDK Library

Before accessing the functions within the PayContactless Embed SDK library, there are a few steps to follow:

1. Initialization: Begin by calling the initialize method.

A sample method is highlighted below;

PayContactlessCustomerSDK.initialize(this)

Where context (application context).

Important Recommendation for Using PayContactlessEmbed SDK

For optimal functionality and seamless integration, it is strongly advised to invoke the start method of PayContactlessEmbed within the onCreate method of your application.

Then you can retrieve the initialized instance as follows:

val sdk = PayContactlessCustomerSDK.getInstance()

Class & Method Overview

CustomerInfo Data Class

The CustomerInfo data class is used to encapsulate customer details required for transactions. Below is a breakdown of each parameter:

Parameter	Type	Description
organizationId	Int	The assigned merchant organization ID. it represents the merchant's specific organization.
firstName	String	Customer's first name.
lastName	String	Customer's last name.
region	String	The customer's state or major region (e.g., "Lagos").
subRegion	String	A more specific area within the region (e.g., "Eti-Osa").
emailAddress	String	Customer's email address for communication.
accountNumber	String	The customer's bank account number used for transaction processing.
phoneNumber	String	Customer’s phone number (must be in international format, e.g., [phone]).
bvn	String	Bank Verification Number (BVN) for customer identification.
bankCode	String	The unique identifier of the customer’s bank (e.g., "22998").
pin	String	Verified PIN for transactions.
address	String	The customer’s residential or business address.

Example Usage:

val customerInfo = CustomerInfo( organizationId = 10, firstName = "Tolu", lastName = "Tijani", region = "Lagos", subRegion = "eti-osa", emailAddress = "[e-mail]", accountNumber = "0000000000", phoneNumber = "[phone]", bvn = "0000000000", bankCode = "00000", pin = "0000", address = "lekki lagos" )

Start a Transaction

To start a transaction, call startTransaction() from the SDK with the following parameters. It launches the payment UI for transaction processing.

Parameter	Type	Description
apiKey	String	The authentication key assigned to the merchant for secure transactions.
customerInfo	CustomerInfo	An object containing customer details (see table above).
activity	Activity	The current activity from which the SDK is launched.
launcher	ActivityResultLauncher<Intent>	A launcher to handle transaction results asynchronously.

val launcher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        val data = result.data
        val paymentData = data?.getParcelableExtra<PaymentData>("payment_data")
        // Handle successful payment
    } else {
        val errorMessage = data?.getStringExtra("error_message")
        // Handle payment failure
    }
}

sdk.startTransaction("api_key_here", customerInfo, this, launcher)

---

Downloading a Receipt

Fetches a receipt for a transaction.

// Some 

Parameter	Type	Description
transactionId	Int	ID of the transaction.
phoneNumber	String	Customer’s phone number
orgId	Int	Organization ID.
listener	DownloadReceiptListener	Callback interface for receipt download success or failure.

Example Usage:

sdk.downloadReceipt(transaction_id, "phone_number",org_id, object : DownloadReceiptListener { override fun onDownloadSuccess(response: Uri?) { 
// Handle receipt download success 
} override fun onDownloadFailure(errorMessage: String) { 
// Handle failure 
} })

Update Pin

Updates the user’s transaction PIN.

fun updatePin(updatePinRequest: UpdatePinRequest, listener: UpdatePinListener)

Parameter	Type	Description
updatePinRequest	UpdatePinRequest	Object containing PIN update details.
listener	UpdatePinListener	Callback interface for success or failure.

Example Usage:

sdk.updatePin(UpdatePinRequest(org_id, "phone_number", "new_pin"), object : UpdatePinListener { override fun onUpdatePinSuccess(result: ResponseBody?) { Log.i("SDK", "Pin updated successfully") } override fun onUpdatePinFailure(errorMessage: String) { Log.e("SDK", "Failed to update PIN: $errorMessage") } })

Get Transaction History

Retrieves a list of user transactions.

fun getTransactionHistory( page: Int, size: Int, phoneNumber: String, orgId: Int, transactionId: Int?, startAmount: Int?, endAmountTo: Int?, startDate: String?, endDate: String?, listener: TransactionHistoryListener )

Parameter	Type	Description
page	Int	Page number for pagination. e.g 0
size	Int	Number of transactions per page. e.g 10
phoneNumber	String	Customer’s phone number.
orgId	Int	Organization ID.
transactionId	Int?	(Optional) Specific transaction ID filter.
startAmount	Int?	(Optional) Minimum transaction amount filter.
endAmountTo	Int?	(Optional) Maximum transaction amount filter.
startDate	String?	(Optional) Start date filter, format DD-MM-YYYY
endDate	String?	(Optional) End date filter, format DD-MM-YYYY
listener	TransactionHistoryListener	Callback for transaction history retrieval.

Get Transaction Detail

Retrieves details of a specific transaction.

fun getTransactionDetail( transactionId: Int, phoneNumber: String?, orgId: Int?, listener: TransactionDetailListener )

Parameter	Type	Description
transactionId	Int	ID of the transaction.
phoneNumber	String	Customer’s phone number.
orgId	Int	Organization ID.
listener	TransactionDetailListener	Callback interface for transaction details.

Troubleshooting & FAQs

1. Why am I getting "SDK not initialized" error?

Ensure you call PayContactlessCustomerSDK.initialize(context) in your Application class before calling getInstance().

2. Why is Bluetooth connection failing?

Ensure Bluetooth and Location permissions are granted.

3. Why is downloadReceipt() not returning data?

Check your network connectivity and ensure the correct transaction ID is passed.