Payment Gateways (Stripe & Paystack)
Relevant source files
The following files were used as context for generating this wiki page:
The BankChase application utilizes a dual-gateway architecture to facilitate diverse financial transactions. Stripe is primarily leveraged for P2P (Peer-to-Peer) payments and international USD transactions, while Paystack serves as the core infrastructure for Nigerian Naira (NGN) operations, including virtual account management and bank transfers.
This hybrid integration allows the system to support dedicated virtual NUBAN accounts for deposits, real-time transfers to external bank accounts, and internal wallet-to-wallet payments. The gateways are supported by a background infrastructure involving webhooks for asynchronous event processing, such as deposit confirmations and transfer failure refunds.
Paystack Integration Architecture
Paystack integration focuses on the Nigerian financial ecosystem, providing specialized services for NGN-denominated transactions.
Virtual Account Management
The system assigns dedicated virtual accounts (NUBAN) to users, allowing them to fund their internal wallets via standard bank transfers. This involves a two-step process: registering the user as a customer on Paystack and subsequently assigning a dedicated virtual account.
Bank Transfer Logic
Bank transfers to external Nigerian accounts follow a multi-stage verification and execution flow. The system resolves the recipient's account details before creating a transfer recipient and initiating the final movement of funds.
Stripe & P2P Payments
Stripe integration is utilized for P2P payments and credit card processing, primarily serving USD-based transactions or simplified wallet-to-wallet flows.
P2P Workflow
The P2P system supports immediate wallet-to-wallet credits when both parties are internal users. For external recipients, it leverages Stripe's Payment Intent system.
| Feature | Description |
|---|---|
| Payment Intents | Securely processes credit card transactions through Stripe. |
| Wallet-to-Wallet | Immediate internal credit if recipient email is detected in the system. |
| Dual Notifications | Confirmation emails sent to both sender and recipient via SendGrid/Mailgun. |
Sources: QUICKSTART.md:73-82, MONEY_TRANSFER_API_DOCS.md:186-210, lib/payment-service.ts
Webhook Infrastructure
Both gateways rely on asynchronous notifications to maintain ledger accuracy and handle transaction finality.
Supported Webhook Events
- charge.success: Triggered when a deposit is received via a virtual account. The system credits the user's
wallet_balancein theprofilestable. - transfer.success: Confirms that a bank transfer has reached the destination.
- transfer.failed: Initiates an automatic refund to the sender's internal wallet and records the failure reason.
Sources: MONEY_TRANSFER_API_DOCS.md:321-342, PAYMENTS_INTEGRATION_GUIDE.md:115-125
Configuration and Environment
Gateway behavior is controlled through environment variables, allowing for switching between sandbox and production modes.
| Variable | Description | Source |
|---|---|---|
PAYSTACK_SECRET_KEY | Secret key for Paystack API calls and HMAC verification. | MONEY_TRANSFER_START_HERE.md:23-26 |
STRIPE_SECRET_KEY | Secret key for Stripe Payment Intent creation. | QUICKSTART.md:17-21 |
EMAIL_SERVICE | Defines provider for payment notifications (sendgrid/mailgun). | QUICKSTART.md:22-26 |
MAX_TRANSFER_AMOUNT | Limit enforced by API (Default: ₦10,000,000). | MONEY_TRANSFER_QUICK_REFERENCE.md:162-167 |
Conclusion
The integration of Stripe and Paystack provides BankChase with a robust multi-currency payment infrastructure. Paystack manages the complexities of the Nigerian banking system through virtual accounts and NUBAN transfers, while Stripe handles P2P and international payment flows. This architecture, secured by HMAC-verified webhooks and ACID-compliant database operations, ensures reliable money movement across the platform.