Refunds and disputes

​

Introduction

This page deals with Intent Refunds and Intent Disputes in more detail – ensure that you are familiar with how Echo works and basic integration aspects before continuing. When a refund or dispute occurs on a payment processed by a third-party PSP, the actions your platform needs to take depend on where the payment is in its lifecycle. Echo operates based on funds continually coming through the technical wallet and being distributed to sellers. In a refund or dispute scenario, the stream of funds is not constant. Therefore, careful handling of these cases is necessary to prevent delays in the settlement cycle.

​

Intent not captured

If a refund is requested by the buyer or a dispute occurs while the Intent’s Status is AUTHORIZED, then call the POST Cancel an Intent endpoint to cancel the Intent. In some cases, the PSP will not provide a settlement line because there was no capture and so they are not present in the Settlement file.

​

Intent captured

Once the Intent has been captured, either partially or fully, then you need to use the Intent Refund or Intent Dispute endpoints to declare the event to Echo. These API objects allow Echo to track the funds that are expected to arrive on the technical wallet. The Status of an Intent Refund or Dispute impacts whether the amount of the settlement line must be positive or negative, to enable Echo to reconcile it correctly. See the section settlement file amount calculation for more details on this process. The Intent Refund or Dispute must appear in the Settlement file so that Echo can perform reconciliation correctly. Any lines that appear in the same file offset each other and are handled automatically by Echo’s reconciliation process.

​

Intent Refund

If a refund is requested, fully or partially, call the POST Create an Intent Refund endpoint. In this case the corresponding amount is not expected on the technical wallet, and therefore the amount of the refund transaction in the Settlement file must be negative.

​

Reverse an Intent Refund

For some payment methods, particularly those involving bank wire transfers, it can happen that a refund cannot be processed and the funds are returned to your platform. This scenario also needs to be declared, because the funds are now expected on the technical wallet. In this scenario, therefore, you need to call the POST Reverse an Intent Refund endpoint to declare this, and the settlement line must be positive.

​

Intent Dispute

If a dispute occurs, then call the POST Create an Intent Dispute endpoint to declare the dispute. You need to track the outcome of the dispute using the PUT Update an Intent Dispute endpoint:

• DISPUTE_WON – The dispute was ruled in favor of your platform. The Settlement file includes the transaction with this status and the amount is positive, indicating that the funds are expected on the technical wallet.
• DISPUTE_LOST – The dispute was ruled against of your platform. The Settlement file includes the transaction with this status and the amount is negative, indicating that the funds are not expected on the technical wallet.

You can use the intermediary state, DEFENDED, if your PSP returns the funds to your platform while the outcome is being decided, but there is no movement of funds on Echo’s side until the outcome of the dispute is known (and declared).

​

Once funds arrive

If a refund or dispute is declared after the funds arrive, then its processing depends on the Intent Splits, which can be created at any time from the moment the Intent is captured.

​

Splits not executed

If the Split has not been executed and its Status is not yet COMPLETED, Echo automatically cancels the Split based on the Intent Refund or Dispute declared. In this case, the Split Status becomes REVERSED.

​

Splits executed

If the splits have already been executed when a refund or dispute is declared, then Echo attempts to refund the splits. This process returns the funds to the technical wallet to maintain the correct balance for the next settlement. When a Split Refund is triggered, the Split Status changes to REFUND_SPLIT_PENDING and then to a final state:

• REFUND_SPLIT_REJECTED – The Split Refund failed and there is therefore a deficit on the technical wallet that your platform needs to cover.
• REFUND_SPLIT_COMPLETED – The Split Refund succeeded and the funds were returned to the technical wallet from the seller wallet.

If a Split Refund fails, Echo does not retry it. The actions to take depending on the Split refund status are described below, as they depend on whether the funds have been paid out to the seller and your platform’s chosen approach.

​

Covering funds

If a split refund fails, then in all cases your platform needs to cover the refund or dispute deficit by funding the technical wallet. Otherwise, there may be an impact on subsequent settlement processing. To do so, transfer the refund or dispute amount from your platform wallet to the technical wallet, using POST Create a Transfer. When the recovery from the seller is completed, you can recover these funds as described in the options below.

​

After seller payout

If the transaction funds have already been paid out to the seller when the Intent Refund or Dispute is declared, then the appropriate approach may depend on your agreement with sellers and the guarantees you provide to buyers. Generally, there are three options, as described below. In all cases, because the Intent Splits were executed, Echo attempts to refund the Split as described above.

​

Option 1: Absorb the refund

Some platforms choose to take liability for the refund rather than pass it on to the seller. In this approach, if the Split refund fails, then there is no action needed. If the Split Refund succeeds, the transaction funds have moved from the seller wallet to the technical wallet. To absorb the refund and reimburse the seller, call the POST Create a Transfer endpoint to move the amount from the technical wallet back to the seller’s wallet.

​

Option 2: Reclaim the amount from a later settlement

Given that the seller will likely have funds arriving in their seller wallet from future transactions, you can use these funds in the process. The refund or dispute amount is deducted from the next payout to the seller. In this approach, if the Split Refund fails, then you need to:

1. Call the POST Create a Transfer endpoint to transfer the deficit amount from your platform wallet to the technical wallet
2. Once there are sufficient funds in the seller’s wallet, call the POST Create a Transfer endpoint again to transfer from the seller’s wallet back to your platform wallet

​

Option 3: Request repayment from the seller

You can also request the amount back from the seller. Given that it has already been paid out, this requires a pay-in. In this approach, if the Split Refund fails, then you need to:

1. Call the POST Create a Transfer endpoint to transfer the deficit amount from your platform wallet to the technical wallet
2. Request a pay-in from the seller, which can either be:
   • To the seller’s wallet, followed by a transfer to your platform wallet, or
   • To your platform wallet directly

For this pay-in, you can use the POST Create a Bank Wire PayIn endpoint or any other pay-in method you offer.