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 Go JavaScript

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" \

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


mc, _ := moov.NewClient()

transfer, err := mc.GetTransfer(ctx, "transferID")
if err != nil {
    // handle error
}

mc.RefundTransfer(ctx, transfer.TransferID, moov.CreateRefund{
    Amount: 1700,
})

1
2
3
4
5


const moov = new Moov(credentialsObject);

const transferID = "UUID";

const response = moov.transfers.refund(transferID);

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

{
  "amount": {
    "currency": "USD",
    "value": 1204
  },
  "cardDetails": {
    "failedOn": "2023-09-09T14:15:59Z",
    "initiatedOn": "2023-09-09T14:15:38Z",
    "status": "failed"
  },
  "createdOn": "2023-09-09T14:15:22Z",
  "failureCode": "insufficient-funds",
  "refundID": "d4963079-5b35-4d17-981e-8f851753f786",
  "status": "failed",
  "updatedOn": "2023-09-09T14:15:59Z"
}

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

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.

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.

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

An integer value representing money in a specific currency.

Show child attributes

currency


        string

<=3 characters

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.

createdOn


        string<date-time>

<=24 characters

refundID


        string<uuid>

<=36 characters

UUID v4

Details of a card refund.

amount


        object

An integer value representing money in a specific currency.

Show child attributes

currency


        string

<=3 characters

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

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.

refundID


        string<uuid>

<=36 characters

UUID v4

status


        string<enum>

Possible values: created, pending, completed, failed

updatedOn


        string<date-time>

<=24 characters

cURL Go JavaScript

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" \

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


mc, _ := moov.NewClient()

transfer, err := mc.GetTransfer(ctx, "transferID")
if err != nil {
    // handle error
}

mc.RefundTransfer(ctx, transfer.TransferID, moov.CreateRefund{
    Amount: 1700,
})

1
2
3
4
5


const moov = new Moov(credentialsObject);

const transferID = "UUID";

const response = moov.transfers.refund(transferID);

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

{
  "amount": {
    "currency": "USD",
    "value": 1204
  },
  "cardDetails": {
    "failedOn": "2023-09-09T14:15:59Z",
    "initiatedOn": "2023-09-09T14:15:38Z",
    "status": "failed"
  },
  "createdOn": "2023-09-09T14:15:22Z",
  "failureCode": "insufficient-funds",
  "refundID": "d4963079-5b35-4d17-981e-8f851753f786",
  "status": "failed",
  "updatedOn": "2023-09-09T14:15:59Z"
}

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

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.

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.

X-Retry-In


      string
      <duration>

How long (in milliseconds) to wait until able to retry the request.

Create a refund

Response headers

X-Retry-In

Headers

X-Idempotency-Key

X-Wait-For

Path parameters

transferID

Body

amount

Response

amount

currency

value

createdOn

refundID

amount

currency

value

cardDetails

completedOn

confirmedOn

failedOn

failureCode

initiatedOn

settledOn

status

createdOn

failureCode

refundID

status

updatedOn

Was this helpful?