SAF Offline Transactions (Store-and-Forward)

val client = TaplinkSDK.getClient()
 
client.getOfflineMode(object : OfflineModeCallback {
    override fun onSuccess(result: OfflineModeResult) {
        val enabled = result.enabled
        val updatedAt = result.updatedAt
    }
 
    override fun onFailure(error: PaymentError) {
        // handle communication / technical error
    }
})

val request = SetOfflineModeRequest.builder()
    .setEnabled(true)
    .build()
 
client.setOfflineMode(request, object : OfflineModeCallback {
    override fun onSuccess(result: OfflineModeResult) {
        if (result.enabled) {
            // enabled successfully; present the offline risk notice to the merchant
            showRiskNotice(result.riskNotice)
        }
    }
 
    override fun onFailure(error: PaymentError) {
        // when not connected the switch does not take effect; a clear error is returned here
    }
})

client.getTerminalOnlineStatus(object : TerminalOnlineStatusCallback {
    override fun onSuccess(status: TerminalOnlineStatus) {
        when {
            status.canProcessOnline    -> proceedOnline()
            status.offlineModeEnabled  -> relyOnOffline()
            else                       -> abortTransaction(status.reason)
        }
    }
 
    override fun onFailure(error: PaymentError) { }
})

client.getSafConfig(object : SafConfigCallback {
    override fun onSuccess(config: SafConfigResult) {
        val single = config.singleTransactionLimit
        val cumulativeAmount = config.cumulativeAmountLimit
        val cumulativeCount = config.cumulativeCountLimit
    }
 
    override fun onFailure(error: PaymentError) { }
})

val request = SaveSafConfigRequest.builder()
    .setSingleTransactionLimit(BigDecimal("5000"))    // single-transaction cap USD 50.00 (incl. tip)
    .setCumulativeAmountLimit(BigDecimal("50000"))    // cumulative amount cap USD 500.00
    .setCumulativeCountLimit(20)                      // cumulative count cap
    .build()
 
client.saveSafConfig(request, object : SafConfigCallback {
    override fun onSuccess(config: SafConfigResult) {
        val savedAt = config.savedAt
    }
 
    override fun onFailure(error: PaymentError) { }
})

// query the current upload mode
client.getSafUploadMode(object : SafUploadModeCallback {
    override fun onSuccess(result: SafUploadModeResult) {
        val mode = result.mode // SafUploadMode.AUTO / MANUAL
    }
 
    override fun onFailure(error: PaymentError) { }
})
 
// set the upload mode
val request = SetSafUploadModeRequest.builder()
    .setMode(SafUploadMode.AUTO)
    .build()
 
client.setSafUploadMode(request, object : SafUploadModeCallback {
    override fun onSuccess(result: SafUploadModeResult) { }
    override fun onFailure(error: PaymentError) { }
})

val amount = AmountInfo()
    .setOrderAmount(BigDecimal("1000")) // 1000 minor units = USD 10.00
    .setPricingCurrency("USD")
 
val request = SaleRequest.builder()
    .setReferenceOrderId("ORDER_${System.currentTimeMillis()}")
    .setTransactionRequestId("TXN_${System.currentTimeMillis()}")
    .setAmount(amount)
    .setSafMode(SafMode.OFFLINE_ONLY) // force this transaction into SAF
    .build()
 
client.sale(request, object : PaymentCallback {
    override fun onSuccess(result: PaymentResult) {
        if (result.offlineApproved) {
            // accepted offline, not a final success; result.safStatus == SafStatus.PENDING
            markAsOfflineAccepted(result)
        }
    }
 
    override fun onFailure(error: PaymentError) { }
 
    override fun onProgress(event: PaymentEvent) { }
})

override fun onOfflineAcceptanceRequired(
    info: OfflineAcceptanceInfo,
    decision: OfflineAcceptanceDecision
) {
    // present the amount and risk notice to the cashier; timeout is 60 seconds
    showAcceptanceDialog(info) { accepted ->
        if (accepted) decision.accept() else decision.reject()
    }
}

val query = QueryRequest()
    .setTransactionRequestId("TXN_ORIGINAL_ID")
 
