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:

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:

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.

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:

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:

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.

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:

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.

val queryResult = PaybyrdPaymentSDK.queryTransaction(
  requireContext(),
  QueryTransactionRequest(
    transactionAmount = transactionRequest.amount,
    transactionReference = transactionReference,
    transactionType = transactionRequest.transactionType,
    useReceiptDetails = useReceipt
  )
)

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

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

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.

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

Initialisation and provisioning

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

val initRequest = InitiateRequest(
  serviceCredentialEmail,
  serviceCredencialPassword,
  merchantIdentifier,
  forceInit
)

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

startActivityForResult(initData.intent, PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE)

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

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

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.

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

​Supported operations

​Creating a payment

​Pre-authorisation

​Refund

​Querying a transaction

​Tips

​Initialisation and provisioning

​Native SDK version history

​Full documentation

​JavaScript SDK

​Version history

Supported operations

Creating a payment

Pre-authorisation

Refund

Querying a transaction

Tips

Initialisation and provisioning

Native SDK version history

Full documentation

JavaScript SDK

Version history