Guides API reference Use cases Changelog

Refunds

The refunds endpoint sends a full or partial credit back to the card used for a payment. For most cases, use reversals instead: it cancels the payment if it hasn't settled, which is cheaper and faster, and refunds it if it has.

Use the refunds endpoint directly when you need a partial refund on a payment with a surcharge. Refunds apply to card payments only; ACH transfers can be canceled before they originate.

Refund rules

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

Create a refund

Full refund

Call the refunds POST endpoint without a request body.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/refunds" \
  -H "Authorization: Bearer {token}" \
  -H "x-idempotency-key: UUID" \
  -H "X-Wait-For: rail-response" \
  -H "x-moov-version: v2026.07.00"

Partial refund

Include an amount in the request body.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/refunds" \
  -H "Authorization: Bearer {token}" \
  -H "x-idempotency-key: UUID" \
  -H "X-Wait-For: rail-response" \
  -H "x-moov-version: v2026.07.00" \
  --data-raw '{
    "amount": 1000
  }'

You can also refund from the Dashboard.

Track the refund

The refund's status is pending, completed, or failed, and cardDetails.status gives the rail detail. Subscribe to refund.created and refund.updated, or call the retrieve a refund endpoint. Status definitions are in reversals.