Payments Module
Quick Answer
The payments module lives in src/core/payments. It provides payment method APIs, saved payment methods, card UI, address capture, payment request helpers, and Stripe payment sheet helpers used by commerce checkout flows.
This module is not a payment backend. You still need secure backend endpoints for Stripe, PayPal, and any payment provider that requires secrets.
Source Map
src/core/payments
|-- api
|-- component/IMAddAddressModal
|-- redux/checkout.js
|-- ui/Card/IMCardScreen.js
|-- usePaymentRequest.js
|-- usePaymentSheetManager.js
`-- index.js
Important pieces:
| File or export | Purpose |
|---|---|
usePaymentSheetManager | Prepares Stripe Payment Sheet and native payment options through backend-provided keys. |
usePaymentRequest | Payment request helper for checkout flows. |
IMCardScreen | Saved card/payment method UI. |
IMAddAddressModal | Address capture UI for checkout. |
redux/checkout.js | Selected payment method and checkout state. |
api/firebase/paymentMethods.js | Firebase-backed saved payment methods. |
Payment Provider Boundary
Keep this boundary clear:
| Runs in app | Runs on backend |
|---|---|
| payment method selection | provider secret key usage |
| card/payment sheet presentation | customer creation |
| Apple Pay or Google Pay sheet | ephemeral key creation |
| receives client secret | payment intent creation |
| order confirmation UI | transaction validation and order finalization |
Do not put Stripe secret keys, PayPal secrets, Braintree keys, or other payment secrets in React Native source.
Stripe Integration
For Stripe-backed apps, the app expects backend endpoints that return Payment Sheet keys and client secrets. Configure those endpoints through app config and verify:
- publishable key is public and app-safe;
- secret key stays on backend;
- backend validates cart amount and currency;
- Apple Pay/Google Pay merchant settings are correct;
- order is persisted only after payment succeeds.
Saved Payment Methods
Saved payment methods depend on the app's backend strategy. Firebase-backed apps use src/core/payments/api/firebase/paymentMethods.js.
Before release:
- verify rules only allow users to read/write their own payment method metadata;
- avoid storing raw card data;
- store only provider-safe references and display metadata;
- delete payment methods through provider APIs when required.
Verification Checklist
Test:
- card payment setup;
- card payment success;
- card payment failure;
- Apple Pay if enabled;
- Google Pay if enabled;
- PayPal if enabled;
- cash on delivery if enabled;
- duplicate tap/order submission prevention;
- order persistence after payment success;
- payment failure does not persist a paid order.
Troubleshooting
| Problem | Fix |
|---|---|
| Payment Sheet does not open | Check backend response fields, Stripe publishable key, and native Stripe setup. |
| Apple Pay button is hidden | Verify merchant ID, device support, country/currency, and Stripe Apple Pay setup. |
| Payment succeeds but order is missing | Check order finalization after provider confirmation. |
| Saved cards show for the wrong user | Tighten Firebase rules and query payment methods by authenticated user ID. |
| Checkout total differs from backend amount | Calculate the payable amount server-side and reject tampered client totals. |