Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases API Changelog
  1. API reference
  2. Money movement
  3. Refunds

Cancel or refund a card transfer

Reverses a card transfer by initiating a cancellation or refund depending on the transaction status. Read our reversals guide to learn more.

To use this endpoint from the browser, you’ll need to specify the /accounts/{accountID}/transfers.write scope when generating a token.
POST
/transfers/{transferID}/reversals
cURL 
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
  }'
200 202 400 409 422 429
Successfully initiated a reversal.
cancellation-success
{
  "cancellation": {
    "createdOn": "2023-09-09T14:15:22Z",
    "status": "completed"
  }
}
refund-success
{
  "refund": {
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "cardDetails": {
      "confirmedOn": "2023-09-09T14:17:41Z",
      "initiatedOn": "2023-09-09T14:16:22Z",
      "status": "confirmed"
    },
    "createdOn": "2023-09-09T14:15:22Z",
    "refundID": "d4963079-5b35-4d17-981e-8f851753f786",
    "status": "pending",
    "updatedOn": "2023-09-09T14:17:41Z"
  }
}
Successfully initiated a reversal but an error occurred while waiting for a synchronous response.
Returns the cancellation or refund response, depending on whether the transfer was cancelled or refunded.
{
  "cancellation": {
    "createdOn": "2019-08-24T14:15:22Z",
    "status": "pending"
  },
  "refund": {
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "cardDetails": {
      "completedOn": "2019-08-24T14:15:22Z",
      "confirmedOn": "2019-08-24T14:15:22Z",
      "failedOn": "2019-08-24T14:15:22Z",
      "failureCode": "call-issuer",
      "initiatedOn": "2019-08-24T14:15:22Z",
      "settledOn": "2019-08-24T14:15:22Z",
      "status": "initiated"
    },
    "createdOn": "2019-08-24T14:15:22Z",
    "refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "status": "failed",
    "updatedOn": "2019-08-24T14:15:22Z"
  }
}
Reversal request failed, an error message will be available in the response body.
reversal-failure
{
  "error": "reversal request failed, please try again with a new idempotency key"
}
Attempted to initiate a reversal using a duplicate X-Idempotency-Key header.
Returns the cancellation or refund response, depending on whether the transfer was cancelled or refunded.
{
  "cancellation": {
    "createdOn": "2019-08-24T14:15:22Z",
    "status": "pending"
  },
  "refund": {
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "cardDetails": {
      "completedOn": "2019-08-24T14:15:22Z",
      "confirmedOn": "2019-08-24T14:15:22Z",
      "failedOn": "2019-08-24T14:15:22Z",
      "failureCode": "call-issuer",
      "initiatedOn": "2019-08-24T14:15:22Z",
      "settledOn": "2019-08-24T14:15:22Z",
      "status": "initiated"
    },
    "createdOn": "2019-08-24T14:15:22Z",
    "refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "status": "failed",
    "updatedOn": "2019-08-24T14:15:22Z"
  }
}
The request body could not be processed.
Request was refused due to rate limiting.

Response headers

Retry-After

number

Headers

X-Idempotency-Key

string <uuid> required
Prevents duplicate reversals from being created.

Path parameters

transferID

string <uuid> required
Identifier for the transfer.

Body

application/json

amount

integer<int64>
Amount to reverse in cents. If null, the original transfer’s full amount will be reversed. Partial amounts will automatically trigger a refund instead of a cancellation.

Response

application/json
Returns the cancellation or refund response, depending on whether the transfer was cancelled or refunded.

cancellation

object
right_key Show child attributes

createdOn

string<date-time> <=24 characters required

status

string<enum> required
Cancellation status.
Possible values: pending, completed

refund

object
Details of a card refund.
right_key Show child attributes

amount

object required
An integer value representing money in a specific currency.
right_key Show child attributes

currency

string <=3 characters Pattern
A 3-letter ISO 4217 currency code.

value

integer<int64>
Quantity in the smallest unit of the specified currency. In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

cardDetails

object
right_key Show child attributes

status

string<enum> required
Status of the refund.
Possible values: initiated, confirmed, settled, failed, completed

completedOn

string<date-time> <=24 characters

confirmedOn

string<date-time> <=24 characters

failedOn

string<date-time> <=24 characters

failureCode

string<enum>
Possible values: call-issuer, do-not-honor, processing-error, invalid-transaction, invalid-amount, no-such-issuer, reenter-transaction, cvv-mismatch, lost-or-stolen, insufficient-funds, invalid-card-number, invalid-merchant, expired-card, incorrect-pin, transaction-not-allowed, suspected-fraud, amount-limit-exceeded, velocity-limit-exceeded, revocation-of-authorization, card-not-activated, issuer-not-available, could-not-route, cardholder-account-closed, unknown-issue, duplicate-transaction

initiatedOn

string<date-time> <=24 characters

settledOn

string<date-time> <=24 characters

createdOn

string<date-time> <=24 characters required

refundID

string<uuid> <=36 characters required
UUID

status

string<enum> required
Possible values: created, pending, completed, failed

updatedOn

string<date-time> <=24 characters required