Blocklist

The blocklist marks users whose ACH debit returned with an invalidate-bank code. A BLOCKED user stays blocked until a NOTBLOCKED record is written for them. Which codes block is decided by the return-code engine; this page covers the records and the write paths.

Record

Blocklist items live in the site-payments single table (schema). Each write stores two items: the CURRENT item, overwritten every time and read by GET /{user_id}/payments/blocklists, and a DATE#<timestamp> history item read by GET /{user_id}/payments/blocklists/history.

status event_type trigger_id

BLOCKED

USER_BLOCKED

Confirmation ID of the returned payment; the caller’s trigger_id on a manual add

NOTBLOCKED

USER_NOTBLOCKED

Plaid account_id from the unblock message; the caller’s value on a manual remove

Source: pkg/dynamo/blocklist/blocklist.go, pkg/blocklist/legacy_blocklister.go, pkg/api/blocklist.go

Block

  1. A returned debit is published to Kinesis as SUBSCRIPTION_RETURNED or FLOAT_DEBIT_RETURNED (Events).

  2. site-payments-blocklist-handler maps the event to an engine target: return_code, return_info, payment_method (defaulting to ach), source_id as the failed bank account, confirmation_id as the trigger.

  3. The engine resolves the code. An invalidate-bank code removes the bank account record and writes BLOCKED — ACH dispatch. Any other code writes nothing here.

POST /{user_id}/payments/blocklist writes BLOCKED directly with the caller-supplied trigger_id.

Unblock

  1. A message {"user_id": …​, "account_id": …​} arrives on SQS site-payments-blocklist-remove.

  2. site-payments-blocklist-remover writes NOTBLOCKED with trigger_id = account_id.

No code in this repository or the sibling service repositories sends to that queue. DELETE /{user_id}/payments/blocklist writes NOTBLOCKED directly.

Source: pkg/blocklist/unblocker.go, pkg/blocklist/blocklisthandler.go