Release NotesAnnouncementsVideosBlog
Guides

Reverse a payment

United States

Use the ReversePaymentRequestIntentBuilder class to build an Intent to start an Activity that guides a user through the payment reversal steps. Payment reversal is processed as either a void or refund, depending on the requested amount and the time since the payment was taken.

If an amount is specified, the request must be processed as a refund. If the amount is not specified, either a void or full payment refund will be processed based on several factors including how the payment was taken, how much time had passed since the payment was taken, and what amount was being requested. The result Intent contains a field, Intents.REVERSE_PAYMENT_RESULTwhich will indicate if the payment was refunded or voided.

📘

NOTE

ReversePayment is also used for voiding/canceling pre-auth payments.

Prerequisites

Examples

Example—Full refund

You can build a reverse payment request (full amount) with a few lines of code.

val paymentId = payment.id // should be id from a payment/pre-auth
val context = this

val builder = ReversePaymentRequestIntentBuilder(paymentId)
val intent = builder.build(context)

Context context = this;
String paymentId = payment.getId(); // should be id from a payment/pre-auth
ReversePaymentRequestIntentBuilder builder = new ReversePaymentRequestIntentBuilder(paymentId);
Intent intent = builder.build(context);

The Intent can then be used to start the activity to process the reverse payment request.

Example—Partial refund

This is an example of a partial amount refund.

📘

NOTE

A partial refund cannot be processed on a non-finalized payment, that is, a payment awaiting closeout.

val paymentId = payment.id // should be id from a payment/pre-auth
val context = this

val builder = ReversePaymentRequestIntentBuilder(paymentId)
builder.amount(500) // requesting a $5 partial refund
val intent = builder.build(context)

Context context = this;
String paymentId = payment.getId(); // should be id from a payment/pre-auth
 
ReversePaymentRequestIntentBuilder builder = new ReversePaymentRequestIntentBuilder(paymentId);
builder.amount(500L); // requesting a $5 partial refund
Intent intent = builder.build(context);

Response details

When the reverse payment flow completes, the response is available through onActivityResult().

For a successful request:

  • Retrieve the refund paymentId object using the Intent: ReversePaymentRequestIntentBuilder.Response.PAYMENT_ID
  • Retrieve the refund object using the Intent: ReversePaymentRequestIntentBuilder.Response.REVERSE_PAYMENT_RESULT
  • Retrieve the voidpaymentId status using the Intent: ReversePaymentRequestIntentBuilder.Response.REFUND

For an unsuccessful request, retrieve the failure message using the Intent: ReversePaymentRequestIntentBuilder.Response.FAILURE_MESSAGE

Processing results

when(intent.getStringExtra(Intents.EXTRA_REVERSE_PAYMENT_RESULT)) {
   ReversePaymentResult.REFUNDED.name -> {
       val paymentId = intent.getStringExtra(Intents.EXTRA_PAYMENT_ID)
       val refund = intent.getParcelableExtra<Refund>(Intents.EXTRA_REFUND)
   }
   ReversePaymentResult.VOIDED.name -> {
       val paymentId = intent.getStringExtra(Intents.EXTRA_PAYMENT_ID)
   }
   ReversePaymentResult.FAILED.name -> {
       // request failed
       intent.getStringExtra(Intents.EXTRA_FAILURE_MESSAGE)
   }
}

public void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    String result = data.getStringExtra(Intents.EXTRA_REVERSE_PAYMENT_RESULT);
    if (result.equals(ReversePaymentResult.REFUNDED.name())) {
      String paymentId = data.getStringExtra(Intents.EXTRA_PAYMENT_ID);
      Refund refund = data.getParcelableExtra(Intents.EXTRA_REFUND);
    } else if (result.equals(ReversePaymentResult.VOIDED.name())) {
      String paymentId = data.getStringExtra(Intents.EXTRA_PAYMENT_ID);
    } else if (result.equals(ReversePaymentResult.FAILED.name())) {
      String failureMessage = data.getStringExtra(Intents.EXTRA_FAILURE_MESSAGE);
    }
  }

Updated 3 months ago