Refund

Handling Refunds with the SDK

Overview: Processing refunds is a crucial functionality for any payment gateway or service. Within our SDK, while the underlying mechanics resemble payment transactions, there are some nuances to consider for refunds. Let's delve into how the Prophius SDK manages refund operations.

1. Preliminary Steps for Refunds:

• Receipt Collection:

  • Purpose: To have a concrete reference for the transaction being refunded.

  • Action: The merchant must request the payment receipt from the customer. This receipt contains essential transaction details, most crucially, the transaction code.

• Transaction Search:

  • Purpose: To locate the specific transaction in the system and ensure it's valid for a refund.

  • Action: Using the provided transaction code from the receipt, the merchant searches for the corresponding transaction using refundInquiry fuction of the SDK.

Transaction Inquiry for Refund

This function is used to search the specific transaction in the system

PayContactlessEmbed.getInstance().refundInquiry(@Nullable String transactionCode, @NonNull InquiryListener listener)

Inquiry Listener

public interface InquiryListener {
   void onSuccess(InquiryResult transaction);
   void onFailure(Error error);
}

Inquiry Result

data class InquiryResult(
    var cardNumber: String?,
    var amount: Double,
    var currency: Int
)

Field Names	Field Descriptions	Values
CardNumber	masked card number used in transaction	************6375
Amount	amount value of the transaction	5.00
Currency	amount current of the transaction	566
Error	Check 6.1 Error Handling section

2. Initiating the Refund Process:

Once the transaction is located, the refund can be processed. There are typically two scenarios to consider:

• Full Refund:

  • Scenario: Customer requests a complete refund of the transaction amount.

  • Action: The SDK's doRefund method is called with the full transaction amount.

• Partial Refund:

  • Scenario: Customer only requests a part of the transaction amount to be refunded.

  • Action: The SDK's doRefund method is invoked with the specified partial amount.

4. Communicating the Refund Status:

The outcome of the refund, be it success or failure, should be clearly communicated back to the customer. Use the RefundResult instance, similar to TransactionResult, to guide this process.

In Summary: Refunds, while similar in structure to payments within the SDK, require an added layer of preparation at the application level. Ensure your application provides a smooth refund process, as it enhances customer trust and the user experience.

Parameters:

1. Amount:

   • Description: Denotes the transaction's value as specified by the user.

   • Constraints:

     • Should be a whole number, with its length capped at 12 digits.

     • Exclude any separators or currency symbols.

   • Examples:

     • A payment amount of $100 should be conveyed as 10000, where the trailing two digits represent cents.

     • Conversely, $1.01 is represented as 101.

2. Transaction Code:

   • Description: Transaction code value confirmed according to refundInqury response.

3. Description

   • Description: Provides contextual information detailing the purpose or reason behind the payment. It could relate to the product/service name, a brief summary, or any relevant description the merchant deems necessary.

4. Currency Code

   • Description: The currecy value of the transaction. It has be numeric code of ISO 4217 format.

   • Examples:

     • 566 for Naira instead of NGN

5. Activity

   • Description: The current activity. Payment page is started as a new activity. In order to start payment activity Embed SDK needs the current acitivity of the app.

6. RFU Map

   • Description: RFUMap (Reserved for future use) object is used to transfer key value pairs between backend system and merchant application

7. TransactionResultListener:

   • Description: This interface is vital as it captures and manages transaction outcomes, be it success or failure scenarios.

Full Refund

This function is used for refunding all of the amount of the transaction.

PayContactlessEmbed.getInstance().doFullRefund(@NonNull String amount, @NonNull String transactionCode, @Nullable String description, @Nullable String currencyCode, @NonNull FragmentActivity activity, @Nullable Map<String, String> rfuMap, @NonNull TransactionResultListener listener)

If currency parameter is set null, the default currency is used for transaction. The default currecny is Naira in SDK.

Please check details for TransactionResultListener on Sale section.

Sale

Partial Refund

This function is used for refunding a part of the amount of the transaction. E.g. User buys two piece of goods, but he/she wants to return only one piece.

PayContactlessEmbed.getInstance().doPartialRefund(@NonNull String amount, @NonNull String transactionCode, @Nullable String description, @Nullable String currencyCode, @NonNull FragmentActivity activity, @Nullable Map<String, String> rfuMap, @NonNull TransactionResultListener listener)

If currency parameter is set null, the default currency is used for transaction. The default currecny is Naira in SDK.

Please check details for TransactionResultListener on Sale section.

Sale