Send reversal request

Function

int sendReversalRequest(String saleId, String transactionId, @Nullable String poNumber, Amount amount, @Nullable PaymentOptions options)

int sendReversal(RTRReversalRequest reversalRequest, RTRMessageHeader messageHeader)

int sendMessage(String message)

Description

Used to initiate a reversal of a previous transaction. The request is built with various values (see example).

The method returns an initial response (see Error code) whether the request could successfully be sent to the Soft Point-of-Sale app or not.

The result of the reversal itself is then received with the onReversalResponse(RTRReversalResponse response) or onResponseError(int errorCode) methods in your client implementation. More information on the asynchronous error codes can be found at Error codes.

Examples of using int sendReversal(...) and int sendReversalRequest(...) can be found at the bottom of the page.

Arguments

ArgumentDescriptionTypeRequired
saleIdIdentification of a Sale System or a Sale Terminal for the Sale to POI protocol.StringRequired
transactionIDId of the payment which gets reversed.StringRequired
poNumberPO Number of the merchant.StringOptional
amountThe amount of the transactionAmountRequired
optionsAdditional payment functionality.PaymentOptionsOptional

Objects

RTRReversalRequest

Content of the Reversal Request message.

ArgumentDescriptionTypeRequired
originalPoiTransactionOriginal Transaction which gets reversed.RTROriginalPOITransactionRequired
reversalReasonPick one of RTRReversalReason.RTRReversalReasonRequired
startDateUsually the current date/time.StringRequired
forecastedAmountAmount of reversal.BigDecimalRequired
saleDataData related to the Sale System.RTRPaymentTransactionOptional
reversedAmount-BigDecmialOptional
customerOrderIf related to a customer order.StringOptional
customerOrderId-StringOptional
openOrderStateTrue by default.BooleanOptional
currencyIf multiple currencies are allowed.StringOptional
additionalInformation-StringOptional

RTRMessageHeader

Message header of the Sale to POI protocol message

ArgumentDescriptionTypeRequired
messageClassPopulated with RTRMessage.Service.RTRMessageClassRequired
messageCategoryFor payments RTRMessageCategory.PAYMENT is used.RTRMessageCategoryRequired
messageTypeFor payments RTRMessageType.REQUEST is used.RTRMessageTypeRequired
serviceIdIdentification of a message pair, which processes a transactionStringRequired
saleIdIdentification of a Sale System or a Sale Terminal for the Sale to POI protocol.StringRequired
poiIdIdentification of a POI System or a POI Terminal for the Sale to POI protocol.StringRequired
protocolVersion-StringOptional
deviceId-StringOptional

For other objects, see Send payment request.

Example

Send Reversal Request

When using sendReversalRequest the SDK sets some of the values automatically.

When using sendReversal all fields have to be set. The SDK then converts it for sending it to the Soft Point-of-Sale app.

 fun sendReversalRequest(amount: String, poNumber: String?) {
        val invoiceNumber = sharedPrefs.lastPaymentOrRefundTransactionID!!

        val sponsoredMerchantData = sponsoredMerchantViewModel.getSponsoredMerchantData()
        val sponsoredMerchantModel = (
                if (sponsoredMerchantData == null) null else
                    SponsoredMerchantModel(
                        sponsoredMerchantData.merchantName,
                        sponsoredMerchantData.merchantCountry,
                        sponsoredMerchantData.merchantCategoryCode,
                        sponsoredMerchantData.registrationId,
                        sponsoredMerchantData.merchantAddress
                    ))

        val serviceIdOrSaleId = sharedPrefs.serviceIdOrSaleId.toString()
        val amount = Amount(amount = BigDecimal(amount), currency = "EUR")

        val options = PaymentOptions(
            sponsoredMerchantData = sponsoredMerchantModel
        )

        client.sendReversalRequest(serviceIdOrSaleId, invoiceNumber, poNumber, amount, options).let {
            Log.d(LOG_TAG, "Reversal result code: $it")
        }

        sharedPrefs.serviceIdOrSaleId = sharedPrefs.serviceIdOrSaleId.inc()
    }

fun sendReversalRequest(amount: String, poNumber: String?) {
        val sponsoredMerchantData = sponsoredMerchantViewModel.getSponsoredMerchantData()
        val sponsoredMerchantList = (
                if (sponsoredMerchantData == null) null else
                    listOf(RTRSponsoredMerchant(sponsoredMerchantData.merchantName, sponsoredMerchantData.merchantCountry,
                            sponsoredMerchantData.merchantCategoryCode, sponsoredMerchantData.registrationId, sponsoredMerchantData.merchantAddress)))

        val originalPoiTransaction = RTROriginalPOITransaction(
            RTRPOITransactionID(sharedPrefs.lastPaymentOrRefundTransactionID!!, "")
        )

        val saleData = RTRSaleData(
                saleTransactionID = RTRSaleTransactionID("", LocalDateTime.now().toString()),
                sponsoredMerchant = sponsoredMerchantList,
                saleToAcquirerData = getSaleToAcquirerData(poNumber)
        )

        val reversalReason = RTRReversalReason.MERCHANTCANCEL
        val reversalRequest = RTRReversalRequest(
            originalPoiTransaction,
            reversalReason,
            ZonedDateTime.now().toString(),
            BigDecimal(amount),
            saleData
        )

        val serviceIdOrSaleId = sharedPrefs.serviceIdOrSaleId.toString()

        val messageHeader = RTRMessageHeader(
            RTRMessageClass.SERVICE,
            RTRMessageCategory.PAYMENT,
            RTRMessageType.REQUEST,
            serviceIdOrSaleId,
            serviceIdOrSaleId,
            ""
        )

        sharedPrefs.serviceIdOrSaleId = sharedPrefs.serviceIdOrSaleId.inc()

        client.sendReversal(reversalRequest, messageHeader).let {
            Log.d(LOG_TAG, "Reversal result code: $it")
        }
    }

Receive Reversal Response

Extend your client-implementation with following methods:

class ClientImplementation(
  context: Context
) : Client(context, sha256OfSigningCertificate) {

    override fun onResponse(responseJson: String) {
        super.onResponse(responseJson)
        Log.d(LOG_TAG, "onResponse: $responseJson")
    }

    override fun onReversalResponse(response: RTRReversalResponse) {
        super.onReversalResponse(response)
        Log.d(LOG_TAG, "onResponse: $response")
    }
}