Skip to main content
Version: v2

Payment Lifecycle

Overview​

This document outlines the complete payment lifecycle in the Wallet Payment Service. It describes the various states a payment can transition through from initialization to completion, supporting both card and bank account payment methods.

Payment Methods​

The Wallet Payment Service supports the following payment methods:

  • Card Payments: Credit and debit card transactions
  • Bank Account Payments: ACH transfers

Payment Vendors​

The system integrates with multiple payment processing vendors:

  • STRIPE

Payment Lifecycle Stages​

1. Payment Creation​

The payment lifecycle begins with the creation of a payment through one of three entry points:

  • Guest Payment: One-time payment without saving payment details
  • User Payment: Payment with a logged-in user
  • Merchant-Initiated Payment: Payment triggered by a merchant

Initial States​

  • INITIATED: The payment has been created but processing has not yet started
  • PENDING: The payment request is being processed

2. Customer Creation/Validation​

Before processing the payment, the system validates or creates customer records:

States During Customer Handling​

  • PENDING_FOR_CUSTOMER_CREATION: The payment is waiting for customer record creation
  • FAILED: Customer creation failed, preventing payment from proceeding

3. Payment Method Processing​

The system processes the payment method based on whether it's saved, new, or a guest payment:

States During Payment Method Handling​

  • PENDING_FOR_PAYMENT_METHOD_CREATION: Waiting for payment method to be created/validated
  • PAYMENT_METHOD_FAILED: Payment method validation failed but can be retried
  • PROCESSING: Payment is being processed with the vendor
  • PROCESSING_DEDUP_CHECK: For pay-and-save flow, checking for duplicate payment methods
  • AUTH_REQUIRED: Additional authentication required from the customer

4. Payment Authorization​

For card payments, an authorization step may occur:

Authorization States​

  • AUTHORIZED: Payment has been authorized but not yet captured
  • ACCEPTED: Payment has been accepted by the system (specific to certain flows)

5. Payment Confirmation and Capture​

After authorization, payments can be confirmed and funds captured:

Confirmation States​

  • CONFIRMATION_INITIALIZED: Payment confirmation has been initiated
  • CAPTURE_INITIALIZED: Fund capture has been initiated
  • CANCEL_INITIALIZED: Payment cancellation has been initiated
  • CANCEL_FAILED: Payment cancellation attempt failed

6. Final Payment States​

Payments ultimately reach one of these terminal states:

Terminal States​

  • COMPLETED: Payment successfully processed and funds transferred
  • FAILED: Payment processing failed
  • CANCELED: Payment was canceled before completion

Payment Flow Types​

Standard Payment Flow​

  1. INITIATED → PROCESSING → COMPLETED/FAILED

Authorization and Capture Flow​

  1. INITIATED → PROCESSING → AUTHORIZED → CAPTURE_INITIALIZED → COMPLETED/FAILED

Customer Creation Flow​

  1. INITIATED → PENDING_FOR_CUSTOMER_CREATION → INITIATED → (standard flow continues)

Payment Method Creation Flow​

  1. INITIATED → PENDING_FOR_PAYMENT_METHOD_CREATION → INITIATED → (standard flow continues)

Pay and Save Flow​

  1. INITIATED → PROCESSING_DEDUP_CHECK → PROCESSING → COMPLETED/FAILED

Payment Cancellation Flow​

  1. Any state → CANCEL_INITIALIZED → CANCELED/CANCEL_FAILED

Error Handling​

The payment service handles various error conditions:

  1. Payment Method Errors: Issues with the payment instrument like expired cards, insufficient funds
  2. Customer Creation Errors: Problems creating or finding customer records
  3. Merchant Configuration Errors: Issues with merchant setup or allowed payment methods
  4. Vendor Errors: Issues from payment processing vendors
  5. Internal Errors: System errors within the payment service

Payment Retry Mechanism​

The system allows for retry of failed payments:

  • Tracks retry attempts via retryCount
  • Applies maximum retry logic via canRetry(maxRetry) check
  • Distinguishes between retryable failures (PAYMENT_METHOD_FAILED) and permanent failures (FAILED)

Payment Lifecycle Diagram​

This diagram summarizes the main payment state transitions, including customer and payment method creation, processing, authorization, capture, and cancellation flows.