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