Refunds.

Because OpenSettle is non-custodial, the funds being refunded already live in your wallet — not ours. A refund is a transfer broadcast from the merchant settlement wallet back to the customer wallet of record. We build the unsigned transaction, the merchant signs and broadcasts it from their own wallet, and the chain reader confirms it. We never hold a key that could move funds on your behalf.

Refund a payment

Refunds attach to an existing confirmed payment — they aren't a standalone resource. Step one returns an unsigned tx envelope your wallet signs; step two reports the broadcast tx hash so the chain reader can watch for confirmation.

// 1. Build the unsigned refund tx (admin-only, step-up gated).
const { payment, unsignedTx } = await os.payments.refund("pay_9fX0a2E1", {
  amountMinor: 4900,  // $49.00 in minor units / cents (omit for full refund)
  reason: "requested_by_customer",
  // recipientAddress is only required if the original payer address wasn't
  // captured at payment time (legacy Phase 1 payments).
});

// 2. Merchant signs + broadcasts unsignedTx.evm with their own wallet.
//    The dashboard does this for you on the Refund button.

// 3. Tell OpenSettle the tx hash so the chain reader picks it up.
await os.payments.refundBroadcast(payment.id, {
  refundTxHash: "0x4ae1…b9d7",
});

Partial refunds

Pass amountMinor less than the original payment to refund partially; omit it for a full refund. Only one refund can be in-flight per payment at a time — the API rejects a second refund call while refundTxHash is set and unconfirmed.

Dashboard

From a payment row in the dashboard, click Refund, choose an amount, and sign the prepared transaction with your connected wallet. The dashboard then posts the broadcast tx hash to the API for you.

Webhooks

• refund.initiated — unsigned tx built and returned to the merchant; awaiting signature + broadcast.
• refund.broadcast — merchant reported the signed tx hash. Carries txHash.
• refund.confirmed — chain reader observed the required confirmations.
• payment.refunded — fires alongside refund.confirmed and flips the payment status to refunded.

Gas fees

Gas for refund transactions is paid by the merchant wallet — same as any outbound transfer. On EVM chains we estimate a tight upper bound and warn before broadcast if the estimate exceeds 1% of the refund amount (configurable). On Tron, gas is paid as TRX or burned as energy from the staking account; ensure the wallet holds at least 50 TRX of bandwidth for refund operations. Solana and L2 gas are typically below $0.01 and not worth surfacing.