client.query(query, object : PaymentCallback {
    override fun onSuccess(result: PaymentResult) {
        when (result.safStatus) {
            SafStatus.PENDING, SafStatus.PROCESSING -> continueWaiting()
            SafStatus.APPROVED                       -> finalizeApproved(result)
            SafStatus.DECLINED, SafStatus.VOIDED     -> finalizeFailed(result)
            else                                     -> handleNonSaf(result)
        }
    }
 
    override fun onFailure(error: PaymentError) { }
})

val request = VoidRequest.builder()
    .setTransactionRequestId("TXN_${System.currentTimeMillis()}")
    .setOriginalTransactionRequestId("TXN_ORIGINAL_ID") // the SAF transaction to void
    .build()
 
client.void(request, object : PaymentCallback {
    override fun onSuccess(result: PaymentResult) {
        // result.offlineApproved == true, result.safStatus == SafStatus.VOIDED
    }
 
    override fun onFailure(error: PaymentError) {
        // not found / not this terminal / status not allowed — all returned with a distinguishable reason
    }
})

client.batchClose(request, object : PaymentCallback {
    override fun onSuccess(result: PaymentResult) { }
 
    override fun onFailure(error: PaymentError) {
        if (error.code == "317" && error.safPendingBlocked) {
            val summary = error.safPendingSummary // Pending count, amount, receiveUnknownCount
            // clear Pending by uploading first, then retry with the original batch-close request ID
            uploadThenRetryBatchClose(summary)
        }
    }
})

// local Pending list
val pendingReq = SafPageRequest.builder()
    .setPageNo(1)
    .setPageSize(20)
    .build()
 
client.listSafPending(pendingReq, object : SafPendingCallback {
    override fun onSuccess(page: SafPendingPage) {
        val items = page.items       // masked summaries
        val totalCount = page.totalCount
        val totalAmount = page.totalAmount
    }
 
    override fun onFailure(error: PaymentError) { }
})
 
// Sunbay SAF transactions list
val txnQuery = SafTransactionsQuery.builder()
    .setPageNo(1)
    .setPageSize(20)
    .setFromTime(fromTimeMillis)
    .setToTime(toTimeMillis)
    .setStatuses(listOf(SafStatus.PROCESSING, SafStatus.APPROVED, SafStatus.DECLINED))
    .build()
 
client.listSafTransactions(txnQuery, object : SafTransactionsCallback {
    override fun onSuccess(page: SafTransactionsPage) { }
    override fun onFailure(error: PaymentError) { }
})

val request = UploadSafTransactionRequest.builder()
    .setTransactionRequestId("TXN_ORIGINAL_ID")
    .build()
 
client.uploadSafTransaction(request, object : SafUploadCallback {
    override fun onSuccess(result: SafUploadResult) {
        val status = result.safStatus // current status or "result unknown"
    }
 
    override fun onFailure(error: PaymentError) {
        // when communication is interrupted and cannot be confirmed, the original transactionRequestId is preserved; reconcile with query
    }
})

val request = SafUploadAllRequest.builder()
    .setOperationId(UUID.randomUUID().toString()) // unique for the current terminal
    .build()
 
client.startSafUploadAll(request, object : SafUploadTaskCallback {
    override fun onSuccess(task: SafUploadTaskResult) {
        val taskId = task.uploadTaskId // status starts as RUNNING
        pollUploadTask(taskId)
    }
 
    override fun onFailure(error: PaymentError) {
        // when the creation result is unknown, operationId is returned to recover the task
    }
})
 
// query progress: either uploadTaskId or operationId
val query = SafUploadTaskQuery.builder()
    .setUploadTaskId(taskId)
    .build()
 
client.getSafUploadTask(query, object : SafUploadTaskCallback {
    override fun onSuccess(task: SafUploadTaskResult) {
        when (task.status) {
            SafUploadTaskStatus.RUNNING                 -> pollAgainLater()
            SafUploadTaskStatus.COMPLETED               -> onAllUploaded(task)
            SafUploadTaskStatus.COMPLETED_WITH_PENDING  -> onPartiallyUploaded(task)
        }
    }
 
    override fun onFailure(error: PaymentError) { }
})

client.registerSafResultCallback(object : SafResultCallback {
    override fun onUploaded(result: SafUploadResult) {
        // a SAF transaction was uploaded successfully (received by Sunbay)
    }
 
    override fun onFinalResult(result: SafUploadResult) {
        // a SAF transaction reached a final result: APPROVED / DECLINED
    }
})