Refunds

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));

Initiating a refund via the Moov Dashboard

In the dashboard, you can initiate a refund on the Transfer details page.

Initiate a refund

Once initiated, you can choose whether it’s a full or partial refund, and note how much you’re refunding.

Initiate a refund

Afterwards, Moov will populate relevant information and status in the transfer details section and the timeline.

Refund statuses

Moov continues to support the refund status GET endpoint and the refund list GET endpoint for tracking and managing refunds.

See the Reversals guide for refund status and webhook information.