> For the complete documentation index, see [llms.txt](https://lumin-soft.gitbook.io/cowpay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lumin-soft.gitbook.io/cowpay/cowpay-android-sdk.md).

# Cowpay Android SDK

## 1. REQUIREMENTS

* Minimum Android SDK 24 
* Target API level 34

## 2. INSTALLATION

1- Add the JitPack repository to the project-level build.gradle file:

```gradle
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
} 
```

2- Add Frames SDK dependency to the module gradle file:

```gradle
dependencies {
    implementation 'com.github.CowpayPayment:Cowpay-Android:${latest version}'
}
```

{% hint style="info" %}
You can find the latest version [here](https://github.com/CowpayPayment/Cowpay-Android/releases)
{% endhint %}

3- Update org.jetbrains.kotlin.android in build.grade (Project: Your Project) to be 1.9.0:

```gradle
plugins {
    id 'com.android.application' version '8.0.2' apply false
    id 'com.android.library' version '8.0.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.0' apply false
}
```

4- Update kotlinCompilerExtensionVersion in build.grade (Module :app) to be 1.5.1:

```gradle
    composeOptions {
        kotlinCompilerExtensionVersion '1.5.1'
    }
```

## 3. IMPORT

```kotlin
import com.luminsoft.cowpay_sdk.sdk.*
import com.luminsoft.cowpay_sdk.sdk.model.*
```

## 4. USAGE

**Step 1**: **Initialize the payment info:**

```kotlin
val paymentInfo = PaymentInfo(
    merchantReferenceId = "merchantReferenceId",
    customerMerchantProfileId = "customerMerchantProfileId",
    amount = 200.0,
    customerFirstName = "FirstName",
    customerLastName = "LastName",
    customerMobile = "01234567890",
    customerEmail = "customer@customer.com",
    description = "description",
    isFeesOnCustomer = false
)
```

**Step 2**: **Initialize the SDK:**

CowpaySDK.init function is used for Initializing Cowpay SDK instance to use it.

{% hint style="warning" %}
It’s a throws function so please put it in a try…catch blocs.
{% endhint %}

```kotlin
try {

    CowpaySDK.init(
        merchantCode = merchantCode,
        merchantHash = merchantHash,
        merchantPhoneNumber = merchantPhoneNumber,
        paymentInfo = paymentInfo,
        environment = CowpayEnvironment.STAGING or CowpayEnvironment.PRODUCTION,
        localizationCode = LocalizationCode.AR or LocalizationCode.EN,
        merchantLogo = merchantIconLink
    )
} catch (e: Exception) {
    Log.e("error", e.toString())
}
```

**Step 3**: **launch SDK and create a callback object:**

CowpaySDK.launch function is used for launching Cowpay SDK.

{% hint style="warning" %}
It’s a throws function so please put it in a try…catch blocs.
{% endhint %}

{% hint style="info" %}
CowpayCallBack object contains Success, error and closedByUser call backs
{% endhint %}

```kotlin
try {

    CowpaySDK.launch(activity, object : CowpayCallback {
        override fun success(paymentSuccessModel: PaymentSuccessModel) {
            // Successful payment call back
            // paymentSuccessModel.paymentMethodName
            // paymentSuccessModel.paymentReferenceId
        }

        override fun error(paymentFailedModel: PaymentFailedModel) {
            // error during the payment process
        }

        override fun closedByUser() {
            // the user decided to leave the payment page
        }
    })
} catch (e: Exception) {
    Log.e("error", e.toString())
}
```

## 5.  ADDITIONAL OPTIONS

{% hint style="info" %}
If you want to do an action based on payment method you can make success call back like that:
{% endhint %}

<pre class="language-kotlin"><code class="lang-kotlin">override fun success(paymentSuccessModel: PaymentSuccessModel) {

<strong>    if (paymentSuccessModel is PaymentSuccessModel.FawrySuccessModel) {
</strong>        Log.e("SuccessFawry", paymentSuccessModel.paymentMethodName)
    }
     else if (paymentSuccessModel is PaymentSuccessModel.CreditCardSuccessModel) {
<strong>        Log.e("SuccessCard", paymentSuccessModel.paymentReferenceId)
</strong>        Log.e("SuccessCard", paymentSuccessModel.paymentMethodName)
    }
    Log.e("SuccessCard", paymentSuccessModel.toString())
}
</code></pre>

## 5.  VALUES DESCRIPTION

| Keys                      | Values                                                                                                                                   |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| localizationCode          | Select your language code LocalizationCode.EN for English, and LocalizationCode.AR for Arabic. The default value is English              |
| environment               | Select the environment CowpayEnvironment.*STAGING* for staging and CowpayEnvironment.*PRODUCTION* for production.                        |
| amount                    | Transaction amount. Two decimal values like "15.60", were sent in case of partial capture. <mark style="color:orange;">(Required)</mark> |
| description               | charge request description that reserves the payment name. <mark style="color:orange;">(Required)</mark>                                 |
| customerMerchantProfileId | The ID of the customer being charged on your system. <mark style="color:orange;">(Required)</mark>                                       |
| merchantReferenceId       | A unique alphanumeric value is required as an identifier for the charge request. <mark style="color:orange;">(Required)</mark>           |
| customerFirstName         | customer first name <mark style="color:orange;">(Required)</mark>                                                                        |
| customerLastName          | customer last name <mark style="color:orange;">(Required)</mark>                                                                         |
| customerEmail             | customer valid email address. <mark style="color:orange;">(Required)</mark>                                                              |
| customerMobile            | Nationally formatted customer mobile that should start with 01. <mark style="color:orange;">(Required)</mark>                            |
| isFeesOnCustomer          | <p>Boolean variable, True if the customer will pay transaction fees and false if not.</p><p>Default value is false.</p>                  |
| merchantCode              | Your code that presented in your panel. <mark style="color:orange;">(Required)</mark>                                                    |
| merchantHash              | Hash Key that is presented in your panel. <mark style="color:orange;">(Required)</mark>                                                  |
| merchantPhoneNumber       | merchant phone number. <mark style="color:orange;">(Required)</mark>                                                                     |
| merchantLogo              | merchant logo url                                                                                                                        |
| CowpayCallback            | Call back functions model. It contains success, error, and closedByUser callbacks. <mark style="color:orange;">(Required)</mark>         |
| success                   | Call back function if transaction succeeds.                                                                                              |
| error                     | Call back function when an error occurres.                                                                                               |
| closedByUser              | Call back function if customer goes back before making a transaction.                                                                    |
| paymentSuccessMode        | Payment success model that contains paymentReferenceId and paymentMethodName.                                                            |
| paymentReferenceId        | Payment reference number.                                                                                                                |
| paymentMethodName         | Payment method name (credit card, fawry, etc…)                                                                                           |