Payment reversal

United States

To return funds to a customer, reverse the original payment. When you make these requests, provide a paymentID as a reference to the payment that needs reversal.

Types of reversal:

  • Void and refund—Legacy Clover SDKs supported explicit methods for both void and refund. Reversal is a convenience method that abstracts the timing logic needed to determine whether a payment should be voided or refunded.
  • Reversal—Processes a return on an existing payment. If there is no existing payment, use a Credit request to return funds to customers.
  • Online Refund Authorization—Refunds and credits are subject to approval or decline by the processor. Configure your app to handle all potential scenarios.

For more information, see Supported payment methods.

Prerequisites

Before you integrate with the Go SDK, complete the following:

Field descriptions

ReversalRequest

FieldRequiredTypeDescription
PaymentIdtrueStringClover-assigned universally unique identifier (UUID) of the payment for which reversal is requested.

Length: Maximum 13

Note: The PaymentID displays in the Payment details in PayResponse for which a successful PayRequest was sent.
amountfalseInt64Refund amount in cents.

If the value in this field is null/nil or zero (0), the full amount is refunded.

Format: Cents; Cannot be a negative value.

Maximum amount = 999999999

ReversalResponse

FieldTypeDescription
PaymentIdStringClover-assigned universally unique identifier (UUID) of the payment for which reversal is needed.

Note: This value must be the same as the paymentId under reversalRequest.
resultReversalResultIndicates if the payment is voided or refunded in case of successful reversal.
Values:

- Void
- Refund
voidReasonVoidReasonReason for the reversal is voided.
Value:The default value is USER_CANCEL, since it is requested by the integrator or user.
refundRefundRefund details are auto-populated on a successful refund

Android

To reverse a payment, enter values in the ReversalRequest parameters. See the ReversalRequest.

The following are the ReversalResponse response scenarios for the ReversalPaymentState:

  • Successful reversal request returns OnReverseComplete with the ReversalResponse.
  • Error such as invalid payment input returns the OnReversalPaymentError.
fun requestReversal(request: ReversalRequest): Flow<ReversalPaymentState>
lifecycleScope.launch {
    val request = ReversalRequest(
        amount = amount,
        paymentId = paymentId
    )
 
    goSdk.requestReversal(
        request
    ).collectLatest { reversalPaymentState ->
 
        when (reversalPaymentState) {
            is ReversalPaymentState.OnReversalPaymentError -> {
                println("Reversal failed: ${reversalPaymentState.error}")
                updateUI(reversalPaymentState)
            }
            is ReversalPaymentState.OnReversalPaymentComplete -> {
                println("Reversal succeeded: ${reversalPaymentState.response}")
                updateUI(reversalPaymentState)
            }
            else -> {
                //Something unexpected happened
            }
        }
    }
}
lifecycleScope.launch {
    val voidRequest = ReversalRequest(
        amount = null,
        paymentId = paymentId
    )
 
    goSdk.requestReversal(
        voidRequest
    ).collectLatest { reversalPaymentState ->
 
        when (reversalPaymentState) {
            is ReversalPaymentState.OnReversalPaymentError -> {
                println("Void request failed: ${reversalPaymentState.error}")
                updateUI(reversalPaymentState)
            }
            is ReversalPaymentState.OnReversalPaymentComplete -> {
                println("Void request succeeded: ${reversalPaymentState.response}")
                updateUI(reversalPaymentState)
            }
            else -> {
                //Something unexpected happened
            }
        }
    }
}

iOS

To reverse a payment, enter values of paymentId and the amount with the reverse() function under the ReversalRequest.

let reversalRequest = ReversalRequest(amount: amount, paymentId: paymentId)
 
do {
   let reversalResponse = try await CloverPaymentSDK.shared.reverse(reversalRequest:reversalRequest)
   print("reversal success: \(reversalResponse)")
} catch {
   print("reversal failure: \(error)")
}