Payment Intent

internal/api/v1/billing/services/payment-intent.service.js provides two capabilities: reloading OneBalance wallets via Stripe Payment Intents and mirroring the marketplace checkout experience for accounts that require Payment Intent confirmation. It reuses helper utilities from the Charge service to maintain consistent pricing, subscription creation, and queue behaviour.

Primary Controller: payment-intent.controller.js

🗄️ Collections & Models

• shared/models/onebalance.js – Increments balances after successful reloads.
• shared/models/onebalance-usage_logs.js – Records credit/debit events for audit.
• shared/models/queues.js – Queues post-checkout jobs (subaccount-charge).
• shared/models/store-price.js / store-cart.js – Resolves pricing metadata and cache for previews.
• shared/models/account.js – Validates listing eligibility, resolves parent relationships.
• shared/models/stripe-key.js – Fetches connected account token for Stripe client.

🔗 External Services

• Stripe Payment Intents API – Used for both balance reloads and checkout charges.
• Currency Utility (shared/utilities/currency) – Converts reload amounts into base currency before crediting OneBalance.
• Charge Helpers – phoneNumQuantity, additionalAction, createMainAccountSubscription, formatPrice.

🔄 Data Flow

flowchart TD
    UI[Billing UI] -->|POST /payment-intent| Controller
    Controller --> Service
    Service -->|Connected token| Stripe
    Service --> Onebalance[(OneBalance)]
    Service --> QueueManager
    Service --> StoreCart
    Stripe --> WebhookService

🧩 Functions

payment({ onebalance, amount, currency, payment_source, account })

Reloads OneBalance for the parent account.

1. Retrieves connected account Stripe key and customer ID.
2. Resolves payment source (explicit ID or default card).
3. Creates a Payment Intent for amount * 100 in the specified currency.
4. On success, converts the charged amount back to BASE_CURRENCY using CurrencyUtil.
5. Updates OneBalance balance and clears retry flags.
6. Inserts credit log entry indicating refill event.

Edge Cases

• Throws when Stripe keys missing or customer unlinked.
• Rejects when no default payment source exists.
• Surfaces Stripe connection timeouts via custom error helper.

checkout({ account, account_id, product_type, type, external_action, card, uid })

Imitates the Charge service marketplace checkout but always uses Payment Intents.

1. Resolves pricing metadata (including phone number tier handling).
2. For type="preview", upserts a cart item and returns formatPrice DTO.
3. For purchase:
   • Confirms Payment Intent with amount Math.ceil(cost).
   • Creates parent subscription via createMainAccountSubscription.
   • Invokes additionalAction to queue provisioning.
   • Deletes the temporary cart and enqueues subaccount-charge log entry.
4. Returns boolean success indicator (controller wraps response payload).

Guards & Validations

• Blocks duplicate listing purchases and unsupported add-ons (instasite, site).
• Requires Stripe customer linkage and funding source.
• Reuses OneBalance rebill configuration to compute internal costs.

🧪 Testing Notes

• Reference tests/customer.test.js for end-to-end checkout expectations (shared logic).
• When adding new product types, ensure both Charge and Payment Intent fixtures are aligned.

⚠️ Operational Considerations

• BASE_CURRENCY environment variable must be set for OneBalance balance adjustments.
• Controllers should catch PaymentIntent.status === 'requires_action' to prompt additional authentication.
• Preview and purchase flows rely on consistent cart cleanup to avoid stale items.

🔗 Related Docs

• Charge
• Customer
• Payment Link
• Billing Module Overview