Giao diện
payment / payment
Trang sinh tự động
Sinh từ ad83b0aea — chạy 820 migration lên PostgreSQL 17 rồi đọc pg_catalog. Mô tả bảng và cột lấy từ COMMENT ON. Không sửa tay: lần chạy docgen sau sẽ ghi đè.
13 bảng. Quay lại payment.
payment_intents
P3-01 / #479. Provider-agnostic payment attempt for one cash obligation (MOCK only, G-FIN). UNKNOWN is not terminal and blocks a second intent; SUCCEEDED needs a verified capture of the exact amount; NEEDS_REVIEW ends an attempt whose captured money could not be applied (Finance: payment.unapplied_captures).
public.payment_intents · 19 cột · 10 check · 1 unique · 5 index · 1 policy · 6 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
obligation_id | uuid | NOT NULL | FK → payment_obligations | |
request_id | text | NOT NULL | ||
provider | text | NOT NULL | ||
provider_mode | text | NOT NULL | ||
amount_vnd | bigint | NOT NULL | ||
currency | text | NOT NULL | ||
payload_hash | bytea | NOT NULL | ||
provider_session_ref | text | |||
result_code | text | |||
status | text | NOT NULL | ||
status_changed_at | timestamptz | NOT NULL | ||
change_source | text | NOT NULL | ||
change_source_id | text | NOT NULL | ||
correlation_id | correlation_ref | NOT NULL | ||
created_by | uuid | FK → accounts | ||
created_at | timestamptz | NOT NULL | ||
updated_at | timestamptz | NOT NULL | ||
version | integer | NOT NULL |
Khoá chính: id
Trỏ ra (2):
created_by→accounts·ON DELETE RESTRICTobligation_id→payment_obligations·ON DELETE RESTRICT
Được trỏ tới (9): cashbook_entries, payment_event_conflicts, payment_events, payment_hold_releases, payment_intent_leases, payment_intent_recovery_checks, payment_intent_sessions, payment_reconciliation_items, provider_transactions
payment_obligations
P3-01. Per-order obligations DEPOSIT / PI_POINT / REMAINING in integer VND; immutable amounts, OPEN -> SETTLED | CANCELLED with expectedVersion; cash settles by allocations, PI_POINT by an accepted REDEEM.
public.payment_obligations · 18 cột · 11 check · 2 unique · 6 index · 2 policy · 8 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
order_id | uuid | NOT NULL | FK → orders | |
kind | text | NOT NULL | ||
method | text | NOT NULL | ||
order_cycle_id | uuid | FK → order_cycles | ||
amount_vnd | bigint | NOT NULL | ||
points | integer | |||
point_rate_snapshot_vnd | numeric | |||
point_request_id | uuid | FK → point_requests | ||
source_id | text | NOT NULL | ||
status | text | NOT NULL | ||
settled_at | timestamptz | |||
change_source | text | NOT NULL | ||
change_source_id | text | NOT NULL | ||
change_reason | text | |||
created_at | timestamptz | NOT NULL | ||
updated_at | timestamptz | NOT NULL | ||
version | integer | NOT NULL |
Khoá chính: id
Trỏ ra (3):
order_cycle_id→order_cycles·ON DELETE RESTRICTorder_id→orders·ON DELETE RESTRICTpoint_request_id→point_requests·ON DELETE RESTRICT
Được trỏ tới (8): cashbook_entries, cod_collections, deposit_checkouts, deposit_checkouts, order_cycle_close_values, payment_allocations, payment_intents, payment_remaining_recalcs
payment_events
P3-01. Append-only verified provider observations per intent; unique (provider, provider_event_id).
public.payment_events · 14 cột · 8 check · 1 unique · 3 index · 1 policy · 3 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
intent_id | uuid | NOT NULL | FK → payment_intents | |
provider | text | NOT NULL | ||
provider_mode | text | NOT NULL | ||
provider_event_id | text | NOT NULL | ||
event_type | text | NOT NULL | ||
reported_status | text | NOT NULL | ||
provider_txn_id | text | |||
reported_amount_vnd | bigint | |||
currency | text | NOT NULL | ||
payload_hash | bytea | NOT NULL | ||
occurred_at | timestamptz | |||
recorded_at | timestamptz | NOT NULL | ||
correlation_id | correlation_ref | NOT NULL |
Khoá chính: id
Trỏ ra (1):
intent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới (1): payment_event_conflicts
payment_overpayment_cases
P3-05, PAF-P1-18 (DEC-PAF-08). Immutable offline excess-deposit case (cọc dư), one per excess: CLOSE at the close (final price below deposit + points value), SKIP for the increase after a skipped cycle; an order may hold several. Each case has its own reference code. Records the excess in integer VND; never a refund, a provider call or a point reversal (sow/03 s7.3). OWN + Finance read.
public.payment_overpayment_cases · 14 cột · 6 check · 3 unique · 5 index · 2 policy · 4 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
order_id | uuid | NOT NULL | FK → orders | |
close_outcome_id | uuid | FK → order_close_outcomes | ||
owner_account_id | uuid | NOT NULL | FK → accounts | |
final_total_vnd | bigint | NOT NULL | ||
deposit_vnd | bigint | NOT NULL | ||
points_value_vnd | bigint | NOT NULL | ||
excess_vnd | bigint | NOT NULL | P3-05, PAF-P1-18. CLOSE: the excess at the close (constraint payment_overpayment_cases_money); SKIP: the increase over the cases already open. The excess of an order is the sum over its cases. | |
status | text | NOT NULL | ||
source_id | text | NOT NULL | ||
created_at | timestamptz | NOT NULL | ||
version | integer | NOT NULL | ||
kind | text | NOT NULL | PAF-P1-18. CLOSE: opened by the close hook payment.open_remaining (source overpayment:<order>); SKIP: the increase of the excess after a skipped cycle (PAF-P1-03, no close outcome). | |
reference_code | text | NOT NULL | PAF-P1-18 (DEC-PAF-08, BR-APP-08 / BR-MD-07). Reference of the case for the offline handling: DU + ddmmyyyy (Vietnam day of created_at) + 4 digits, from campaign.next_daily_code('excess_deposit', 'DU', 4); issued by the insert guard, never chosen by the caller. |
Khoá chính: id
Trỏ ra (3):
close_outcome_id→order_close_outcomes·ON DELETE RESTRICTorder_id→orders·ON DELETE RESTRICTowner_account_id→accounts·ON DELETE RESTRICT
Được trỏ tới (1): refund_cases
payment_reconciliation_runs
P3-13. One row per provider/mode, VN business date and rerun; immutable after COMPLETE/INCOMPLETE. Evidence and totals only: no tolerance, no ledger or transaction write. MOCK only (G-FIN).
public.payment_reconciliation_runs · 24 cột · 12 check · 1 unique · 3 index · 4 policy · 4 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
provider | text | NOT NULL | ||
provider_mode | text | NOT NULL | ||
run_date_vn | date | NOT NULL | ||
run_version | integer | NOT NULL | ||
timezone | text | NOT NULL | ||
window_start | timestamptz | NOT NULL | ||
window_end | timestamptz | NOT NULL | ||
trigger_kind | text | NOT NULL | ||
requested_by | uuid | FK → accounts | ||
status | text | NOT NULL | ||
started_at | timestamptz | NOT NULL | ||
finished_at | timestamptz | |||
provider_snapshot_ref | text | |||
remote_dataset_hash | bytea | |||
local_totals | jsonb | |||
remote_totals | jsonb | |||
error_code | text | |||
lease_owner | text | |||
lease_expires_at | timestamptz | |||
correlation_id | correlation_ref | NOT NULL | ||
created_at | timestamptz | NOT NULL | ||
updated_at | timestamptz | NOT NULL | ||
version | integer | NOT NULL |
Khoá chính: id
Trỏ ra (1):
requested_by→accounts·ON DELETE RESTRICT
Được trỏ tới (1): payment_reconciliation_items
payment_allocations
P3-01. Append-only capture -> obligation allocations; sums never exceed the capture or the obligation.
public.payment_allocations · 6 cột · 2 check · 2 unique · 4 index · 0 policy · 4 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
transaction_id | uuid | NOT NULL | FK → provider_transactions | |
obligation_id | uuid | NOT NULL | FK → payment_obligations | |
amount_vnd | bigint | NOT NULL | ||
source_id | text | NOT NULL | ||
created_at | timestamptz | NOT NULL |
Khoá chính: id
Trỏ ra (2):
obligation_id→payment_obligations·ON DELETE RESTRICTtransaction_id→provider_transactions·ON DELETE RESTRICT
Được trỏ tới: không có
payment_event_conflicts
#479 T9. Verified provider observations whose event id was already stored (payment_events.event_id) with another intent, event type, status, transaction id or amount: never applied, listed for Finance (payments_needing_attention PROVIDER_EVENT_CONFLICT). One row per payload hash. Append-only, SYSTEM_ONLY.
public.payment_event_conflicts · 14 cột · 7 check · 1 unique · 3 index · 0 policy · 2 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
event_id | uuid | NOT NULL | FK → payment_events | |
intent_id | uuid | NOT NULL | FK → payment_intents | |
provider | text | NOT NULL | ||
provider_mode | text | NOT NULL | ||
provider_event_id | text | NOT NULL | ||
event_type | text | NOT NULL | ||
reported_status | text | NOT NULL | ||
provider_txn_id | text | |||
reported_amount_vnd | bigint | |||
payload_hash | bytea | NOT NULL | ||
occurred_at | timestamptz | |||
recorded_at | timestamptz | NOT NULL | ||
correlation_id | correlation_ref | NOT NULL |
Khoá chính: id
Trỏ ra (2):
event_id→payment_events·ON DELETE RESTRICTintent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới: không có
payment_hold_releases
#479 two-step. The release (cancelPayment) of a provider hold (AUTHORIZED) whose payment attempt ended FAILED: attempts, last result, earliest next attempt (the recovery sweep backoff). RELEASING -> RELEASED | CAPTURED (the provider captured anyway: a LATE_CAPTURE for Finance) | GAVE_UP (Finance attention HOLD_RELEASE_FAILED). Not a payment fact. SYSTEM_ONLY: RLS forced, no grant; written by payment.system_claim_hold_release and payment.system_note_hold_release (pi_worker).
public.payment_hold_releases · 10 cột · 6 check · 0 unique · 2 index · 0 policy · 3 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
intent_id | uuid | NOT NULL | PK FK → payment_intents | |
status | text | NOT NULL | ||
attempts | integer | NOT NULL | ||
last_result | text | |||
last_attempt_at | timestamptz | |||
next_attempt_at | timestamptz | NOT NULL | ||
ended_at | timestamptz | |||
version | integer | NOT NULL | ||
created_at | timestamptz | NOT NULL | ||
updated_at | timestamptz | NOT NULL |
Khoá chính: intent_id
Trỏ ra (1):
intent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới: không có
payment_intent_leases
#479 T4 / two-step / buyer re-check. Who may run one provider step of an intent (SEND the create, CAPTURE an authorized session, QUERY for the buyer) until leased_until. Not a payment fact. SYSTEM_ONLY: RLS forced, no grant; written by payment.lease_core.
public.payment_intent_leases · 6 cột · 3 check · 0 unique · 1 index · 0 policy · 0 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
intent_id | uuid | NOT NULL | PK FK → payment_intents | |
purpose | text | NOT NULL | PK | |
holder | uuid | NOT NULL | ||
leased_until | timestamptz | NOT NULL | ||
claims | integer | NOT NULL | ||
claimed_at | timestamptz | NOT NULL |
Khoá chính: intent_id, purpose
Trỏ ra (1):
intent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới: không có
payment_intent_recovery_checks
#479 T8. Recovery bookkeeping of the payment.intent_recover sweep, one row per intent it checked: attempts, last check, earliest next check (backoff). Not a payment fact (the intent is unchanged). SYSTEM_ONLY: RLS forced, no grant; written by payment.system_note_intent_check (pi_worker).
public.payment_intent_recovery_checks · 4 cột · 2 check · 0 unique · 1 index · 0 policy · 0 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
intent_id | uuid | NOT NULL | PK FK → payment_intents | |
attempts | integer | NOT NULL | ||
last_checked_at | timestamptz | NOT NULL | ||
next_check_at | timestamptz | NOT NULL |
Khoá chính: intent_id
Trỏ ra (1):
intent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới: không có
payment_intent_sessions
#479 T5. How the buyer pays the open provider session of one intent (web page, app deeplink, QR string, the provider's own session end), as the provider reported it; written once (payment.session_core), append-only. Read through the intent (U-04 own, F-01 Finance).
public.payment_intent_sessions · 6 cột · 4 check · 0 unique · 1 index · 1 policy · 2 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
intent_id | uuid | NOT NULL | PK FK → payment_intents | |
pay_url | text | |||
deeplink | text | |||
qr_data | text | |||
provider_expires_at | timestamptz | |||
recorded_at | timestamptz | NOT NULL |
Khoá chính: intent_id
Trỏ ra (1):
intent_id→payment_intents·ON DELETE RESTRICT
Được trỏ tới: không có
payment_reconciliation_items
P3-13. One payment discrepancy of a run (five sow/03 s12 types); evidence immutable, handling OPEN -> IN_PROGRESS -> RESOLVED. Never edits provider_transactions/intents/obligations.
public.payment_reconciliation_items · 30 cột · 14 check · 1 unique · 5 index · 4 policy · 5 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
run_id | uuid | NOT NULL | FK → payment_reconciliation_runs | |
discrepancy_type | text | NOT NULL | ||
item_key | text | NOT NULL | ||
transaction_id | uuid | FK → provider_transactions | ||
intent_id | uuid | FK → payment_intents | ||
provider_txn_id | text | |||
external_request_ref | text | |||
provider_recorded_at | timestamptz | |||
local_kind | text | |||
remote_kind | text | |||
local_status | text | |||
remote_status | text | |||
local_amount_vnd | bigint | |||
remote_amount_vnd | bigint | |||
remote_currency | text | |||
evidence | jsonb | NOT NULL | ||
remote_payload_hash | bytea | |||
status | text | NOT NULL | ||
owner_account_id | uuid | FK → accounts | ||
note | text | |||
retry_count | integer | NOT NULL | ||
last_retry_at | timestamptz | |||
resolved_by | uuid | FK → accounts | ||
resolved_at | timestamptz | |||
resolution_note | text | |||
correlation_id | correlation_ref | NOT NULL | ||
created_at | timestamptz | NOT NULL | ||
updated_at | timestamptz | NOT NULL | ||
version | integer | NOT NULL |
Khoá chính: id
Trỏ ra (5):
intent_id→payment_intents·ON DELETE RESTRICTowner_account_id→accounts·ON DELETE RESTRICTresolved_by→accounts·ON DELETE RESTRICTrun_id→payment_reconciliation_runs·ON DELETE RESTRICTtransaction_id→provider_transactions·ON DELETE RESTRICT
Được trỏ tới: không có
payment_remaining_recalcs
FU-SHORTAGE2. Immutable record of what a partial shortage case did to the REMAINING obligation of an Order: amended, excess refunded (online) or returned offline (COD), unchanged, or undecided with a reason. OWN + Operations read.
public.payment_remaining_recalcs · 16 cột · 5 check · 2 unique · 4 index · 2 policy · 2 trigger · RLS bật
| Cột | Kiểu | Khoá | Mô tả | |
|---|---|---|---|---|
id | uuid | NOT NULL | PK | |
order_id | uuid | NOT NULL | FK → orders | |
owner_account_id | uuid | NOT NULL | FK → accounts | |
shortage_case_id | uuid | NOT NULL | FK → stock_shortage_cases | |
obligation_id | uuid | NOT NULL | FK → payment_obligations | |
method | text | NOT NULL | ||
status_before | text | NOT NULL | ||
previous_amount_vnd | bigint | NOT NULL | ||
target_vnd | bigint | NOT NULL | ||
new_amount_vnd | bigint | NOT NULL | ||
excess_vnd | bigint | NOT NULL | ||
action | text | NOT NULL | ||
reason | text | |||
request_key | text | NOT NULL | ||
source_id | text | NOT NULL | ||
created_at | timestamptz | NOT NULL |
Khoá chính: id
Trỏ ra (4):
obligation_id→payment_obligations·ON DELETE RESTRICTorder_id→orders·ON DELETE RESTRICTowner_account_id→accounts·ON DELETE RESTRICTshortage_case_id→stock_shortage_cases·ON DELETE RESTRICT
Được trỏ tới: không có