Events

Event contracts for the Payments Service: what it publishes to the site-payments Kinesis stream and what it consumes. Flow behavior lives on the domain pages linked from each row.

Published

site-payments-kinesis-feeder consumes the DynamoDB stream of the payments table (schema). For every stream record it:

  1. Unmarshals the new image as a payment; a record with an empty event_type is skipped.

  2. Builds an fmsdk.Event — id = confirmation_id, type = event_type, source = PaymentService, version = V2, data = the payment in the GET /payments/{confirmation_id} shape.

  3. Puts the record on site-payments with the confirmation ID as the partition key.

Payments are written at submission with an empty event_type; the later write that sets event_type on a status change is the one published. The exception is a safe-retry recovery of a pinless charge for an ACH request, written with FLOAT_DEBIT_COMPLETED or SUBSCRIPTION_COMPLETED. Prenotes are written with PRENOTE_SUBMITTED and publish at submission. PATCH /payments/{confirmation_id} clears event_type on its write, and that update is not republished.

Source: pkg/feeder/feeder.go

Event Types

Consumers are the sibling services whose Kinesis event-source filters name the type (their deploy/*.tf, checked in this pass).

event_type Written by Consumers

SUBSCRIPTION_COMPLETED

check-ach-worker, api (safe retry)

subscription-service

SUBSCRIPTION_RETURNED

jpm-webhook-processor, usio-syncer

blocklist-handler, subscription-service

SUBSCRIPTION_CHARGED_BACK

usio-syncer

subscription-service, user-service

SUBSCRIPTION_REFUNDED

api (POST /refunds)

subscription-service

FLOAT_DEBIT_COMPLETED

check-ach-worker, api (safe retry)

float-service

FLOAT_DEBIT_COMPLETED_PLAID

check-ach-worker (Plaid clearing)

float-service

FLOAT_DEBIT_RETURNED

usio-syncer

blocklist-handler, float-service

FLOAT_DEBIT_CHARGED_BACK

usio-syncer

float-service, user-service

FLOAT_CREDIT_COMPLETED

check-ach-worker

float-service

FLOAT_CREDIT_RETURNED

usio-syncer

float-service

FLOAT_REFUNDED

api (POST /refunds)

—

LOAN_DEBIT_COMPLETED

check-ach-worker

loc-service

LOAN_DEBIT_RETURNED

usio-syncer

loc-service

LOAN_DEBIT_CHARGED_BACK

usio-syncer

loc-service

LOAN_CREDIT_COMPLETED

check-ach-worker

loc-service

LOAN_CREDIT_RETURNED

usio-syncer

loc-service

LOAN_PAYMENT_REFUNDED

api (POST /refunds)

loc-service

PRENOTE_SUBMITTED

api (prenote endpoints)

—

PRENOTE_COMPLETED

check-ach-worker

—

PRENOTE_RETURNED

jpm-webhook-processor, usio-syncer

—

UNKNOWN_EVENT_TYPE

usio-syncer, when the payment class cannot be determined

—

Source: pkg/dynamo/payments.go; PRENOTE_SUBMITTED in pkg/api/prenotes.go; refund types in pkg/api/refunds.go; safe-retry types in pkg/api/usio_safe_retry.go

Consumed

Input Source Transport Handled by

Returned subscription and float debits

This service (kinesis-feeder)

Kinesis site-payments, filtered to SUBSCRIPTION_RETURNED, FLOAT_DEBIT_RETURNED

blocklist-handler — ACH dispatch

JPM payment status callbacks

JPM

HTTPS POST /v1/jpm on jpm.webhooks.floatme.io

jpm-webhook-handler — JPM Webhooks

Prenote requests

pkg/prenotes/batch-script (manual CSV run)

SQS site-payments-prenotes

prenoter — Prenotes

Unblock requests {"user_id", "account_id"}

No producer in this repository or the sibling service repositories

SQS site-payments-blocklist-remove

blocklist-remover — Unblock flow

Debit card repair requests

scripts/debit-fixer (manual CSV run)

SQS site-payments-debit-fixer

debit-card-fixer — Debit Fixer

Internal work queues (check-ach, usio-sync, usio-refresh, jpm-webhooks) are in Infrastructure.