svc-payments¶
NovaTrek Payments Service | Support | v1.1.0 | NovaTrek Platform Team
Manages payments, refunds, and billing for adventure bookings at NovaTrek Adventures.
Swagger UI Download OpenAPI Spec
Integration Context¶
Data Store¶
Overview¶
| Property | Detail |
|---|---|
| Engine | PostgreSQL 15 |
| Schema | payments |
| Tables | payments, refunds, payment_methods, daily_summaries, disputes, refund_policy_evaluations |
| Estimated Volume | ~2,500 transactions/day |
| Connection Pool | min 10 / max 30 / idle timeout 5min |
| Backup Strategy | Continuous WAL archiving, daily base backup, 7-year retention (financial) |
Key Features¶
- PCI-DSS compliant token storage (no raw card data)
- Idempotent payment processing via request keys
- Double-entry ledger for financial reconciliation
Table Reference¶
payments¶
Payment transaction records with tokenized card references
| Column | Type | Constraints |
|---|---|---|
payment_id | UUID | PK |
reservation_id | UUID | NOT NULL |
guest_id | UUID | NOT NULL |
amount | DECIMAL(10,2) | NOT NULL |
currency | CHAR(3) | NOT NULL |
payment_method_id | UUID | NOT NULL, FK -> payment_methods |
gateway_ref | VARCHAR(255) | NOT NULL |
status | VARCHAR(20) | NOT NULL |
idempotency_key | VARCHAR(64) | NOT NULL, UNIQUE |
created_at | TIMESTAMPTZ | NOT NULL |
Indexes:
idx_pay_reservationonreservation_ididx_pay_guestonguest_ididx_pay_idempotencyonidempotency_key(UNIQUE)idx_pay_statusonstatus, created_at DESC
refunds¶
Refund records linked to original payments
| Column | Type | Constraints |
|---|---|---|
refund_id | UUID | PK |
payment_id | UUID | NOT NULL, FK -> payments |
amount | DECIMAL(10,2) | NOT NULL |
reason | TEXT | NOT NULL |
gateway_ref | VARCHAR(255) | NOT NULL |
status | VARCHAR(20) | NOT NULL |
created_at | TIMESTAMPTZ | NOT NULL |
Indexes:
idx_refund_paymentonpayment_id
payment_methods¶
Tokenized payment instruments (no raw card data stored)
| Column | Type | Constraints |
|---|---|---|
method_id | UUID | PK |
guest_id | UUID | NOT NULL |
token | VARCHAR(255) | NOT NULL (gateway token) |
card_last_four | CHAR(4) | NOT NULL |
card_brand | VARCHAR(20) | NOT NULL |
expiry_month | SMALLINT | NOT NULL |
expiry_year | SMALLINT | NOT NULL |
is_default | BOOLEAN | NOT NULL, DEFAULT FALSE |
Indexes:
idx_pm_guestonguest_id
Solutions Affecting This Service¶
| Ticket | Solution | Capabilities | Date |
|---|---|---|---|
| NTK-10009 | Refund and Dispute Management Workflows | CAP-5.5, CAP-5.4 | 2026-03-06 |
Endpoints (12 total)¶
POST /payments -- Process a payment¶
Initiates payment processing for a reservation. The payment is authorized and captured based on the selected method.
GET /payments/{payment_id} -- Retrieve payment details¶
Returns full details of a specific payment including processor reference and status history.
POST /payments/{payment_id}/refund -- Initiate a refund¶
Creates a refund for the specified payment. Supports full or partial refunds.
GET /guests/{guest_id}/payment-history -- Retrieve payment history for a guest¶
Returns paginated payment history for a specific guest, ordered by most recent first.
GET /disputes -- List disputes with optional filters¶
POST /disputes -- Create a refund dispute¶
Opens a dispute for a payment. The system evaluates the refund request against
GET /disputes/{dispute_id} -- Retrieve dispute details¶
PATCH /disputes/{dispute_id} -- Update a dispute (assign, add notes, escalate)¶
Supports field-level updates. Requires role matching the dispute tier.
POST /disputes/{dispute_id}/resolve -- Resolve a dispute with refund decision¶
Resolves the dispute with a decision (FULL_REFUND, PARTIAL_REFUND, DENIED).
POST /chargebacks -- Ingest a chargeback notification from payment processor¶
Creates a dispute record from an external chargeback notification.
POST /refund-policy/evaluate -- Evaluate refund eligibility against policy (dry-run)¶
Returns the policy evaluation result without creating a dispute.
GET /payments/daily-summary -- Get daily payment summary¶
Returns an aggregated summary of payments processed on a given date, broken down by method and status.
Consuming Applications¶
| Application | Screens Using This Service |
|---|---|
| Guest Portal | Booking Flow, Reservation Management |
| Operations Dashboard | Analytics Dashboard, Partner Bookings |
| Adventure App | My Reservations |
Events Published¶
| Event | Channel | Trigger | Consumers |
|---|---|---|---|
payment.processed | novatrek.support.payment.processed | POST /payments | svc-reservations, svc-notifications |