Getting Started

Refund Processing


Refunds are their own workflow — they need to reverse the original charge, return inventory to stock, update the accounting ledger, and notify the customer. By modeling refunds as a separate workflow, you get independent retry logic, a dedicated audit trail, and the ability to handle partial refunds.

Don't confuse this with the refund_charge compensation in payment processing — that's an immediate undo inside a payment that's still failing. This is a business process in its own right, usually started days later by a support tool or customer portal:

Compensation vs. Refund Workflow
Saga compensation
Undo, immediately

Runs inside the failing payment workflow. System-triggered, full amount, part of the original saga's journal.

Refund workflow
A process of its own

Started days later by support or the customer. Full or partial amount, own retries, own journal, own audit trail.

How it works

The four steps run in a deliberate order: the only step that can be declined goes first, and the bookkeeping that must never diverge from the money follows it.

Money Moves First, Books Always Follow
1
process_gateway_refundThe one step that can be refused — do it before recording anything
2
return_inventoryRetries until done — stock reflects the reversal
3
update_ledgerBooks follow the money, never lead it
4
send_refund_notificationLast — the customer hears about facts, not intentions
Once step 1 succeeds, steps 2–4 are inevitable — replayed and retried through any crash until complete.

That inevitability is the point. The failure mode this design eliminates is divergence: a refund issued at the gateway that never reaches the ledger. If the gateway refuses the refund, nothing was recorded anywhere; once it succeeds, the journaled refund_id guarantees the remaining bookkeeping runs to completion — a crash can delay the ledger entry, but it can never lose it.

Example: reverse, restock, record, notify

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[derive(Debug, Clone, Serialize, Deserialize)]
5
struct RefundRequest {
6
order_id: String,
7
charge_id: String,
8
amount: f64, // Full or partial amount
9
reason: String,
10
customer_id: String,
11
}
12
13
#[derive(Debug, Clone, Serialize, Deserialize)]
14
struct RefundResult {
15
refund_id: String,
16
status: String,
17
amount_refunded: f64,
18
}
19
20
#[task]
21
async fn process_gateway_refund(charge_id: String, amount: f64) -> Result<String> {
22
let refund = gateway::create_refund(&charge_id, amount).await?;
23
Ok(refund.id)
24
}
25
26
#[task]
27
async fn return_inventory(order_id: String) -> Result<()> {
28
warehouse::release_reservation(&order_id).await?;
29
Ok(())
30
}
31
32
#[task]
33
async fn update_ledger(order_id: String, refund_id: String, amount: f64) -> Result<()> {
34
accounting::record_refund(&order_id, &refund_id, amount).await?;
35
Ok(())
36
}
37
38
#[task]
39
async fn send_refund_notification(customer_id: String, amount: f64) -> Result<()> {
40
email::send_refund_confirmation(&customer_id, amount).await?;
41
Ok(())
42
}
43
44
#[workflow(name = "process_refund", version = "1.0.0")]
45
pub async fn process_refund(
46
ctx: WorkflowContext,
47
request: RefundRequest,
48
) -> Result<RefundResult> {
49
// Step 1: Process refund with payment gateway
50
let refund_id = ctx.execute_task(
51
process_gateway_refund, (request.charge_id.clone(), request.amount)
52
).await?;
53
54
// Step 2: Return inventory to stock
55
ctx.execute_task(return_inventory, request.order_id.clone()).await?;
56
57
// Step 3: Update accounting ledger
58
ctx.execute_task(update_ledger, (
59
request.order_id.clone(), refund_id.clone(), request.amount
60
)).await?;
61
62
// Step 4: Notify customer
63
ctx.execute_task(
64
send_refund_notification, (request.customer_id.clone(), request.amount)
65
).await?;
66
67
Ok(RefundResult {
68
refund_id,
69
status: "completed".to_string(),
70
amount_refunded: request.amount,
71
})
72
}

Design notes

  • Idempotency, same two layers as the charge. A worker can die inside process_gateway_refund after the gateway accepted it — pass an idempotency key derived from the refund request so the retry gets the original refund back instead of issuing a second one. The mechanics are identical to the charge-side diagram.
  • Validate partial refunds against what's left. amount supports partial refunds, and one charge may see several. process_gateway_refund should check the remaining refundable balance so two support agents processing the same request can't over-refund — the gateway's per-request idempotency key handles duplicates, the balance check handles genuinely distinct requests.
  • Keep the reason in the request. request.reason flows into the workflow's journal and your audit trail — refund analytics and chargeback disputes both want to know why, and the field costs nothing.
  • Decide what a failed notification means. As written, a permanently failing email fails the whole workflow after the money and books are already consistent. If that's not what you want, make the last step best-effort — the same policy call as the confirmation email in payment processing.

Next Steps