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

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.

1
2
3

curl -X POST "https://api.moov.io/accounts/{accountID}/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/accounts/{accountID}/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.

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.

1
2
3

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

1
2
3

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

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 refunds GET endpoints.

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
7

{
  "cancellation": {
    "cancellationID": "UUID",
    "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"
    }
  }
}

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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 webhook events, which will provide you with relevant cancellation updates:

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