Skip to main content
Version: v1

Session Mode Access Configuration

Overview​

The session mode access configuration defines access control rules for different operational modes. It specifies which HTTP methods and URL patterns are permitted for each access mode, creating a robust security framework that enforces proper API access permissions.

Key Benefits
  • Enhanced Security: Restricts operations based on session mode
  • Controlled Access: Prevents unauthorized endpoint access
  • Method Restrictions: Limits HTTP methods based on operation context
  • Fine-Grained Control: Maintains separate permission sets for wallet vs. payment operations
Purpose
  • Establishes permission boundaries for different operational modes
  • Controls which API endpoints can be accessed based on the active mode
  • Enforces HTTP method restrictions for specific URL patterns
  • Creates a layered security model for wallet and payment operations
  • Prevents mode-mixing attacks (e.g., using payment session for wallet operations)
Access Modes

The wallet authentication service defines several operational modes, each providing access to a specific set of operations:

ModeDescriptionTypical Use Case
PAYMENT_METHOD_ENTRYFor entering/registering new payment methodsAdding a new credit card to the system
PAYMENTFor making payments using existing methodsProcessing a one-time payment
PAYMENT_WITH_WALLETCombined mode for payment and wallet operationsCheckout with option to save payment method
WALLETFor wallet management operationsCustomer managing their saved payment methods
PAYMENT_METHOD_SELECTFor selecting from existing payment methodsChoosing from previously saved payment options
URL Pattern Specifications

URL patterns use regular expressions with predefined patterns:

  • $\{uuid-pattern\}: Matches standard UUID format [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
  • $\{bank-routing-pattern\}: Matches numeric bank routing numbers [0-9]+$

Pattern Validation​

All URL patterns undergo validation at application startup to ensure they follow proper regex syntax. Invalid patterns will cause application startup failure with detailed error messages.

Mode-Specific Permissions​

Mode Access Matrix

The following matrix shows which endpoints are accessible in each session mode:

EndpointPAYMENT_ METHOD_ENTRYPAYMENTPAYMENT_ WITH_WALLETWALLETPAYMENT_ METHOD_SELECT
GET /customers/{uuid}/payment-methods✅✅✅✅✅
GET /customers/{uuid}/setup-payment-methods/{uuid}✅❌✅✅✅
GET /banks/routing/routing-number✅❌✅✅✅
GET /payments/{uuid}❌✅✅❌❌
GET /customers/{uuid}/payment-methods/{uuid}❌❌✅✅✅
GET /payment-methods/{uuid}❌❌✅✅✅
POST /customers/{uuid}/setup-payment-methods✅❌✅✅✅
POST /payments❌✅✅❌❌
PATCH /customers/{uuid}/payment-methods/{uuid}❌❌✅✅✅
PATCH /payment-methods/{uuid}❌❌✅✅✅
PATCH /payments/{uuid}/confirm❌✅✅❌❌
DELETE /customers/{uuid}/payment-methods/{uuid}❌❌✅✅✅
DELETE /payment-methods/{uuid}❌❌✅✅✅

✅ = Allowed, ❌ = Not Allowed

Security Considerations
  • Each mode provides least-privilege access to required endpoints
  • URL patterns use precise regex patterns to prevent path traversal attacks
  • The configuration enforces HTTP method restrictions to prevent unauthorized operations
  • Layered access model ensures operational separation between payment and wallet functions
Error Responses

When a request is made that violates the mode-level restrictions, the following error response is returned:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "403 FORBIDDEN. RequestId: be5c3b7d-6f0d-429b-9f19-89f1bff48032"
}

Best Practices​

  1. Use Correct Session Mode: Choose the appropriate session mode based on your operational needs
  2. Handle Permission Errors: Be prepared to handle 403 responses when mode restrictions apply
  3. Avoid Mode Mixing: Don't attempt to use sessions for operations they weren't designed for