> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment SDK (Android)

The Paybyrd Payment SDK allows Android applications to perform payment operations. The Partner App communicates with the Paybyrd Payment App via Android Intents — both apps must be installed on the same POS device. The architecture uses the `startActivityForResult` model.

The SDK is distributed as a `.aar` Android Library file, written in Kotlin.

**SDK version:** `0.0.10`

## Supported operations

* Payment
* Pre-authorisation
* Refund (full and partial)

## Creating a payment

Provide the amount, currency, and type `CHARGE`:

```kotlin theme={null}
val transactionRequest = TransactionRequest(
  amount = inputAmount.toLong(),
  currency = TransactionCurrencyEnum.EUR,
  transactionType = TransactionTypeEnum.CHARGE
)

val transactionData = PaybyrdPaymentSDK.createTransactionData(
  context,
  transactionRequest
)

startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```

**Handling the response:**

```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
        val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)

        if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
            toast("Success")
        } else {
            val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
                PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
                PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
                PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
                PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
                else -> "unknown result code"
            }

            val transactionStatus = when (transactionResponseData.transactionResponse.status) {
                TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
                TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
                TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
                TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
                TransactionStatusEnum.ERROR -> "the performed transaction result in error"
                TransactionStatusEnum.FAILED -> "the performed operation failed"
            }

            toast("$resultCodeMessage - $transactionStatus")
        }

        showTransactionResponseAlert(transactionResponseData)
    }
}
```

## Pre-authorisation

To create a pre-authorisation, use `TransactionTypeEnum.PREAUTHORIZE`. This reserves the funds in the card's credit limit.

```kotlin theme={null}
val transactionRequest = TransactionRequest(
  amount = inputAmount.toLong(),
  currency = TransactionCurrencyEnum.EUR,
  transactionType = TransactionTypeEnum.PREAUTHORIZE
)

val transactionData = PaybyrdPaymentSDK.createTransactionData(
  context,
  transactionRequest
)

startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```

To capture a pre-authorisation, use `TransactionTypeEnum.CHARGE` with the original pre-authorisation identifier. You can capture the full amount or any amount less than the original:

```kotlin theme={null}
val transactionRequest = TransactionRequest(
  amount = inputAmount.toLong(),
  currency = TransactionCurrencyEnum.EUR,
  transactionType = TransactionTypeEnum.CHARGE,
  referencedTransactionIdentifier = ${ID_ORIGINAL_PREAUTHORIZATION}
)

val transactionData = PaybyrdPaymentSDK.createTransactionData(
  context,
  transactionRequest
)

startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```

**Handling the response:**

```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
        val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)

        if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
            toast("Success")
        } else {
            val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
                PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
                PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
                PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
                PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
                else -> "unknown result code"
            }

            val transactionStatus = when (transactionResponseData.transactionResponse.status) {
                TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
                TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
                TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
                TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
                TransactionStatusEnum.ERROR -> "the performed transaction result in error"
                TransactionStatusEnum.FAILED -> "the performed operation failed"
            }

            toast("$resultCodeMessage - $transactionStatus")
        }

        showTransactionResponseAlert(transactionResponseData)
    }
}
```

## Refund

Provide the amount, currency, type `REFUND`, and the identifier of the original payment. For a partial refund, provide an amount less than the original.

```kotlin theme={null}
val transactionRequest = TransactionRequest(
  amount = refundAmount.toLong(),
  currency = TransactionCurrencyEnum.EUR,
  transactionType = TransactionTypeEnum.REFUND,
  referencedTransactionIdentifier = ${ORIGINAL_CHARGE_IDENTIFIER}
)

val transactionData = PaybyrdPaymentSDK.createTransactionData(
  context,
  transactionRequest
)

startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```

**Handling the response:**

```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
        val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)

        if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
            toast("Success")
        } else {
            val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
                PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
                PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
                PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
                PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
                PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
                else -> "unknown result code"
            }

            val transactionStatus = when (transactionResponseData.transactionResponse.status) {
                TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
                TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
                TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
                TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
                TransactionStatusEnum.ERROR -> "the performed transaction result in error"
                TransactionStatusEnum.FAILED -> "the performed operation failed"
            }

            toast("$resultCodeMessage - $transactionStatus")
        }

        showTransactionResponseAlert(transactionResponseData)
    }
}
```

## Querying a transaction

Use the query operation to check transaction status at any point in your application lifecycle. Recommended when the response returns `UNKNOWN` status or when no response is received.

`PaybyrdPaymentSDK.queryTransaction` is synchronous.

```kotlin theme={null}
val queryResult = PaybyrdPaymentSDK.queryTransaction(
  requireContext(),
  QueryTransactionRequest(
    transactionAmount = transactionRequest.amount,
    transactionReference = transactionReference,
    transactionType = transactionRequest.transactionType,
    useReceiptDetails = useReceipt
  )
)
```

```kotlin theme={null}
if (queryResult.code == PaybyrdPaymentSDK.CODE_SUCCESS) {
    when (queryResult.transactionStatus) {
        TransactionStatusEnum.APPROVED -> {
            if (queryResult.transactionStatus == TransactionStatusEnum.APPROVED) {
                requireActivity().runOnUiThread {
                    showTransactionResponseAlert(queryResult.transactionResponseData!!)
                }
            }
        }
        TransactionStatusEnum.DECLINED,
        TransactionStatusEnum.ABORTED,
        TransactionStatusEnum.ERROR -> {
            requireActivity().runOnUiThread {
                Toast.makeText(requireContext(), "queried transaction is declined", Toast.LENGTH_LONG).show()
            }
        }
        TransactionStatusEnum.UNKNOWN, TransactionStatusEnum.FAILED -> {
            requireActivity().runOnUiThread {
                Toast.makeText(requireContext(), "queried transaction is unknown, try query again after", Toast.LENGTH_LONG).show()
            }
        }
    }
}
```

