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

Create a refund

Use the Cancel or refund a card transfer endpoint for more comprehensive cancel and refund options. See the reversals guide for more information.

Initiate a refund for a card transfer.

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}/refunds
cURL 
1
2
3
4

curl -X POST "https://api.moov.io/transfers/{transferID}/refunds" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
200 202 400 409 422 429
Successfully initiated a card refund.
{
  "amount": {
    "currency": "USD",
    "value": 1204
  },
  "createdOn": "2023-09-09T14:15:22Z",
  "refundID": "d4963079-5b35-4d17-981e-8f851753f786"
}
A refund was successfully created but an error occurred while waiting for a synchronous response.
{
  "amount": {
    "currency": "USD",
    "value": 1204
  },
  "createdOn": "2023-09-09T14:15:22Z",
  "refundID": "d4963079-5b35-4d17-981e-8f851753f786",
  "status": "created",
  "updatedOn": "2023-09-09T14:15:22Z"
}
Invalid request, an error message will be available in the response body.
Error response for http requests that failed.
{
  "error": "example error message"
}
Attempted to initiate a refund using a duplicate X-Idempotency-Key header.
Details of a card 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",
  "failureCode": "call-issuer",
  "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

X-Retry-In

string <duration>
How long (in milliseconds) to wait until able to retry the request.

Headers

X-Idempotency-Key

string <uuid> required
Prevents duplicate refunds from being created. Note that we only accept UUID v4.

X-Wait-For

string
Optional header that indicates whether to return a synchronous response that includes the full refund and card transaction details or an asynchronous response indicating the refund was created (this is the default response if the header is omitted).
Possible values: rail-response

Path parameters

transferID

string <uuid> required
Identifier for the transfer.

Body

application/json
Specifies a partial amount to refund. This request body is optional, an empty body will issue a refund for the full amount of the original transfer.

amount

integer<int64>
Amount to refund in cents. If null, the original transfer’s full amount will be refunded.

Response

application/json
Asynchronous refund response Synchronous refund response

amount

object
A representation of money containing an integer value and its 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, so $12.04 is 1204 and $0.99 would be 99.

createdOn

string<date-time> <=24 characters

refundID

string<uuid> <=36 characters Pattern
UUID v4
Details of a card refund.

amount

object
A representation of money containing an integer value and its 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, so $12.04 is 1204 and $0.99 would be 99.

cardDetails

object
right_key Show child attributes

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

status

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

createdOn

string<date-time> <=24 characters

failureCode

string deprecated
This field is deprecated and will be removed in December 2023.
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

refundID

string<uuid> <=36 characters Pattern
UUID v4

status

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

updatedOn

string<date-time> <=24 characters