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

Environment

Table Name

Region

test

test-loc-service

us-west-2

prod

prod-loc-service

us-east-2

Fields

Field Type Description

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)

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

Status	Description
`PENDING`	Payment created, not yet submitted to the payment service
`ACHSENT`	ACH payment submitted to the payment service, awaiting settlement confirmation via webhook
`COMPLETED`	Payment successfully processed and applied to installments
`RETRY`	Payment failed but is eligible for retry; re-queued for the next collection run
`SKIPPED`	Payment processing was skipped without submitting to the payment service. Occurs when: the loan is not in an open status, the loan balance is already zero, the payment amount is invalid or does not match the amount due, the target installment is missing, or the target installment balance is already zero
`FAILED`	Payment permanently failed; no further retries will be attempted
`CHARGED_BACK`	Payment was charged back by the user’s bank (received via webhook from payment service)
`RETURNED`	ACH payment was returned by the bank (reserved; set externally via payment service events)
`REFUNDED`	Payment was refunded (received via webhook from payment service)

PENDING

Payment created, not yet submitted to the payment service

ACHSENT

ACH payment submitted to the payment service, awaiting settlement confirmation via webhook

COMPLETED

Payment successfully processed and applied to installments

RETRY

Payment failed but is eligible for retry; re-queued for the next collection run

SKIPPED

Payment processing was skipped without submitting to the payment service. Occurs when: the loan is not in an open status, the loan balance is already zero, the payment amount is invalid or does not match the amount due, the target installment is missing, or the target installment balance is already zero

FAILED

Payment permanently failed; no further retries will be attempted

CHARGED_BACK

Payment was charged back by the user’s bank (received via webhook from payment service)

RETURNED

ACH payment was returned by the bank (reserved; set externally via payment service events)

REFUNDED

Payment was refunded (received via webhook from payment service)

Process Values

Process Description

Process	Description
`MANUAL`	User-initiated payment through the app
`AUTO`	Automatically initiated by autopay
`RETRY`	Retry of a previously failed payment

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

Key	Pattern
PK	`USER#<user_id>`
SK	`LOAN#<loan_id>#PAYMENT#<payment_id>`

USER#<user_id>

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

Key	Pattern
GSI1PK	`USER#<user_id>`
GSI1SK	`LOAN#<loan_id>#STATUS#<payment_status>#PAYMENT#<payment_id>`

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

Key	Pattern
GSI2PK	`PAYMENT`
GSI2SK	`STATUS#<payment_status>#PAYMENT#<payment_id>`

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

Key	Pattern
GSI3PK	`USER#<user_id>`
GSI3SK	`CONFIRMATION#<confirmation_id>`

GSI3PK

USER#<user_id>

GSI3SK

CONFIRMATION#<confirmation_id>

Query Patterns

Query Index Key Condition Sort Key Condition

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>`

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)               │
                    └──┬──────────────────┬─────────────┬───────────┘
                       │                  │             │
              ACH      │          Pinless │             │ Validation failure
             submit    │           submit │             │ (loan not open,
             success   │          success │             │  zero balance,
                       │                  │             │  invalid amount,
                       │                  │             │  missing/paid target)
                       ▼                  ▼             ▼
              ┌─────────────┐     ┌─────────────┐  ┌──────────┐
              │   ACHSENT   │     │  COMPLETED  │  │ SKIPPED  │
              │ (Submitted  │     │  (Success)  │  └──────────┘
              │  to payment │     └──────┬──────┘
              │   service)  │            │
              └──────┬──────┘            │
                     │                   │ webhook: failed + AUTO ──────────►┐
                     │                   │ webhook: failed + non-AUTO ───────►(FAILED, below)
                     │                   │ webhook: refunded ─────────────────►(REFUNDED, below)
                     │                   │
                     │
                     │ webhook: completed ──────────────────────► COMPLETED
                     │
                     │ webhook: failed + AUTO process ───────────┐
                     │                                           ▼
                     │                                   ┌──────────────┐
                     │                                   │    RETRY     │◄── Submit error (AUTO/RETRY)
                     │                                   │  (Retrying)  │◄── Balance check failed
                     │                                   └──────┬───────┘
                     │                                          │
                     │                                          │ Max retries reached /
                     │                                          │ stale (> 60 days) /
                     │                                          │ competing payment succeeded /
                     │                                          │ loan closed
                     │                                          ▼
                     │ webhook: failed + non-AUTO ────────► ┌──────────┐
                     │                                      │  FAILED  │◄── Submit error (MANUAL)
                     └─────────────────────────────────────►└──────────┘
                     │
                     │ webhook: charged_back ────────────► CHARGED_BACK
                     │
                     └── webhook: refunded ──────────────► REFUNDED

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

Loans - Parent loan for this payment
Installments - Installments this payment applies to
Payment Logs - Audit trail for this payment