Refunds

This guide details Moov’s traditional refund method, however, Moov’s reversal method is more flexible. See notice below.

tip

We strongly recommend using the reversals POST endpoint for initiating refunds due to its broader functionality and enhanced flexibility. Reversals offer more flexibility to return funds to the cardholder, regardless of the state of a transfer. Based on the state of the transfer, Moov dynamically chooses the appropriate action, either a cancel or a refund.

If a transfer is in a state where it can no longer be canceled, the reversals endpoint will initiate a traditional refund, and submit the credit information to the cardholder’s issuing bank. Partial cancellations will also initiate the traditional refund process regardless of the transfer’s status since transfers cannot be partially canceled.

To streamline refunds, see the Reversals guide.

Guidelines

A refund immediately debits the destination wallet balance of the original transfer and returns either full or partial funds to the source card used in the transaction. Once a refund is initiated, Moov submits the credit information to the customer’s card issuer. Typically, customers should immediately see a pending credit to their card that posts within 5-7 business days, although the actual timing may vary by bank.

Only one refund can be initiated at a time per transfer
You cannot refund more than the original transfer amount
Refunds cannot be canceled after they are issued
To avoid a potential double charge, do not attempt to refund a payment that has been disputed by the cardholder
If the refund fails, you are able to initiate the refund again, for the same transfer

Initiating a refund via the API

You have the ability to initiate either a full or partial refund.

Full refund

To initiate a full refund using the API, use the refunds POST endpoint without a payload.

1
2
3


curl -X POST https://api.moov.io/transfers/{transferID}/refunds \
  -H 'Authorization: Bearer {token}' \
  -H 'X-Idempotency-Key: UUID' \

1
2
3
4
5
6


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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const myHeaders = new Headers();
myHeaders.append("X-Idempotency-Key", "UUID");
const requestOptions = {
  method: 'POST',
  headers: myHeaders
};

fetch(`https://api.moov.io/transfers/${transferID}/refunds`, requestOptions)
  .then(response => response.json())
  .then(result => console.log(result));

Partial refund

To initiate a partial refund using the API, you can use the refunds POST endpoint and include an amount in the payload.

1
2
3
4
5
6


curl -X POST https://api.moov.io/transfers/{transferID}/refunds \
  -H 'Authorization: Bearer {token}' \
  -H 'X-Idempotency-Key: UUID' \
  --data-raw '{
    "amount": 1000, // $10.00
      }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


const myHeaders = new Headers();
myHeaders.append("X-Idempotency-Key", "UUID");
const requestOptions = {
  method: 'POST',
  headers: myHeaders
},
  body: {
    "amount": 1000, // $10.00
    };  

fetch(`https://api.moov.io/transfers/${transferID}/refunds`, requestOptions)
  .then(response => response.json())
  .then(result => console.log(result));