## Tips

<Tip>Save the transaction identifier after a successful payment — you will need it for future refunds.</Tip>

<Tip>Save the transaction reference created by `PaybyrdPaymentSDK.createTransactionData` so you can query the transaction result if needed. Query the transaction status whenever `UNKNOWN` is returned.</Tip>

<Tip>Store transaction details before initiating every transaction so you can query the data if the response is not received.</Tip>

## Initialisation and provisioning

Your application can provision the Paybyrd Payment App using a service credential and a merchant identifier.

```kotlin theme={null}
val initRequest = InitiateRequest(
  serviceCredentialEmail,
  serviceCredencialPassword,
  merchantIdentifier,
  forceInit
)

val initData = PaybyrdSettingsSDK.createInitializationData(
  requireContext(),
  initRequest
)

startActivityForResult(initData.intent, PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE)
```

```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE) {
        val initResponseData = PaybyrdSettingsSDK.unpackInitializationResponseData(data?.extras!!)

        if (resultCode == PaybyrdSettingsSDK.CODE_INIT_SUCCESS) {
            if (initResponseData.code == PaybyrdSettingsSDK.CODE_INIT_ALREADY_INITIATED) {
                val errorMessage = "Already init!!"
                showSnackBarMessage(errorMessage)
            } else {
                val errorMessage = getString(R.string.login_success, initResponseData.name, initResponseData.email)
                showSnackBarMessage(errorMessage)
            }
        } else {
            when (initResponseData.code) {
                PaybyrdSettingsSDK.CODE_INIT_FAILED -> {
                    val errorMessage = initResponseData.description
                    showSnackBarMessage(errorMessage)
                }
                PaybyrdSettingsSDK.CODE_INIT_ERROR_NO_MERCHANT_WITH_PERSON_ID -> {
                    val errorMessage = "No Person ID!!"
                    showSnackBarMessage(errorMessage)
                }
                PaybyrdSettingsSDK.CODE_INIT_LOGGED_WITH_ANOTHER_PERSON_ID -> {
                    val errorMessage = "Init with another personId!!"
                    showSnackBarMessage(errorMessage)
                }
            }
        }
    }
}
```

<Warning>The Partner App and Paybyrd Payment App must be installed and running on the same POS device.</Warning>

## Native SDK version history

| Version | Date       | Changes                                                                                                                                                                                                                                                          | Notes                                                              |
| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| 0.0.10  | 15/02/2023 | Add Order Reference field                                                                                                                                                                                                                                        | Requires Paybyrd Payment App 3.1.0 or later                        |
| 0.0.9   | 21/10/2022 | Add Pre-authorisation; Add Initialisation Provisioning; Add Paybyrd App SDK Version to App Details response                                                                                                                                                      | Requires Paybyrd Payment App 2.8.0                                 |
| 0.0.8   | 12/09/2022 | Add more transaction data on payment response (authorization code; terminal id; terminal serial number)                                                                                                                                                          | Requires Paybyrd Payment App 2.7.0                                 |
| 0.0.7   | 01/09/2022 | Support Receipt Details                                                                                                                                                                                                                                          | Requires Paybyrd Payment App 2.7.0 or later                        |
| 0.0.6   | 21/06/2022 | Support Query Transactions                                                                                                                                                                                                                                       | Requires Paybyrd Payment App 2.3.0 or later                        |
| 0.0.5   | 16/05/2022 | Support currencies other than EUR; Validate Requested Currency with Merchant Currency                                                                                                                                                                            | Requires Paybyrd Payment App 2.2.0 or later for non-EUR currencies |
| 0.0.4   | 14/04/2022 | Add card brand and card masked number to payment response                                                                                                                                                                                                        |                                                                    |
| 0.0.3   | 06/04/2022 | Add settings operations: Enable/Disable Automatic Printing; Configure Transaction Result Screen Behaviour (CLOSE\_ON\_TIMEOUT, NEVER\_SHOW, ALWAYS\_SHOW)                                                                                                        |                                                                    |
| 0.0.2   | 30/03/2022 | Support Partial Refunds; Add settings operations: Enable/Disable Receipt Printing; Enable/Disable Kiosk Mode; Set Kiosk App; Get Terminal Data; Get Payment App Data; Configure APN; Install App from SD card path; Enable/Disable Data Roaming; Reboot Terminal |                                                                    |
| 0.0.1   | 16/08/2021 | Initial version: Payment and Refunds                                                                                                                                                                                                                             |                                                                    |

## Full documentation

For the full Kotlin SDK reference, visit the [SDK documentation](https://lykuhoczzinkhzk6cpofpw.on.drv.tw/www.paybyrddocssdk0010.com/).

## JavaScript SDK

A JavaScript SDK is available for progressive web apps running inside an Android WebView. It matches the functionality of native SDK version `0.0.10`.

### Version history

| Version | Date       | Changes                                                                 | Native SDK version | Notes                                       |
| ------- | ---------- | ----------------------------------------------------------------------- | ------------------ | ------------------------------------------- |
| 0.0.2   | 05/07/2023 | Support all features of SDK 0.0.10                                      | 0.0.10             | Requires Paybyrd Payment App 3.1.0 or later |
| 0.0.1   | 23/09/2021 | Initial version: Payment and Refunds; Support all features of SDK 0.0.8 | 0.0.8              | Requires Paybyrd Payment App 2.7.0 or later |

Contact us to get access to all resources including a complete demonstration project.