27 lines
2.2 KiB
Markdown
27 lines
2.2 KiB
Markdown
# ADR 0005: Retain the opaque payer token without additional pseudonymization
|
||
|
||
- Status: Accepted
|
||
- Date: 2026-08-20
|
||
|
||
## Context
|
||
|
||
Initial profiling found 1,034,368 populated `payer_card_key` rows and 402,173 distinct values. Values are opaque alphanumeric tokens 6–11 characters long. The later CTO data guide confirms that the token pseudonymizes a buyer card within one merchant: the same card receives a different token at another merchant. Approximately 53% of rows are missing the value because card information is not returned when the bank stage does not complete.
|
||
|
||
Applying HMAC would preserve equality while adding secret storage, rotation, and re-import operations. Because the supplied value is already opaque and empirically merchant-scoped, that extra transformation provides limited benefit for this dataset and does not make the identifier anonymous.
|
||
|
||
## Decision
|
||
|
||
Retain the supplied `payer_card_key` unchanged as a nullable, restricted internal analytical field. Equality is valid only within the owning merchant and may support covered repeat-card analysis.
|
||
|
||
Every lookup, grouping, or uniqueness calculation involving the token must include the merchant boundary. The token must never be returned by merchant-facing APIs, written to logs or traces, included in exports, rendered in the frontend, or sent to AvalAI/another third party. It must not be described as a card number, account number, or verified unique person.
|
||
|
||
Metrics derived from it must disclose source coverage and use language such as “کارتهای بازگشتی در دادههای موجود,” not claims about verified customers or people. Evidence of reversibility or cross-merchant linkability triggers a new security review and ADR.
|
||
|
||
## Consequences
|
||
|
||
- Repeat-card-token frequency, retry, and success analyses are valid within one merchant for populated values.
|
||
- No new pseudonymization secret or rotation workflow is required for the hackathon dataset.
|
||
- Database access remains more privileged than dashboard/API access because the token is still linkable behavioral data.
|
||
- Missing coverage prevents treating distinct-token counts as complete payer counts.
|
||
- Tests must verify tenant scoping and assert that DTOs, logs, exports, and AI payloads cannot contain the field.
|