Payment SDK

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
  • Refund (Complete and Partial)

Version: 0.0.7

📘

Info

The SDK is written in Kotlin Language.


Create a payment via SDK

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, 
  useReceiptDetails = false
)

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

📘

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.


Creating a refund via SDK

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 = paymentTransactionIdentifier,
  useReceiptDetails = false
)
  
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)
    }
}

🚧

Attention

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


Version History

Version

Date

Changes

Notes

0.0.7

01/09/2022

  • Support Receipt Details

Requires Paybyrd Payment App version 2.7.0 or later.

0.0.6

21/06/2022

  • Support Query Transactions

Requires Paybyrd Payment App version 2.3.0 or later

0.0.5

16/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.4

14/04/2022

  • Add more transaction data on payment response
    Card Brand
    Card Masked Numbe

0.0.3

06/04/2022

  • Add New 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 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.1

16/08/2021

Initial Version

  • Allows Payment and Refunds

Full Documentation

To see the full documentation, check the kotlin docs:

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