POST endpoint offers a robust solution for returning funds to a cardholder, regardless of the current state of the transfer. When possible, the reversals endpoint cancels the transfer, reversing the authorization and swiftly returning funds. If settlement is in progress or completed, a refund is issued instead. Canceling a transfer offers certain advantages over refunds, such as reducing processing costs and expediting returns to cardholders.
- A reversal cannot exceed the original transfer amount
- Once requested, reversals cannot be canceled
- Avoid requesting a reversal for a payment disputed by the cardholder to prevent a potential double charge
- If a reversal request fails, you can initiate it again for the same transfer
Initiating a reversal via the API
Use the reversals
POST endpoint to initiate a reversal. This endpoint dynamically orchestrates one of two actions based on the settlement process:
- Cancels the transfer (reverses the authorization) if it hasn’t been settled yet
- Initiates a refund if the transfer is already in the process of settlement, or has been settled
amount parameter in the request body specifies the reversal amount. Its behavior is as follows:
- No amount specified: Moov first attempts to cancel the transfer. If settlement is in progress or complete, a full refund is initiated.
- Partial amount specified: Moov immediately initiates a partial refund, as partial cancellations aren’t supported. The cardholder will see a full debit followed by a partial credit.
Initiating a refund via the Moov Dashboard
In the dashboard, you can initiate a refund on the Transfer details page.
Once initiated, you can choose whether it’s a full or partial refund, and note how much you’re refunding. If you initiate a full refund, and the transfer has not settled, you will be notified that the transfer has been canceled.
Afterwards, Moov will populate relevant information and status in the transfer details section and the timeline.
Moov automatically checks the settlement status to determine if a transfer can be canceled. A successful request updates the transfer status to
canceled, reversing the pending authorization. If settlement has already begun, a refund is initiated, which you can monitor using the refunds webhooks and the refunds
Moov provides a synchronous response to inform you of the reversal outcome, including relevant details based on whether a cancellation or refund occurred.
A cancellation typically completes instantly. However, if there’s an error with the card network response, a pending status is returned until a confirmation is received.
4xx error after reversal initiation signifies a decline from the card networks or a processing error. Retry the request with a new idempotency key. Refer to the reversal API docs for further information on HTTP error codes.
A refund will have a status of
failed depending on if it was authorized or declined by the card networks.
Refund and cancel statuses
Use the refunds
GET endpoint to retrieve the refund status. If a refund was initiated, a
200 response with the current refund status is received.
If a transfer has a refund in any status, we’ll also include that information in the transfers object itself.
There is a webhook event you can subscribe to that will provide you with relevant reversal updates:
transfer.updatednotifies you once the reversal status changes to any of the following:
There are also two webhook events you can subscribe to that will provide you with relevant refund updates:
refund.creatednotifies you when the refund was successfully created
refund.updatednotifies you once the refund status changes to any of the following: