Refund, reverse, or cancel a payment

Look up the transfer

Get the transfer with the get transfer endpoint to see its rail and state:

curl -X GET "https://api.moov.io/accounts/{partnerAccountID}/transfers/{transferID}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

Check these fields:

• source.paymentMethodType: card-payment for cards; ach-debit-fund or ach-debit-collect for ACH debits
• source.cardDetails.status: initiated or confirmed means the card payment hasn't settled, so it can still be canceled. settled or completed means it needs a refund.
• source.achDetails.status and destination.achDetails.status: initiated means the ACH leg hasn't originated yet, so you can cancel; originated or later means you can't
• status: failed or canceled transfers have nothing to undo, and reversed means the funds already went back
• refundedAmount, refunds, and cancellations: any earlier attempts on this transfer

Deeper guides: card payment timing and ACH statuses.

Reverse a card payment

For a full refund of a card payment, call the reversals endpoint without a body. An X-Idempotency-Key is required; reuse it if you retry the same request.

curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers/{transferID}/reversals" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: 3b9c2f1e-8a47-4d6b-9e21-5c7f0a1d2e34"

The response tells you which action Moov took. A cancellation object, usually with status completed, means the authorization was reversed and the transfer's status becomes canceled. A refund object, usually pending at first, means a credit is on its way to the card. You can also start a reversal in the Dashboard from the transfer's details page with the Refund button. Deeper guide: reversals.

Refund part of a card payment

To return part of the amount, send an amount in cents. Because a card authorization can't be partially canceled, Moov always issues a refund for a partial amount, even if the payment hasn't settled. The cardholder sees the full charge, then a credit for the partial amount.

curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers/{transferID}/reversals" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: 7e1d4a2b-6c93-4f08-b5d2-1a9e3c8f6b70" \
  -d '{ "amount": 1000 }'

Rules for refunds:

• You can't refund more than the original amount, and only one refund can be in progress at a time for each transfer.
• Refunds can't be canceled once issued. If a refund fails, you can try again on the same transfer.
• The refund amount is debited from the merchant's wallet immediately. The cardholder usually sees a pending credit right away that posts in 5-7 business days, depending on their bank.
• If the payment included a surcharge, a full reversal refunds the surcharge automatically. For a partial refund, use the refunds endpoint and specify the proportional surcharge in amountDetails.

Deeper guide: refunds.

Cancel an ACH transfer

ACH transfers can be canceled only before the relevant leg originates: the debit for bank-to-wallet transfers, and the credit for wallet-to-bank and bank-to-bank transfers. Call the cancel a transfer endpoint:

curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers/{transferID}/cancellations" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: c4f8a1d2-3e57-4b96-8a0c-2d6e9f1b7a53"

The response has a cancellationID and a status of pending, completed, or failed. For a bank-to-bank transfer whose debit already originated, the cancellation stays pending while Moov waits for the debit to complete, then credits the source wallet instead of sending the credit leg. If the transfer already originated, failed, or completed, you get a 400. Requests made very close to origination can also fail. Check progress with the cancellation details endpoint.

Canceling a transfer in a transfer group also cancels the transfers after it in the group. It doesn't affect future scheduled transfers. Deeper guide: ACH cancellations.

Return funds after an ACH payment originates

Once an ACH payment originates, you can't cancel it, and the refunds endpoint only supports card transfers. ACH returns are started by the bank, not by you. To give a customer their money back, create a new transfer in the opposite direction with the create transfer endpoint: from the wallet that received the funds to an ACH credit payment method on the customer's bank account.

curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: 9a2e6c1f-4b38-4d75-a0e9-8f3b1c5d2a64" \
  -d '{
    "source": { "paymentMethodID": "{merchantWalletPaymentMethodID}" },
    "destination": { "paymentMethodID": "{customerAchCreditPaymentMethodID}" },
    "amount": { "currency": "USD", "value": 2500 },
    "description": "Refund for order 1042"
  }'

Find both payment method IDs with the list payment methods endpoint. Use ach-credit-standard or ach-credit-same-day for the destination, or instant-bank-credit if the customer's bank supports instant payments. Use foreignID or metadata on the transfer to link it to the original payment in your records. Deeper guide: send funds.

Track the outcome

Each action has its own events:

• Cancellations: cancellation.created, then cancellation.updated with status completed or failed. The transfer's status becomes canceled, and card transfers also show source.cardDetails.status canceled.
• Refunds: refund.created, then refund.updated with status pending, completed, or failed. The refund's cardDetails.status moves through initiated, confirmed, settled, and completed.
• Reversals: produce cancellation or refund events, depending on which action Moov took, plus transfer.updated.

To check a refund directly, use the retrieve refund endpoint:

curl -X GET "https://api.moov.io/accounts/{partnerAccountID}/transfers/{transferID}/refunds/{refundID}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

If a refund fails, cardDetails.failureCode explains why, such as suspected-fraud. A 4xx response to a reversal request means the card network declined it or a processing error occurred; retry with a new idempotency key. Deeper guide: reversal settlement status.