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:
- Create a global developer account with a default test merchant account.
- Create additional test merchants, if needed.
- Create an app in the sandbox.
- Create at least one employee role user for the OAuth flow.
- Order a Clover Go reader Developer Kit (Dev Kit) and set it up.
Field descriptions
ReversalRequest
Field | Required | Type | Description |
---|---|---|---|
PaymentId | true | String | Clover-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. |
amount | false | Int64 | Refund 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
Field | Type | Description |
---|---|---|
PaymentId | String | Clover-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. |
result | ReversalResult | Indicates if the payment is voided or refunded in case of successful reversal. Values: - Void - Refund |
voidReason | VoidReason | Reason for the reversal is voided. Value:The default value is USER_CANCEL, since it is requested by the integrator or user. |
refund | Refund | Refund 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 theReversalResponse
. - 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)")
}
Updated 6 months ago