Refunds

Create

POST /v1/refunds
{
  "transactionId": "cmq4wf2b80004je6l7xq1c9ad",
  "amount": "50000000",
  "reason": "customer_request",
  "note": "Buyer asked for a refund"
}

Returns:

{
  "refund": {
    "id": "cmq4wh9de0006je6l2n5v0kqt",
    "transactionId": "cmq4wf2b80004je6l7xq1c9ad",
    "amount": "50000000",
    "status": "awaiting_signature",
    "reason": "customer_request",
    "payerAddress": "0x...",
    "createdAt": "..."
  },
  "signingInstructions": {
    "token": "0x...USDC",
    "to": "0x...payer",
    "amount": "50000000",
    "note": "Refund for transaction cmq4wf2b80004je6l7xq1c9ad"
  }
}

Submit signature

After the merchant broadcasts the on-chain ERC-20 Transfer, record the tx hash:

POST /v1/refunds/{id}/signature
{
  "refundTxHash": "0x..."
}

Lifecycle

awaiting_signature  →  submitted  →  completed

You can submit a signature only while the refund is awaiting_signature. Any other status returns 403 session_invalid_state, so record the right hash the first time. A refund can't be voided or deleted.

Validation

The original transaction must be in status confirmed.
The total of all refunds on a transaction can't exceed Transaction.amount. The total counts refunds in pending, awaiting_signature, submitted and completed, so an unsigned refund still holds its share.

Webhook events

Event	Fires when
`refund.created`	The refund row was created
`refund.completed`	The transfer confirmed on-chain with the right token, recipient and amount
`refund.failed`	The transfer reverted, paid the wrong token, recipient or amount, or can never land

refund.failed carries the refund, and its failureReason says which. A failed refund no longer counts toward the refundable total, so you can refund the payer again.

A transfer counts as never landing once your wallet has used its nonce for another transaction. If no node ever saw the transfer, Strimz can't prove that, and the refund stays submitted rather than risk refunding the payer twice.

Create

Submit signature

Lifecycle

Validation

Webhook events

On this page