1. Overview
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 optional 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.

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": "2019-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": "2019-08-24T14:15:22Z",
    "updatedOn": "2019-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": "2019-08-24T14:15:22Z",
    "updatedOn": "2019-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
4
5
6

const moov = new Moov(credentialsObject);
try {
  const refund = moov.transfers.getRefund(transferID, refundID);
} catch (err) {
  // ...
}

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