Process a refund

A refund is a two-step flow. First you create the refund on the server. Strimz validates the amount against the original transaction and returns wallet-signing instructions. Then you sign the on-chain transfer from your own wallet to the customer's. The indexer watches Arc and marks the refund completed once the transfer confirms.

Why Strimz doesn't refund for you

The obvious alternative would be to hold your USDC and refund out of it. That would put Strimz in the money-transmission business, which is a regulated activity in most jurisdictions, and would put your money on the Strimz balance sheet instead of yours. Every refund signed from your own wallet leaves a clean on-chain trail between you and the customer, with no intermediary in between.

Issue a refund

const refund = await strimz.refunds.create({
  transactionId: 'tx_xyz',
  amount: '50000000', // 50 USDC, 6 decimals. Partial refunds are fine.
  reason: 'customer_request', // 'customer_request' | 'product_issue' | 'duplicate_charge' | 'fraudulent' | 'other'
  note: 'Customer asked nicely',
})
 
console.log(refund.signingInstructions)
// {
//   token:  '0x...USDC',
//   to:     '0x...payerAddress',
//   amount: '50000000',
//   note:   'Refund for transaction tx_xyz',
// }

The signingInstructions object tells the merchant's wallet what to sign:

// Using viem from the merchant dashboard
import { createWalletClient, http, parseUnits } from 'viem'
import { erc20Abi } from 'viem'
 
const wallet = createWalletClient({
  account: merchantAddress,
  chain: arcMainnet,
  transport: http(),
})
 
const txHash = await wallet.writeContract({
  address: signingInstructions.token,
  abi: erc20Abi,
  functionName: 'transfer',
  args: [signingInstructions.to, BigInt(signingInstructions.amount)],
})

Submit the tx hash

Once the merchant has the tx hash, post it back to Strimz:

await strimz.refunds.submitSignature(refund.id, { refundTxHash: txHash })

This flips the refund from awaiting_signature to submitted. The indexer is watching for ERC-20 Transfer events with this tx hash; when one lands, it flips the refund to completed and fires refund.completed.

Cumulative caps

Strimz won't let you refund more than the original transaction:

// Original transaction: 100 USDC
 
await strimz.refunds.create({
  transactionId: 'tx_x',
  amount: '60000000',
  reason: 'customer_request',
})
// ok: 60 of 100 refunded
 
await strimz.refunds.create({
  transactionId: 'tx_x',
  amount: '50000000',
  reason: 'customer_request',
})
// 400 invalid_request: 60 + 50 > 100

The cap is computed across refunds with status submitted or completed. An awaiting_signature refund that the merchant abandons doesn't lock funds. You can void it (delete the row) and re-create.

What if the indexer never sees the on-chain transfer?

This happens if the merchant submitted the wrong tx hash. The refund stays in submitted indefinitely. To fix:

await strimz.refunds.submitSignature(refund.id, { refundTxHash: correctTxHash })

Re-submitting overwrites idempotently. The indexer's matcher then finds the right Transfer and completes the refund.

If the merchant submitted a real hash but the on-chain transfer was for the wrong amount, the refund row records the original intent amount and the on-chain transfer's amount separately. The dashboard surfaces the discrepancy so finance can reconcile.

What if the customer's address is invalid?

You can't get this far. Strimz validates Refund.payerAddress is a valid 20-byte EVM address at create time, and the original transaction's payer address is recorded on-chain. Strimz uses that recorded address rather than anything you pass in. The only way to could be wrong is if the customer's wallet itself is wrong, which Strimz can't prevent.