Developer Docs

Ngwenya supports native USDC cryptocurrency payments across the platform. To minimize operational risk, security surface area, and regulatory overhead, Phase 1 of the Stablecoin Commerce initiative relies entirely on Stripe-managed crypto rails.

By utilizing Stripe to process USDC, the platform supports stablecoin payments while retaining the exact same security posture and programmatic interfaces used for fiat card processing.

Architecture & Flow

The stablecoin payment flow utilizes the existing Payments Subgraph to process intents and reconcile blockchain states.

1. Intent Creation

When a Visitor/Buyer opts to pay via crypto on the frontend, the client calls the createCryptoPaymentIntent mutation. This bypasses the default card configuration and explicitly requests a cryptocurrency checkout session.

mutation {
  createCryptoPaymentIntent(input: {
    amount: 1500,
    currencyCode: "USD",
    paymentProvider: "stripe_crypto"
  }) {
    paymentIntentId
    clientSecret
  }
}

The Payments subgraph uses the StripeHandler to configure the Stripe intent with payment_method_types: ['crypto'].

2. Frontend Execution

The returned clientSecret is passed to Stripe Elements on the frontend. Stripe securely hosts the crypto UI, presenting the Buyer with a QR code or connection prompt for their wallet. The Buyer signs and broadcasts the transaction to the network (e.g., Ethereum, Solana, Polygon, or Base).

3. Webhook Reconciliation

Because blockchain transactions take time to confirm, crypto payments are inherently asynchronous.

Once Stripe detects sufficient block confirmations, it triggers a standard payment_intent.succeeded webhook to the platform.

The WebhookService automatically detects the 'crypto' payment method type in the payload and extracts critical metadata, which is then mapped to the Transaction entity:

  • cryptoNetwork: The blockchain used (e.g., polygon, solana)
  • cryptoTxHash: The on-chain transaction hash
  • walletAddress: The payer's wallet address (if available)

The transaction state is then transitioned to CAPTURED, and a payment_captured TCP event is emitted, allowing the Murchases Subgraph to finalize the Murchase and notify the Malet Owner.

Data Model Extensions

The Transaction entity includes nullable fields specifically for crypto processing:

export enum CryptoNetwork {
  ETHEREUM = 'ethereum',
  BASE = 'base',
  POLYGON = 'polygon',
  SOLANA = 'solana',
}

// Inside Transaction Entity
cryptoNetwork?: CryptoNetwork;
cryptoTxHash?: string;
walletAddress?: string;

Security & Compliance

No Custody Risk

Because Ngwenya uses Stripe to settle stablecoins, the platform never holds private keys and never interacts directly with smart contracts. Stripe receives the USDC, handles all on-chain monitoring, and settles the funds to the platform's bank account in fiat (USD).

Irreversibility

Unlike credit cards, blockchain transactions are mathematically irreversible. There are no traditional chargebacks on crypto payments. In the event of a dispute or required refund, Malet Owners must initiate a standard refund via the platform's Order Management interface. Stripe will execute the refund by returning fiat-equivalent value (or crypto, depending on merchant configuration) back to the original wallet.

CAUTION

ToS Considerations: The platform's Terms of Service stipulate that blockchain transactions are final. Dispute resolution for crypto payments is handled internally via platform mediation rather than through network chargebacks.