Auto Refunds
An optional capability that automatically handles overpayments, underpayments, and late payments — either by refunding the customer or settling the funds received.
Auto Refunds is an opt-in capability. When enabled by BEEM on your merchant account, every inbound payment that hits an exception (overpayment, underpayment, or late payment) is handled automatically using rules BEEM configures for you. When the capability is off, exception payments retain their discrepancy status and require manual handling.
To enable Auto Refunds, contact your BEEM account manager.
Default behaviour (capability off)
By default, Auto Refunds is disabled on new merchant accounts. In that state:
- The original pay-in retains the relevant exception status (
UNDERPAID,OVERPAID,LATE) — see Payment Exceptions - Funds received sit in the receiving wallet
- No refund is created automatically
- Your team handles each exception manually — for example, by initiating a refund payout, contacting the customer, or accepting the partial amount
The merchant Portal shows all rules as — under Wallets → [merchant account] → Payment exceptions when the capability is off.
When the capability is on
Once BEEM enables Auto Refunds for your merchant account, two things happen:
- BEEM configures a behaviour for each of the three exception types (overpayments, underpayments, late payments).
- BEEM configures a billing preference for who absorbs the fees on the refund leg.
The rules apply to every Channel payment and Payment Link In on that merchant — there is no per-channel or per-payment override.
Exception types
Three exception types are governed by Auto Refunds:
| Exception | When it fires |
|---|---|
| Overpayments | The recipient receives more than the requested amount. |
| Underpayments | The recipient receives less than the requested amount. |
| Late payments | Funds arrive after the inbound expiry window — see Payment Exceptions. |
Behaviour options
Each exception type has its own behaviour setting. Two options are supported:
| Behaviour | What happens |
|---|---|
| Automatically refund sender wallet | BEEM creates an outbound refund and generates a refund URL. You send the URL to the customer; they nominate a refund address (and may choose the receiving asset). |
| Convert and settle to receiving wallet | BEEM converts the funds actually received into the requested asset and credits your merchant wallet. No refund is created and the pay-in settles. |
Per-exception independenceEach exception type can be configured independently — for example, overpayments could be set to "Convert and settle" while underpayments and late payments are set to "Automatically refund sender wallet".
The auto-refund flow
When Automatically refund sender wallet is the active behaviour, BEEM creates an outbound payment as a follow-up to the original pay-in. This appears as a separate transaction in your Payment Links list.
Refund transaction characteristics
| Field | Value |
|---|---|
type | OUT |
subType | merchantRefund |
reference | REFUND-{original-reference}-{suffix} — easy to correlate to the original pay-in |
redirectUrl | A Payment Link Out — Without Detail URL the customer uses to nominate their refund address and asset |
status (initial) | Awaits the customer to provide refund details, then transitions through PROCESSING to COMPLETE |
What the merchant does
- Detects the exception status on the original pay-in (via
status-changewebhook or the Portal). - Retrieves the linked refund payout (same
walletId, matchingREFUND-reference). - Sends the
redirectUrlto the customer through your chosen channel (email, support ticket, in-app message). - The customer opens the link, provides their refund address, and selects the asset they wish to receive.
- BEEM executes the refund and emits standard outbound webhooks.
Worked exampleA customer underpays a 100 USDT request, sending only 50 USDT. BEEM creates a refund payout for 49.833145 USDT (50 USDT less a refund processing fee of 0.166855 USDT). The customer is sent the refund URL, chooses to receive TRX on the Tron network, and provides their TRX address. BEEM converts the refund balance to TRX at the live rate and sends 153.858 TRX to the customer's nominated address.
Refund fees billed to
The Billing preference controls who pays the processing and network fees on the refund leg:
| Option | Behaviour |
|---|---|
| Merchant | Refund processing and network fees are debited from the merchant wallet in addition to the original refund amount. The customer receives the full amount back. |
| Customer | Refund fees are deducted from the refunded amount. The customer receives the original amount minus the fees. |
The default is Merchant.
Convert and settle behaviour
When the rule is set to Convert and settle to receiving wallet, no refund is created. Instead:
- The amount actually received is converted into the requested asset at the live rate
- Your merchant wallet is credited with the converted amount
- The original pay-in transitions to
COMPLETE - Standard inbound webhooks fire (
transaction-detected,transaction-confirmed,transaction-settled)
This is the simplest path for customers and removes the need for a refund URL handoff, at the cost of accepting whatever amount actually arrives.
In the merchant Portal
The active configuration shows under Wallets → [merchant account] → Payment exceptions with four read-only fields:
| Field | Description |
|---|---|
| Overpayments | The behaviour applied when the recipient receives more than the requested amount. |
| Underpayments | The behaviour applied when the recipient receives less than the requested amount. |
| Late payments | The behaviour applied when funds arrive after the expiry window. |
| Refund fees billed to | Who absorbs the processing and network fees on the refund leg — Merchant or Customer. |
If any field shows —, no rule has been configured for that exception type. Either the capability is off, or BEEM has not yet set a rule.