Merchant Gateway Architecture & API Design

[kelly-musk]

📋 Description

This issue involves designing the "Entry Point" for commercial adoption. The Merchant Gateway is a specialized layer of the Aframp platform that allows businesses to generate invoices, process payments in cNGN, and manage their digital storefronts. Unlike a standard peer-to-peer wallet, the Merchant Gateway must handle high-concurrency transaction volumes, provide instant "Payment Confirmed" webhooks, and support complex metadata (like Order IDs and SKU details) required for business accounting.

🎯 Objective

Create a robust, developer-friendly infrastructure that allows any business to integrate cNGN payments into their existing checkout flow with minimal technical overhead.

🛠️ Technical Requirements

• Merchant Scoped API Keys:
  • Implement a secure "Public/Private Key" pair system for merchants to authenticate their backend servers.
  • Support for "Restricted Scopes" (e.g., a key that can only "Read" transactions but not "Refund").
• Unified Checkout Object:
  • Define the Invoice schema: amount_cngn, callback_url, expiry_time (e.g., 15 minutes), and merchant_reference.
• High-Speed Webhook Engine:
  • A reliable notification service that sends a POST request to the merchant's server the moment the Stellar Network confirms a payment.
  • Implement "Exponential Backoff" retries for failed webhook deliveries.
• Idempotency Logic:
  • Ensure that a single "Order ID" cannot be paid twice, preventing duplicate charges for the same customer purchase.

✅ Acceptance Criteria

• Merchants can generate a unique payment_intent_id via a REST API.
• The system monitors the blockchain and transitions the invoice state from PENDING to PAID in under 5 seconds.
• Webhooks are cryptographically signed to allow merchants to verify they originated from Aframp.
• The architecture supports "Meta-Transactions" where the merchant can choose to pay the network gas fees (Stellar XLM) for their customers.

🔴 Priority: Critical

Labels: Merchant-Tools, API-Design, Ecosystem

---

[Diaroke]

@Diaroke has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I would like to work on this issues because I can handle it correctly. Kindly reassign.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Diaroke to this issue.

[drips-wave]

Congratulations, @Diaroke! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @Diaroke: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