Design Decision Note

[metalalive]

Context & Use Cases

• Charge management
  • buyers can create charges on checkout and track charge progress to see whether the purchases are completed
  • this application synchronizes order details between the order-processing application to ensure accurate charge validation
  • merchants can capture their funds from a successful pay-in
  • supports partial charges for buyers, allow multiple payments per order
  • handles multi-currency transaction, estimates conversion for both buyers and merchants
• Merchant Onboarding
  • merchants can configure (at least one of) supported third-party payment processors, before they can process checkouts and refunds.
• Refund Management
  • this application synchronizes return requests from the order-processing system for refund.
  • return requests are processed with respect to order details, charge records, and refund eligibility.
  • supports partial refunds, allowing merchants to refund only a portion of a charge
  • tracks multiple refund rounds and ensures accurate calculations of refunded and remaining amounts.

---

Charge management

How does the application guarantee idempotency in operations such as charge creation, payout, and refunds to prevent duplicate transactions ?

Continue to the question above, how does the charge identity (ChargeToken) work? what role does it play in this context ?

Continue to the question above, what happens if the token decoding fails due to data corruption?

How does this application safely transition charge state (e.g., from Initialized to ProcessorCompleted to OrderAppSynced) in a concurrent environment, and what safeguards prevent race conditions ?

How does this application handle failures in the RPC calls such as order detail synchronization ?

What strategies do you employ for error propagation and recovery when external services (e.g., 3rd-party processor Stripe) fail ?

• how errors are logged or retried, TODO

How are edge cases handled, such as handling zero amounts or invalid currencies ?

What other potential issues might arise from multiple charges per order (partial charge support) ?

TODO

Multi-Currency Calculations:

Where and How are currency conversion and precision handled ?

Continue to the question above, what scale is used for decimal places, and how is rounding managed to avoid financial inaccuracies?

What measures are in place to avoid rounding or overflow errors?

Merchant Onboarding

Refund Management

How does this application handle failures in the RPC calls such as return request synchronization ?

Continue to the question above, What checks are in place to prevent over-refunding, and how are partial refunds tracked across multiple rounds ?

How is idempotency planned for refunds to prevent duplicate processing ?

Third-Party Integration

How does the adapter for 3rd-party processor abstract the integration with external payment processors (e.g., Stripe)

continue to the question above, and what challenges might you face when extending support to additional processors?

TODO, currently not support extra processors yet

How are API keys for third-party processors secured and managed?

Architecture Considerations

How does the application handle failures in critical operations (e.g., timeouts from the payment processor or datastore errors), and is there a rollback or compensating transaction mechanism in place ?

What were the trade-offs in choosing RPC-based communication for order and refund synchronization compared to other messaging protocols?

What design decisions were made to mitigate potential security risks (e.g., data breaches or fraud) inherent in payment processing systems?

How could this application be scaled with many merchants and charges, what are potential bottlenecks, like slow RPC calls, and how caching or optimizations are implemented.

TODO, will be updated after profiling

How are time zones handled in financial transactions ?

Observability

How do you plan to monitor critical operations (such as charge capture and refund processing) for traceability and auditability?

What metrics or logs are you capturing to detect and respond to anomalies or failures in this application ?