# Refunds for Crypto and Wallet Payments

Use this page when a customer wants money back after a **completed** crypto or wallet payment.

> Important: This page covers **post-payment returns**.\
> It is different from **reclaim**.

* Use this page when the original payment completed and the merchant decides to return value to the customer.
* Use [Reclaiming Unconverted Crypto ](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto)when a payment ends as `underpaid`, `overpaid`, `expired`, `invalid`, or `cancelled` and funds remain unconverted.

### Current supported behavior

Bead does not currently support an API-driven refund workflow for crypto and wallet payments as part of the standard integrator flow.

For completed crypto and wallet payments, merchants should revert to their normal cash return policy.

That return policy is determined by the merchant and may include:

* cash
* ACH
* store credit
* another merchant-controlled return method

This guidance is the same for crypto and wallet payments processed through Bead.

### What merchants should do today

When a customer asks for money back after a completed payment:

1. Confirm that the original payment status is `completed`.
2. Apply the merchant’s normal return policy.
3. Record the return in the merchant’s own order, customer service, and accounting systems.
4. Communicate the return outcome to the customer through the merchant’s normal support or receipt process.

If the merchant supports both full and partial returns, those should also follow the merchant’s own return policy and internal process.

### What this page does not cover

This page does **not** apply when the payment ends in one of these statuses:

* `underpaid`
* `overpaid`
* `expired`
* `invalid`
* `cancelled`

In those cases, any unconverted funds are handled through Bead’s reclaim flow, not through a merchant refund flow.

### Legacy refund endpoints

You may still see refund-related endpoints in the OpenAPI, including:

* `GET /PaymentRefunds/quote`
* `POST /PaymentRefunds/start`
* `POST /PaymentRefunds/confirm`
* `GET /PaymentRefunds/{refundId}`
* `POST /PaymentPages/{id}/crypto/request-refund`
* `PATCH /Payments/{paymentId}/refund-email`

These endpoints are not the supported integration path for new crypto or wallet refund implementations.

Use the guidance on this page instead.

### Webhooks and polling

There is no supported refund-status webhook flow for crypto and wallet payment returns under the guidance on this page.

Do not design your integration around polling `GET /PaymentRefunds/{refundId}` for post-payment crypto or wallet refunds.

For supported real-time behavior, continue to use payment webhooks and payment status checks for the original payment lifecycle.

### Reporting and settlement impact

A completed payment should continue to be treated as the original completed payment in Bead.

If the merchant later chooses to return value to the customer under its own return policy:

* do not expect that return to be represented as the supported refund flow in Bead
* do not expect a Bead refund webhook as part of the supported pattern
* track that return in the merchant’s own order and accounting systems

This keeps the original payment lifecycle separate from the merchant’s later business decision to issue a return.

### Recommended integrator messaging

Make the distinction clear in your UI and support process:

* **Completed payment + customer wants money back** = merchant return policy
* **Underpaid, overpaid, expired, invalid, or cancelled** = Bead reclaim flow

This reduces confusion for customers and helps prevent them from being sent into the wrong flow.

### Example support language

Your original payment completed successfully. Returns for completed payments are handled according to the merchant’s normal return policy. This is separate from Bead’s reclaim flow, which only applies when a payment does not fully complete and funds remain unconverted.

### Related pages

* [Under- and Over-Payment Handling](https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling)
* [Reclaiming Unconverted Crypto](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto)
* [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses)
* [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks)