Record payment for subscription

​

Overview

​

Key Concepts

• Collection Method: Determines when payments are collected (charge_automatically or send_invoice)
• Payment Behavior: Defines how the system responds to payment failures
• Payment Methods: Card payments and wallet/credits with intelligent splitting
• Flow Types: Different contexts like subscription creation, renewals, manual payments
• Partial Payments: Smart fallback to wallet payments when card payments fail

​

Why Payment Behaviors and Collection Methods Matter

​

Business Model Alignment

• SaaS Products: Use charge_automatically + allow_incomplete for graceful failure handling
• Enterprise: Use send_invoice + default_active for manual billing cycles
• Freemium: Use charge_automatically + default_active for service-first approach
• Premium Services: Use charge_automatically + error_if_incomplete for strict payment requirements

​

Valid Payment Configurations

​

Invalid Combinations

• When no collection method is provided, the default is charge_automatically.
• When no payment behavior is provided, the default is default_active.

​

Partial Payment Logic

​

Overview

​

Decision Matrix

​

Rules Summary

• Subscription Creation + Default Active: Always allow partial wallet payment
• Other Subscription Creation: No partial payment (affects activation)
• All Other Flows: Always allow partial payment (better than failure)

​

Wallet Categorization

1. ALL Wallets: Can pay any price type (USAGE + FIXED)
2. USAGE Wallets: Can only pay usage-based charges
3. FIXED Wallets: Can only pay fixed charges
4. USAGE+FIXED Wallets: Treated as ALL wallets

​

Wallet Selection Algorithm

​

Payment Processing Order

1. USAGE Wallets First: Pay usage-based charges
2. FIXED Wallets Second: Pay fixed charges
3. ALL Wallets Last: Pay remaining amounts
4. Balance Sorting: Highest balance wallets used first

​

Endpoint: POST /v1/subscriptions

{
  "customer_id": "cust_123",
  "plan_id": "plan_456",
  "collection_method": "charge_automatically",
  "payment_behavior": "allow_incomplete",
  "gateway_payment_method_id": "pm_789"
}

• collection_method: "charge_automatically" | "send_invoice" (default: "charge_automatically")
• payment_behavior: "allow_incomplete" | "error_if_incomplete" | "default_active" | "default_incomplete" (default: "default_active")
• gateway_payment_method_id (optional): Override default payment method

​

Payment Flow Architecture

​

Card-First Strategy

1. Calculate Split: Determine what wallets can pay based on price type restrictions
2. Card First: Attempt card payment for the full eligible amount
3. Evaluate Result: Check if card payment succeeded or failed
4. Partial Decision: Use behavior + flow type to decide on wallet fallback
5. Wallet Payment: Process available wallet payments if allowed
6. Final Status: Determine overall payment success and subscription status

​

Payment Flow Types

​

1. Subscription Creation (InvoiceFlowSubscriptionCreation)

• Behavior: Applies full payment behavior logic
• Status Updates: Subscription status depends on payment result and behavior
• Partial Payments: Only allowed for default_active behavior

​

2. Renewal (InvoiceFlowRenewal)

• Behavior: Non-blocking payment processing
• Status Updates: Subscription continues regardless of payment result
• Partial Payments: Always allowed (partial payment better than none)

​

3. Manual Payment (InvoiceFlowManual)

• Behavior: Uses card-first logic with wallet fallback
• Status Updates: Activates subscription only on full payment success
• Partial Payments: Always allowed

​

4. Cancellation (InvoiceFlowCancel)

• Behavior: Processes final charges/credits
• Status Updates: No subscription status changes
• Partial Payments: Always allowed

​

Payment Methods

​

1. Card Payments (CARD)

• Processing: Immediate via Stripe integration
• Requirements: Customer must exist in Stripe with valid payment method
• Gateway Support: Can specify gateway_payment_method_id for subscription-specific cards
• Fallback: Wallet payment attempted if card fails (based on partial payment rules)

​

2. Credits/Wallet Payments (CREDITS)

• Processing: Instant, no external dependencies
• Restrictions: Wallets can be limited to USAGE, FIXED, or ALL price types
• Multi-Wallet: Supports multiple wallets per customer with intelligent selection
• Priority: Promotional wallets used before paid wallets

​

3. Offline Payments (OFFLINE)

• Processing: Manual reconciliation required
• Use Cases: Wire transfers, checks, cash payments
• Status: Immediate success upon manual confirmation

​

4. Payment Link (PAYMENT_LINK)

• Processing: Redirects to external payment page
• Features: Supports 3D Secure, multiple payment methods
• Integration: Webhook-based status updates

​

API Reference

​

Create Subscription with Payment Configuration

{
  "customer_id": "cust_123",
  "plan_id": "plan_456",
  "collection_method": "send_invoice",
  "payment_behavior": "default_active",
  "gateway_payment_method_id": "pm_789"
}

• collection_method: "charge_automatically" | "send_invoice"
• payment_behavior: "allow_incomplete" | "error_if_incomplete" | "default_active" | "default_incomplete"
• gateway_payment_method_id (optional): Override default payment method

​

Payment Method Strategy

• Primary: Configure card payments for automatic billing
• Fallback: Set up wallet payments for partial payment scenarios
• Enterprise: Enable offline payments for wire transfers
• Customer Choice: Offer payment links for flexible payment options

​

Troubleshooting

​

Common Issues

1. Payment Declined: Verify customer’s payment method and billing details
2. Wallet Restrictions: Check wallet allowed_price_types match invoice charges
3. Subscription Not Activating: Verify payment behavior allows activation on failure
4. Partial Payments: Check flow type and behavior combination in decision matrix

• Create Subscription API
• Attempt Payment API