Guides

Payment SDK

Suggest Edits

The Paybyrd Payment SDK allows Android Applications to perform financial operations. This integration model, allows you to create your Android App with your business logic and add a payment feature with less effort in a secure way.

How the SDK works

To explain how it works, let's call Partner APP as the APP that will integrate with Paybyrd Payment SDK.

The Partner APP communicates with Paybyrd Payment APP via Android Intents, therefore both apps must be installed on the same POS. The architecture of communication is based on startActivityForResult model.

To perform the payment requests, the Partner APP must include the Paybyrd Payment SDK file, released through a .aar file, which is an Android Library. This .aar file, contains exactly the API to start and handle the result of all operations.

Supported Financial Operations

  • Payment
  • Pre Authorization
  • Refund (Complete and Partial)

Version: 0.0.10

📘

Info

The SDK is written in Kotlin Language.


Create a payment

To create a payment via SDK, you must provide the amount, currency and type as 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)

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

Create a pre authorization

To create a pre authorization transaction you have to start using the type TransactionTypeEnum.PREAUTHORIZE, this operation will reserver the founds in the credit card limit.

To capture the original pre authorization transaction you have to use the TransactionTypeEnum.CHARGE and use the original identifier. You can capture the full amount or any amount less than the original amount.

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)

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)

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

Creating a refund

To create a refund via SDK, you must provide the amount, currency, type as REFUND and the identifier of the original payment.

The refund can be complete or partial, to perform the partial refund just provide an amount less than the original amount.

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)

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

Your application may want to query a transaction data in any time or your application lifecycle. We strongly recommend the use of query transaction function in case of receiving the UNKNOWN status or when not receiving the transaction response.

Note: 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()
      }
    }
  }
}

Hints

📘

Hint

Save the transaction Identifier after a successful payment in case the need of future refund.

📘

Hint

Save the transaction reference created using PaybyrdPaymentSDK.createTransactionData if you need to query the transaction result.

Its recommended to query the transaction status when UNKNOWN status is returned.

📘

Hint

We suggest your application create an approach to store the transaction detail before every transaction and in case of need, perform query the transaction data.

Initialization Provisioning

Your application is allowed to perform a Paybyrd Payment App using a "Service Credencial" 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)
                    }
                }
            }
        }
    }

🚧

Attention

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


Version History

VersionDateChangesNotes
0.0.1015/02/2023- Add Order Reference fieldRequires Paybyrd Payment App version 3.1.0 or later.
0.0.921/10/2022- Add Pre Authorization ; Add Initialization Provisioning ; Add a Paybyrd App SDK Version to App Details response.Requires Paybyrd Payment version 2.8.0
0.0.812/09/2022- Add more transaction data on payment response { authorization code ; terminal id ; terminal serial number)Requires Paybyrd Payment App version 2.7.0
0.0.701/09/2022- Support Receipt DetailsRequires Paybyrd Payment App version 2.7.0 or later.
0.0.621/06/2022- Support Query TransactionsRequires Paybyrd Payment App version 2.3.0 or later
0.0.516/05/2022- Support Other currencies than EUR
- Validate Requested Currency with Merchant Currency		To support currencies other than EUR, requires Paybyrd Payment App version 2.2.0 or later.
0.0.414/04/2022- Add more transaction data on payment response
Card Brand
Card Masked Number
0.0.306/04/2022- Add New Settings Operations
Enable/Disable Automatic Printing
Configure Transaction Result Screen Behaviour { CLOSE_ON_TIMEOUT, NEVER_SHOW, ALWAYS_SHOW }
0.0.230/03/2022- Support Partial Refunds
- Add Settings Operations
Enable/Disable Receipt Printing
Enable/Disable Kioski Mode
Set Kioski APP
Get Terminal Data
Get Payment APP Data
Configure APN
Install APP from SDCARD Path
Enable/Disable Data Roaming
Reboot Terminal
0.0.116/08/2021Initial Version

- Allows Payment and Refunds

Full Documentation

To see the full documentation, check the kotlin docs by clicking the box below.

lykuhoczzinkhzk6cpofpw.on.drv.tw
paymentsdk

Javascript SDK

With this option you can run a progressive web app using an android webview and call the Paybyrd Payment APP directly from Javascript.

Version History

VersionDateChangesNative SDK VersionNotes
0.0.205/07/2023- Support All features of SDK 0.0.100.0.10Requires Paybyrd Payment App version 3.1.0 or later.
0.0.123/09/2021Initial Version

- Allows Payment And Refunds
- Support All features of SDK 0.0.8		0.0.8Requires Paybyrd Payment App version 2.7.0 or later.

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

Updated over 1 year ago