Reversals | Moov Documentation

This guide details how to reverse or refund transfers using Moov's flexible reversals endpoint.

The reversals 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.

Guidelines

• 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
• If a reversal includes a surcharge, the surcharge must be specified in the request

Initiate a reversal

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 yet settled
• Initiates a refund if the transfer is already in the process of settlement, or has been settled

The request body is optional and 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. The amount is required to process a partial refund.

Ask

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/reversals" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "x-moov-version: v2024.01.00" \

Ask

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/reversals" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "x-moov-version: v2024.01.00" \
  --data-raw '{\n    "amount": 1000 // $10.00\n  }'

For immediate error correction, we recommend requesting a full reversal and creating a new transfer to create a smoother cardholder experience.

You can also initiate a reversal through the Moov Dashboard.

Initiate a cancellation

While a reversal will cancel the transaction if possible, you also have the option of requesting a cancellation directly with the cancel a transfer POST endpoint.

Ask

If you request a cancellation, but the card network has already settled, you'll receive an error. If the cancellation window has passed, use the reversals or refunds endpoint instead.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/cancellations" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "x-moov-version: v2024.01.00" \

Ask

You can get the details of a cancellation using the cancellation details GET endpoint.

curl -X GET "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/cancellations/{cancellationID}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "x-moov-version: v2024.01.00" \

Settlement status

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 cancellation or refunds as well as the cancellation or refundsGET endpoints.

Moov provides a synchronous response to inform you of the reversal outcome, including relevant details based on whether a cancellation or refund occurred.

Ask

{
  "cancellation": {
    "cancellationID": "string",
    "createdOn": "2024-08-24T14:15:22Z",
    "status": "completed"
  }
}

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.

A 4xx error after reversal initiation signifies a decline from the card networks or a processing error. Retry the request with a new idempotency key. See our reversal API documentation for further information on HTTP error codes.

Ask

Ask

{
  "refund": {
    "refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "createdOn": "2024-08-24T14:15:22Z",
    "updatedOn": "2024-08-24T14:15:32Z",
    "status": "pending",
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "cardDetails": {
      "status": "confirmed",
      "confirmedOn": "2023-09-10T18:23:56Z"
    }
  }
}

A refund will have a pending status while waiting for authorization, or a failed status if it was declined by the card networks. The refund's cardDetails.status will update with one of the following detailed rail specific statuses:

If the refund status updates to failed, the cardDetails object will update with a failure code.

{
  "refund": {
    "refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "createdOn": "2024-08-24T14:15:22Z",
    "updatedOn": "2024-08-24T14:15:32Z",
    "status": "failed",
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "cardDetails": {
      "status": "failed",
      "failureCode": "suspected-fraud",
      "failedOn": "2023-09-10T18:23:56Z"
    }
  }
}

If a transfer has a refund or cancellation in any status, we’ll also include that information in the transfers response itself.

Ask

 "transferID": "string",
  "createdOn": "2024-08-24T14:15:22Z",
  "status": "canceled",
  "cancellations": [\
    {\
     "cancellationID": "string",\
     "createdOn": "2023-09-09T14:15:22Z",\
     "status": "completed"\
    }\
  ],

Webhooks

Subscribe to the following webhook event, which will provide you with relevant reversal updates:

• transfer.updatednotifies you once the reversal status changes to any of the following:

• canceled

  • source.canceled

Subscribe to the following webhook events, which will provide you with relevant cancellation updates:

• cancellation.created notifies you when the cancellation was successfully created

• cancellation.updatednotifies you when the cancellation was updated

• pending

  • completed
  • failed

Subscribe to the following two webhook events, which will provide you with relevant refund updates:

• refund.created notifies you when the refund was successfully created

• refund.updatednotifies you once the refund status changes to any of the following:

• pending

  • completed
  • failed