Payments

Description

The Payment entity represents a payment transaction against a loan. Payments can be initiated automatically via autopay, manually by the user, or as retries of previously failed payments. Each payment tracks its lifecycle from creation through completion or failure.

Storage

Environment Table Name Region

test

test-loc-service

us-west-2

prod

prod-loc-service

us-east-2

Fields

Field Type Description

loc_user_id

String

User ID who owns the payment

loc_loan_id

String

Loan this payment applies to

loc_payment_id

String

Unique payment identifier (UUID)

loc_amount

Integer

Payment amount in cents

loc_status

String

Payment status (see Status Values below)

loc_payment_method

String

Payment method: ach or pinless

loc_process

String

How payment was initiated: MANUAL, AUTO, RETRY

loc_confirmation_id

String

Confirmation ID from payments service

loc_account_last_four

String

Last 4 digits of payment account

loc_intended_installment_id

String

Target installment for this payment

loc_payment_attempts

Integer

Number of payment attempts made

loc_applications

Array

List of installments this payment was applied to

loc_update_reason

String

Reason for last update (for audit logging)

loc_created_date

String

Creation timestamp (RFC3339)

loc_last_updated

String

Last update timestamp (RFC3339)

Status Values

Status Description

PENDING

Payment created, not yet submitted

ACHSENT

ACH payment submitted, awaiting settlement

COMPLETED

Payment successfully completed

RETRY

Payment failed, scheduled for retry

SKIPPED

Payment skipped (e.g., loan already paid)

FAILED

Payment permanently failed

CHARGED_BACK

Payment was charged back

RETURNED

ACH payment was returned

Process Values

Process Description

MANUAL

User-initiated payment through the app

AUTO

Automatically initiated by autopay

RETRY

Retry of a previously failed payment

Keys and Indexes

Primary Key

Key Pattern

PK

USER#<user_id>

SK

LOAN#<loan_id>#PAYMENT#<payment_id>

GSI1 - Payments by User and Loan Status

Used to list payments for a specific loan filtered by status.

Key Pattern

GSI1PK

USER#<user_id>

GSI1SK

LOAN#<loan_id>#STATUS#<payment_status>#PAYMENT#<payment_id>

GSI2 - All Payments by Status

Used by collection jobs to query payments across all users by status.

Key Pattern

GSI2PK

PAYMENT

GSI2SK

STATUS#<payment_status>#PAYMENT#<payment_id>

GSI3 - Payments by Confirmation ID

Used to look up a payment by its confirmation ID from the payments service.

Key Pattern

GSI3PK

USER#<user_id>

GSI3SK

CONFIRMATION#<confirmation_id>

Query Patterns

Query Index Key Condition Sort Key Condition

Get payment by loan and payment ID

Primary

PK = USER#<user_id>

SK = LOAN#<loan_id>#PAYMENT#<payment_id>

List all payments for a loan

Primary

PK = USER#<user_id>

SK begins_with LOAN#<loan_id>#PAYMENT

List payments for loan in status

GSI1

GSI1PK = USER#<user_id>

GSI1SK begins_with LOAN#<loan_id>#STATUS#<status>

List all payments in retry status

GSI2

GSI2PK = PAYMENT

GSI2SK begins_with STATUS#RETRY

Get payment by confirmation ID

GSI3

GSI3PK = USER#<user_id>

GSI3SK = CONFIRMATION#<confirmation_id>

Status Transitions

                    ┌──────────────────────┐
                    │       PENDING        │
                    │  (Payment created)   │
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │       ACHSENT        │
                    │  (Submitted to bank) │
                    └──────────┬───────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│    COMPLETED    │   │     RETRY       │   │    RETURNED     │
│  (Success)      │   │  (Will retry)   │   │  (ACH returned) │
└─────────────────┘   └────────┬────────┘   └─────────────────┘
                               │
                    ┌──────────▼───────────┐
                    │       FAILED         │
                    │  (Max retries)       │
                    └──────────────────────┘

Payment Applications

When a payment completes successfully, it is applied to installments. The loc_applications field tracks which installments received funds:

{
  "loc_applications": [
    {
      "payment_id": "abc-123",
      "installment_id": "inst-456",
      "amount": 5000,
      "payment_date": "2024-01-15T12:00:00Z"
    }
  ]
}

Related Entities