Docs / Refunds and payouts
How do you refund a crypto payment? Payouts, approvals and limits
An on-chain payment cannot be reversed, so a refund is simply a new payout. The payout flow has a few security checks worth knowing in advance.
The short version: on-chain payments cannot be reversed. There is no automatic chargeback and no automatic refund. A refund is a payout that you start manually, sent from the hot wallet to the customer's address. The payout flow has several safety checks: an address book, approvals, one-time codes and limits. Before refunding, check the address and the network.
1. What a refund is
Cards have chargebacks. On-chain transfers do not. Once funds are confirmed they cannot be recalled, so a refund can only be a further transfer made by the merchant, sending the agreed amount back to the customer's wallet address. The official documentation says the same: refunds must be handled manually through the dashboard or the API.
The transfer is sent from the project's hot wallet. If no hot wallet is configured for the project, or the hot wallet lacks the coin or the gas, it cannot be sent. See wallet roles.
The official flow uses email to deliver one-time codes, so an email service must be set up. On PayRamHost, whether payouts and approvals are enabled for your account is shown by your dashboard. If you are unsure, contact us.
2. What to check before you refund
- Did the payment really succeed? Confirm in the dashboard or with the status endpoint that the state is
FILLEDorOVER_FILLED. Do not rely on a customer's screenshot. See payment statuses. - Get the destination address and network from the customer in writing, and have them confirm it again. The official documentation warns plainly that the network and the address must match. If they belong to different blockchains, the payout fails and funds may be lost.
- Do not assume you can send it back the way it came. The payment record has a source address, but if the customer withdrew from an exchange, that source is often an exchange address and a refund sent there may not be credited to the customer. Ask the customer for their own wallet address.
- Coin and amount. Confirm how much, in which coin and on which chain, and check that the hot wallet has enough of that coin and enough gas.
- Keep a record. Link the refund to the original order's
invoice_idandreference_idso reconciliation is easy.
3. The payout flow: from creation to sending
According to the official documentation, a payout in the dashboard works like this:
- In the left Withdraw menu open Payouts.
- Add the recipient to the Address Book. Click Add New and enter the network, wallet address and any notes. Saving needs a one-time code to confirm. The address book exists so that every payout goes to the right address.
- Go back to the payout page, click Create Payout, choose the recipient, enter the amount and create it.
- The payout request appears in the dashboard and waits for approval (see the next section). Once approved it is queued and sent on-chain.
Putting the recipient in the address book before paying out is a deliberate error check in the design: it avoids mistyping an address each time.
4. Approvals and one-time codes
- Payouts created by non-admin roles need an administrator's approval before they are processed.
- When approving, a 6-digit code is emailed to the approving administrator's own address and is valid for 10 minutes. The approval takes effect only when the code is entered.
- Who can approve: Root and Admin (any payout, including ones they created) and Project Admin (payouts of the projects they administer). Other members cannot approve even a payout they created.
- A rejected payout becomes
rejected, which is final.
The point of this design is that nobody can move money alone. When you assign permissions to a team, keep the person who creates a payout separate from the person who approves it.
5. Payout limits
Limits are set per project and decide whether a new payout is sent, held for approval or rejected:
| Setting | Effect |
|---|---|
| Auto-approve (on/off) | When off, every payout waits for approval |
| Auto-approve amount | Payouts above this amount are held for approval |
| Daily limit | A payout that would take that account's total over the limit for the last 24 hours is held |
| Hourly limit | The same, over the last 60 minutes |
| Minimum amount | Payouts below this amount are rejected |
A value of 0 has special meaning for some settings: an auto-approve amount of 0 means every payout is held; a daily or hourly limit of 0 means no limit; a minimum amount of 0 means no minimum. A blank field inherits the default setting. Changes apply only to payouts created afterwards.
6. What each payout status means
| Status | Meaning |
|---|---|
pending-approval | Waiting for approval |
pending-otp-verification | An administrator approved it and the emailed code has yet to be entered |
pending | Queued to send. If the hot wallet cannot cover it yet, it waits up to 48 hours for you to top it up, then fails |
initiated | Broadcast on-chain and has a transaction hash. The hash can change during this stage because of a fee bump, so always use the latest one |
sent | Confirmed on-chain. The money has left, so treat this as success. A sent payout never becomes failed |
processed | System bookkeeping is done. There is no webhook for it and you do not need to wait for it |
failed | It did not go through. See the failure reason |
rejected | Rejected by an administrator |
cancelled | Cancelled before it was sent |
The final states are sent, failed, rejected and cancelled.
7. Starting a payout through the API
Your own code can also start a payout with a project API key, using POST /api/v1/withdrawal/merchant. A payout created through the API is subject to the same limits and approval rules as above. One held by a limit goes to awaiting approval, and approval still happens in the dashboard and cannot be done through the API. You can track a payout with webhooks or the query endpoint. For the exact fields, the official PayRam documentation is authoritative.
For supported networks and coins see which blockchains and coins PayRam supports: Bitcoin can be received but payouts are not supported.
8. FAQ
Can I refund only part of a payment?
Yes. You enter the payout amount yourself and there is no requirement to refund in full. Record the reason and the amount in the order notes.
Who pays gas on a refund?
The hot wallet pays it, so the merchant bears it, and it is not part of the service fee.
What if I send to the wrong address?
An on-chain transfer cannot be recalled. If you send to the wrong address or network the funds usually cannot be recovered. That is why you use the address book, have the customer confirm the address, and verify a new address with a small amount first.
How do I refund an underpayment or overpayment?
For an overpayment you can refund the excess or record it as customer credit against future invoices. For an underpayment, have the customer top up, or refund what was received. See payment statuses.
Related reading
- Wallet roles: What each of the four wallets in PayRam does: the master account deploys contracts, deposit wallets receive customer payments, the cold wallet holds the final funds and the hot wallet only pays gas and sends payouts, plus how much to keep in each and where the keys live.
- Payment statuses: What PayRam's five payment statuses mean, how to handle underpaid (PARTIALLY_FILLED), overpaid (OVER_FILLED) and expired (CANCELLED) payments, and how to keep your order status in sync using webhooks and the status endpoint.
- Merchant guide: A step-by-step guide to the PayRam merchant dashboard, from logging in to your first payment: nodes, wallets, hot wallet, payment links, the API and webhooks.