1. Guides
2. Money movement
3. Accept payments
4. Card acceptance

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

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

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.

1
2
3

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

1
2
3
4
5
6

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

You can also initiate a reversal through the Moov Dashboard.

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 refunds webhooks and the refunds GET endpoint.

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

1
2
3
4
5
6

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "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"
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "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"
    }
  }
}

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.

1
2

curl -X GET "https://api.moov.io/transfers/{transferID}/refunds/{refundID}" \
  -H "Authorization: Bearer {token}" \

1
2
3

mc, _ := moov.NewClient()

mc.GetRefund(ctx, "transferID", "refundID")

1
2
3
4
5
6

const moov = new Moov(credentialsObject);

const transferID = "UUID";
const refundID = "UUID";

const response = moov.transfers.getRefund(transferID, refundID);

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

Webhooks

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

• transfer.updated notifies you once the reversal status changes to any of the following:
  • canceled
  • source.canceled

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.updated notifies you once the refund status changes to any of the following:
  • pending
  • completed
  • failed