# 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;

```kotlin
PayContactlessCustomerSDK.initialize(this)
```

Where context (application context).

{% hint style="info" %}
**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.
{% endhint %}

Then you can retrieve the initialized instance as follows:

```
val sdk = PayContactlessCustomerSDK.getInstance()
```

### Class & Method Overview <a href="#id-4.-class-and-method-overview" id="id-4.-class-and-method-overview"></a>

#### CustomerInfo Data Class <a href="#id-4.1-customerinfo-data-class" id="id-4.1-customerinfo-data-class"></a>

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., `+2348067500250`).         |
| `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:

{% code overflow="wrap" %}

```kotlin
val customerInfo = CustomerInfo( organizationId = 10, firstName = "Tolu", lastName = "Tijani", region = "Lagos", subRegion = "eti-osa", emailAddress = "makolichuks@gmail.com", accountNumber = "0000000000", phoneNumber = "+234800000000", bvn = "0000000000", bankCode = "00000", pin = "0000", address = "lekki lagos" )
```

{% endcode %}

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.                 |

```kotlin
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 <a href="#id-4.3-downloading-a-receipt" id="id-4.3-downloading-a-receipt"></a>

Fetches a receipt for a transaction.

```kotlin
// 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:

{% code overflow="wrap" %}

```kotlin
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 
} })
```

{% endcode %}

#### Update Pin <a href="#id-4.4-update-pin" id="id-4.4-update-pin"></a>

Updates the user’s transaction PIN.

{% code overflow="wrap" %}

```kotlin
fun updatePin(updatePinRequest: UpdatePinRequest, listener: UpdatePinListener)
```

{% endcode %}

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

Example Usage:

{% code overflow="wrap" %}

```kotlin
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") } })
```

{% endcode %}

#### Get Transaction History <a href="#id-4.5-get-transaction-history" id="id-4.5-get-transaction-history"></a>

Retrieves a list of user transactions.

{% code overflow="wrap" %}

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

{% endcode %}

| 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 <a href="#id-4.6-get-transaction-detail" id="id-4.6-get-transaction-detail"></a>

Retrieves details of a specific transaction.

{% code overflow="wrap" %}

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

{% endcode %}

| 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 <a href="#id-5.-troubleshooting-and-faqs" id="id-5.-troubleshooting-and-faqs"></a>

#### **1. Why am I getting "SDK not initialized" error?** <a href="#id-1.-why-am-i-getting-sdk-not-initialized-error" id="id-1.-why-am-i-getting-sdk-not-initialized-error"></a>

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

#### **2. Why is Bluetooth connection failing?** <a href="#id-2.-why-is-bluetooth-connection-failing" id="id-2.-why-is-bluetooth-connection-failing"></a>

Ensure Bluetooth and Location permissions are granted.

#### **3. Why is** `downloadReceipt()` **not returning data?** <a href="#id-3.-why-is-downloadreceipt-not-returning-data" id="id-3.-why-is-downloadreceipt-not-returning-data"></a>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.prophius.com/developer-console/customer-account-base-embed-sdk/account-base-embed-sdk/sdk-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.