Bài 71: Payment Stripe Integration — PaymentIntent + Webhook

Sau bài học, bạn sẽ:

• Hiểu Stripe PaymentIntent flow — server tạo intent + client confirm với 3DS challenge + automatic capture vs manual confirm.
• Cài stripe-rust crate v0.36+ (community Stripe Rust SDK) với feature runtime-tokio-hyper-rustls align tokio + rustls workspace lock.
• Implement POST /api/v1/payments/orders/{order_id}/intent gọi Stripe API tạo PaymentIntent + return client_secret cho frontend Stripe Elements.
• Implement POST /webhooks/stripe với signature verify HMAC-SHA256 (lock B37 continued — webhook signature verify pattern).
• Pattern idempotent webhook handler: dedup qua event.id PRIMARY KEY + bảng audit trail stripe_webhook_events 7 column + 2 index.
• Update payments.status từ webhook event qua 2 handler PaymentIntentSucceeded + PaymentIntentPaymentFailed; transition orders.status pending → paid khi success.
• Query payment_payload @> {"payment_intent_id": ...} (lock B60 continued — JSONB @> containment với jsonb_path_ops index match nhanh).
• Foundation cho B72 (Service Layer trait abstraction), G14 (analytics dashboard payment), G18 (Stripe production setup live key + 3DS SCA challenge full).

Stripe có 2 API thanh toán — Charge API (legacy 2011) chỉ 1 step charge thẳng nhưng KHÔNG hỗ trợ SCA (Strong Customer Authentication) bắt buộc tại EU từ PSD2 2019 + KHÔNG retry safe nếu network drop; và PaymentIntent API (2018) — multi-step stateful object track full lifecycle thanh toán, hỗ trợ 3DS challenge tự động, retry an toàn qua idempotency key Stripe-native. Stripe khuyến cáo PaymentIntent cho mọi tích hợp mới từ 2019; Shop API lock PaymentIntent.

Flow đầy đủ 8 step request/response:

1. Client → Server: POST /api/v1/payments/orders/{order_id}/intent
2. Server → Stripe API: stripe.PaymentIntent.create(amount, currency, metadata)
3. Stripe → Server: PaymentIntent { id: "pi_xxx", client_secret: "pi_xxx_secret_yyy", status: "requires_payment_method" }
4. Server → Client: { client_secret }
5. Client (browser, Stripe Elements): stripe.confirmCardPayment(client_secret, { payment_method: {...} })
6. Stripe (3DS challenge nếu issuer yêu cầu) → user complete OTP/biometric
7. Stripe → Server (webhook): payment_intent.succeeded HOẶC payment_intent.payment_failed
8. Server: update payments.status + orders.status driven bởi webhook event

3 nguyên tắc bất biến đi kèm flow này:

• Server KHÔNG handle card data — toàn bộ thẻ tín dụng (number, CVV, exp) đi thẳng từ browser qua Stripe.js SDK lên Stripe servers; Shop API chỉ trao đổi PaymentIntent ID + client_secret. Đây là yêu cầu PCI compliance — nếu Shop API touch raw card data thì phải audit PCI DSS Level 1 (cost ~50k-100k USD/năm + recurring audit).
• Webhook là source of truth — server tin webhook (Stripe → Shop API) KHÔNG tin client response (browser → Shop API). Lý do: client có thể bị đóng tab giữa lúc 3DS challenge, network drop, hoặc malicious user fake response success. Webhook đến từ Stripe có signature HMAC verify được, không thể fake.
• Test mode — Stripe có 2 mode: test (key sk_test_... + test card 4242 4242 4242 4242 miễn phí mọi flow) + live (key sk_live_... charge thật, cần verify business). Shop API dev + CI chỉ dùng test mode; live mode chỉ activate ở G18 production setup.

Stripe KHÔNG maintain official Rust SDK — stripe-rust là community crate (maintained bởi arlyon từ 2018, version 0.36 release Q1 2026 cover toàn bộ Stripe API 2026-01 version + auto-generated từ OpenAPI spec). Cài qua workspace deps:

# File: Cargo.toml (workspace root)
[workspace.dependencies]
# ... các dep cũ B70 giữ nguyên
stripe = { version = "0.36", features = ["runtime-tokio-hyper-rustls"] }

Add vào crates/shop-api/Cargo.toml:

# File: crates/shop-api/Cargo.toml
[dependencies]
# ... cũ
stripe = { workspace = true }

Feature runtime-tokio-hyper-rustls lock decision: align tokio runtime workspace lock B10 + hyper HTTP client + rustls pure-Rust TLS (skip native-tls/OpenSSL bloat + cross-platform reliable lock B51 continued). Crate cung cấp 2 nhóm API chính: stripe::Client sync với secret key + stripe::Webhook::construct_event helper verify signature parse Event.

Env config thêm 2 field vào AppConfig (B56 đã setup):

// File: crates/shop-api/src/config.rs (extend B56)
pub struct AppConfig {
    // ... 8 field cũ B56 (app_env, port, database_url, redis_url, jwt_secret, ...)
    pub stripe_secret_key: String,        // sk_test_... (dev) hoặc sk_live_... (prod G18)
    pub stripe_webhook_secret: String,    // whsec_... shared secret Stripe webhook signing
}

impl AppConfig {
    pub fn from_env() -> anyhow::Result<Self> {
        Ok(Self {
            // ... existing field cũ
            stripe_secret_key: std::env::var("STRIPE_SECRET_KEY")
                .map_err(|_| anyhow::anyhow!("STRIPE_SECRET_KEY env var required"))?,
            stripe_webhook_secret: std::env::var("STRIPE_WEBHOOK_SECRET")
                .map_err(|_| anyhow::anyhow!("STRIPE_WEBHOOK_SECRET env var required"))?,
        })
    }
}

Update .env.example dev onboarding:

# File: .env.example (extend B70)
# ... env cũ DATABASE_URL/PORT/APP_ENV/JWT_SECRET

# Stripe (test mode dev)
STRIPE_SECRET_KEY=sk_test_REPLACE_ME
STRIPE_WEBHOOK_SECRET=whsec_REPLACE_ME

Lock decision B71 — API key + webhook secret QUA env MANDATORY: KHÔNG hard-code vào source code (lock B70 security continued); nếu lộ thì rotate qua Stripe dashboard không cần redeploy code. Production (G18) inject env qua orchestrator secret manager (AWS Secrets Manager, Kubernetes Secret, HashiCorp Vault) — KHÔNG dùng .env file. from_env MANDATORY fail-fast ở startup (Result + anyhow::anyhow!) tránh runtime panic muộn lúc Stripe API call.

Module crates/shop-db/src/payments.rs đã có placeholder skeleton từ B54 (bảng payments + 6 cột + 2 index). B71 mở rộng thêm 3 hàm DB phục vụ 2 endpoint + 2 webhook handler:

// File: crates/shop-db/src/payments.rs (extend B54 skeleton)
use sqlx::PgPool;
use chrono::{DateTime, Utc};
use serde_json::Value;

pub struct PaymentRow {
    pub id: i64,
    pub order_id: i64,
    pub payment_type: String,
    pub payment_payload: Value,
    pub status: String,
    pub created_at: DateTime<Utc>,
}

/// Tạo hoặc cập nhật payment record cho order — UPSERT 1 order = 1 payment.
pub async fn create_stripe_payment(
    pool: &PgPool,
    order_id: i64,
    payment_intent_id: &str,
    customer_id: Option<&str>,
    amount: i64,
    currency: &str,
) -> Result<PaymentRow, sqlx::Error> {
    let payload = serde_json::json!({
        "payment_intent_id": payment_intent_id,
        "customer_id": customer_id,
        "amount": amount,
        "currency": currency,
    });

    sqlx::query_as!(
        PaymentRow,
        r#"
        INSERT INTO payments (order_id, payment_type, payment_payload, status)
        VALUES ($1, 'stripe', $2, 'pending')
        ON CONFLICT (order_id) DO UPDATE SET
            payment_payload = EXCLUDED.payment_payload,
            status = 'pending'
        RETURNING id, order_id, payment_type,
                  payment_payload as "payment_payload: Value",
                  status, created_at
        "#,
        order_id, payload
    )
    .fetch_one(pool)
    .await
}

Hàm update_status_by_intent dùng JSONB @> containment operator lock B60 — index jsonb_path_ops match nhanh O(log n) không phải scan toàn bảng:

// File: crates/shop-db/src/payments.rs (tiếp)
pub async fn update_status_by_intent(
    pool: &PgPool,
    payment_intent_id: &str,
    new_status: &str,
) -> Result<Option<PaymentRow>, sqlx::Error> {
    sqlx::query_as!(
        PaymentRow,
        r#"
        UPDATE payments SET status = $1
        WHERE payment_payload @> $2::jsonb
        RETURNING id, order_id, payment_type,
                  payment_payload as "payment_payload: Value",
                  status, created_at
        "#,
        new_status,
        serde_json::json!({"payment_intent_id": payment_intent_id})
    )
    .fetch_optional(pool)
    .await
}

pub async fn find_by_intent_id(
    pool: &PgPool,
    payment_intent_id: &str,
) -> Result<Option<PaymentRow>, sqlx::Error> {
    sqlx::query_as!(
        PaymentRow,
        r#"
        SELECT id, order_id, payment_type,
               payment_payload as "payment_payload: Value",
               status, created_at
        FROM payments
        WHERE payment_payload @> $1::jsonb
        "#,
        serde_json::json!({"payment_intent_id": payment_intent_id})
    )
    .fetch_optional(pool)
    .await
}

3 lock decision DB layer B71:

• payment_payload @> $1::jsonb lock B60 continued — query containment thay đổi từ "tìm payment có payment_intent_id = X" thành "tìm payment mà payload chứa {"payment_intent_id": "X"}". Cùng kết quả, dùng index jsonb_path_ops match O(log n); flexible khi schema payment_payload thay đổi (thêm customer_id, charge_id) không cần migration ALTER cột.
• ON CONFLICT (order_id) DO UPDATE UPSERT lock — 1 order = 1 payment record (B54 schema lock UNIQUE order_id constraint). Scenario: user click "Pay" lần đầu tạo PaymentIntent A; mất kết nối; click lần 2 → tạo PaymentIntent B; ON CONFLICT update payload sang B + reset status = pending; record cũ A bị orphan trong Stripe (sẽ auto-cancel sau 24h). Tránh duplicate row payment cùng order.
• Status transition pending → success | failed (driven bởi webhook MANDATORY, KHÔNG bởi handler endpoint); enforce qua application layer + CHECK constraint B54 (status TEXT CHECK IN ('pending','success','failed')).

Tạo file mới crates/shop-api/src/routes/payments.rs chứa handler create intent + webhook. Handler thứ nhất gọi Stripe API tạo PaymentIntent + persist record cục bộ:

// File: crates/shop-api/src/routes/payments.rs
use axum::{extract::{State, Path}, Json, http::StatusCode, http::HeaderMap};
use stripe::{Client, CreatePaymentIntent, PaymentIntent, Currency, Webhook};
use shop_common::error::AppError;
use shop_db::payments as db;
use crate::state::AppState;

#[derive(Debug, Clone, serde::Serialize)]
pub struct CreateIntentResponse {
    pub client_secret: String,
    pub payment_intent_id: String,
}

pub async fn create_payment_intent(
    State(state): State<AppState>,
    Path(order_id): Path<i64>,
) -> Result<Json<CreateIntentResponse>, AppError> {
    // 1. Fetch order verify tồn tại + status hợp lệ
    let order = sqlx::query!(
        "SELECT id, total, status FROM orders WHERE id = $1",
        order_id
    )
    .fetch_optional(&state.db).await?
    .ok_or_else(|| AppError::NotFound(format!("order {} not found", order_id)))?;

    if order.status != "pending" {
        return Err(AppError::Validation(format!(
            "cannot create payment intent for order in status {}",
            order.status
        )));
    }

    // 2. Convert Decimal total → smallest currency unit (VND integer, KHÔNG sub-unit)
    let amount_cent = (order.total * rust_decimal::Decimal::from(100))
        .to_i64()
        .ok_or_else(|| AppError::Internal("amount conversion overflow".into()))?;

    // 3. Gọi Stripe API tạo PaymentIntent
    let client = Client::new(state.config.stripe_secret_key.clone());
    let mut params = CreatePaymentIntent::new(amount_cent, Currency::VND);
    params.metadata = Some(std::collections::HashMap::from([
        ("order_id".to_string(), order.id.to_string()),
    ]));
    params.automatic_payment_methods = Some(stripe::CreatePaymentIntentAutomaticPaymentMethods {
        enabled: true,
        allow_redirects: None,
    });

    let intent = PaymentIntent::create(&client, params).await
        .map_err(|e| AppError::Internal(format!("stripe create failed: {}", e)))?;

    // 4. Persist payment record local DB
    db::create_stripe_payment(
        &state.db,
        order_id,
        &intent.id.to_string(),
        None,
        amount_cent,
        "vnd",
    ).await?;

    // 5. Return client_secret cho client confirm 3DS qua Stripe Elements
    Ok(Json(CreateIntentResponse {
        client_secret: intent.client_secret.unwrap_or_default(),
        payment_intent_id: intent.id.to_string(),
    }))
}

4 lock decision handler create intent:

• Metadata order_id đính kèm PaymentIntent — Stripe gửi metadata về trong webhook event payload, giúp trace ngược order_id khi event đến. Có thể thêm user_id sau khi B112 wire JWT auth.
• Currency lock VND Shop API — Việt Nam đồng integer, KHÔNG sub-unit (1 VND nhỏ nhất, không có "xu"). Khác USD/EUR có cent (1 USD = 100 cent). Convert order.total NUMERIC(15,2) sang i64 qua * 100 để align Stripe API smallest currency unit convention — nhưng VND đã integer thì nhân 100 dư 2 chữ số 0 ở cuối (vd 50000.00 VND → 5000000) phục vụ Stripe accept, không ảnh hưởng UX (frontend display lại / 100).
• Status guard order = pending — không cho tạo intent cho order đã paid/shipped/cancelled (defensive); 422 Validation nếu vi phạm.
• automatic_payment_methods.enabled = true — Stripe tự render UI Elements support nhiều method (card, Apple Pay, Google Pay, ...) thay vì hard-code chỉ card; allow_redirects: None để Stripe quyết định theo method.

Stripe gửi event qua webhook URL với HTTP POST + header Stripe-Signature chứa timestamp + HMAC-SHA256:

POST /webhooks/stripe HTTP/1.1
Host: api.shop.example
Stripe-Signature: t=1718438400,v1=8c7e2c3c1c8b2d3c4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d
Content-Type: application/json

{"id": "evt_xxx", "type": "payment_intent.succeeded", "data": {...}}

Signature format chuẩn Stripe: HMAC-SHA256(secret, <timestamp>.<raw_body>) — secret là STRIPE_WEBHOOK_SECRET shared giữa Stripe + Shop API; concat timestamp + "." + raw_body (body MANDATORY raw bytes, KHÔNG re-serialize qua serde_json::Value vì sẽ thay đổi byte order key); compute HMAC-SHA256 + hex encode + compare với v1= value bằng constant-time. Pattern verify tóm tắt 4 step:

• Parse t=<ts> + v1=<hex> từ header value.
• Reject nếu now() - ts > 5 phút (replay attack window — attacker capture + replay sau 5 phút sẽ fail).
• Compute HMAC-SHA256(secret, ts.body) + hex encode.
• Constant-time compare với v1 (lock B37 + B70 security continued).

Crate stripe-rust đã đóng gói toàn bộ pattern trên qua helper Webhook::construct_event — Shop API chỉ gọi 1 hàm thay tự implement HMAC manual:

// File: crates/shop-api/src/routes/payments.rs (tiếp)
pub async fn stripe_webhook(
    State(state): State<AppState>,
    headers: HeaderMap,
    body: String,                                // raw body cho HMAC verify
) -> Result<StatusCode, AppError> {
    // 1. Get signature header
    let signature = headers
        .get("Stripe-Signature")
        .and_then(|v| v.to_str().ok())
        .ok_or_else(|| AppError::BadRequest("missing Stripe-Signature header".into()))?;

    // 2. Verify signature + parse Event (HMAC-SHA256 + 5 phút tolerance built-in)
    let event = Webhook::construct_event(
        &body,
        signature,
        &state.config.stripe_webhook_secret,
    )
    .map_err(|e| {
        tracing::warn!(?e, "stripe webhook signature invalid");
        AppError::BadRequest("invalid webhook signature".into())
    })?;

    // 3. Dispatch handler theo event type (idempotent dedup BƯỚC 7)
    handle_stripe_event(&state, event).await?;

    Ok(StatusCode::OK)
}

4 lock decision webhook verify B71:

• Webhook::construct_event helper — dùng implementation Stripe-official KHÔNG manual HMAC implement. Đỡ 2 class lỗi: parse header sai format (Stripe có thể thêm v0/v2 scheme tương lai) + constant-time compare quên (B70 lock continued).
• 5 phút tolerance — default crate, replay attack window. Attacker capture signed webhook + replay sau 5 phút → Stripe check timestamp old → reject. Stripe docs khuyến cáo tolerance 5 phút (300 giây) balance giữa network latency + security.
• 400 BadRequest cho signature fail — KHÔNG 401 Unauthorized (401 imply credential sai, leak info "endpoint này cần auth + bạn provide wrong key"). 400 chung chung "request invalid" không expose internal logic. Stripe sẽ retry exponential 3 days nếu KHÔNG nhận 2xx — log warn để alert (signature liên tục fail có thể là webhook secret expired sau rotate).
• Body MANDATORY String raw (KHÔNG Json<Value>) — axum extract Json sẽ deserialize + re-serialize lại body, thay đổi byte order key → HMAC compute trên body modified sẽ FAIL signature verify. Bắt buộc dùng String hoặc Bytes extractor giữ raw bytes nguyên bản (lock B37 continued — raw body extractor MANDATORY cho webhook).

Stripe có thể gửi cùng 1 event 2 lần trong nhiều scenario: (i) network blip giữa Stripe → Shop API → Stripe không nhận 2xx → retry; (ii) server timeout > 10 giây Stripe coi như fail → retry; (iii) Shop API restart giữa lúc process → event re-deliver. Pattern dedup MANDATORY: cache event.id trong DB table riêng + check trước khi process. Migration 14:

-- File: crates/shop-db/migrations/20260616130000_create_stripe_webhook_events.sql

CREATE TABLE stripe_webhook_events (
    event_id      TEXT PRIMARY KEY,                                 -- Stripe event ID (evt_xxx)
    event_type    TEXT NOT NULL,                                    -- payment_intent.succeeded, ...
    received_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    processed_at  TIMESTAMPTZ,                                       -- NULL khi chưa xong
    status        TEXT NOT NULL DEFAULT 'received'
                  CHECK (status IN ('received', 'processed', 'failed')),
    error_message TEXT,                                              -- log error nếu status = failed
    raw_payload   JSONB NOT NULL                                     -- replay nếu cần
);

CREATE INDEX stripe_webhook_events_type_idx
    ON stripe_webhook_events(event_type, received_at DESC);

CREATE INDEX stripe_webhook_events_status_idx
    ON stripe_webhook_events(status) WHERE status != 'processed';

Handler chính handle_stripe_event 4 step: check dedup, insert record, process theo type, mark status:

// File: crates/shop-api/src/routes/payments.rs (tiếp)
async fn handle_stripe_event(
    state: &AppState,
    event: stripe::Event,
) -> Result<(), AppError> {
    let event_id = event.id.to_string();
    let event_type = event.type_.to_string();

    // 1. Check dedup — Stripe có thể gửi event 2 lần
    let existing = sqlx::query!(
        "SELECT status FROM stripe_webhook_events WHERE event_id = $1",
        event_id
    )
    .fetch_optional(&state.db).await?;

    if let Some(row) = existing {
        tracing::info!(event_id, status = %row.status, "stripe webhook already received, skip");
        return Ok(());                                  // idempotent return success
    }

    // 2. Insert event record audit trail (raw_payload preserve)
    let raw_payload = serde_json::to_value(&event)?;
    sqlx::query!(
        r#"
        INSERT INTO stripe_webhook_events (event_id, event_type, raw_payload)
        VALUES ($1, $2, $3)
        "#,
        event_id, event_type, raw_payload
    )
    .execute(&state.db).await?;

    // 3. Process event theo type
    let process_result = match event.type_ {
        stripe::EventType::PaymentIntentSucceeded => {
            handle_payment_succeeded(state, &event).await
        }
        stripe::EventType::PaymentIntentPaymentFailed => {
            handle_payment_failed(state, &event).await
        }
        other => {
            tracing::info!(?other, "stripe event type not handled");
            Ok(())
        }
    };

    // 4. Mark processed | failed status
    match &process_result {
        Ok(_) => {
            let _ = sqlx::query!(
                "UPDATE stripe_webhook_events SET status = 'processed', processed_at = NOW() WHERE event_id = $1",
                event_id
            ).execute(&state.db).await;
        }
        Err(e) => {
            let _ = sqlx::query!(
                "UPDATE stripe_webhook_events SET status = 'failed', error_message = $2 WHERE event_id = $1",
                event_id, e.to_string()
            ).execute(&state.db).await;
        }
    }

    process_result
}

2 handler riêng cho event type chính:

// File: crates/shop-api/src/routes/payments.rs (tiếp)
async fn handle_payment_succeeded(
    state: &AppState,
    event: &stripe::Event,
) -> Result<(), AppError> {
    let intent = match &event.data.object {
        stripe::EventObject::PaymentIntent(pi) => pi,
        _ => return Err(AppError::BadRequest("expected PaymentIntent".into())),
    };

    let intent_id = intent.id.to_string();

    // Update payment record local: status pending → success
    let payment = db::update_status_by_intent(&state.db, &intent_id, "success").await?
        .ok_or_else(|| AppError::NotFound(format!("payment not found for intent {}", intent_id)))?;

    // Transition order: pending → paid (guard nếu đã transition trước đó)
    sqlx::query!(
        "UPDATE orders SET status = 'paid' WHERE id = $1 AND status = 'pending'",
        payment.order_id
    )
    .execute(&state.db).await?;

    tracing::info!(intent_id, order_id = payment.order_id, "payment succeeded");
    Ok(())
}

async fn handle_payment_failed(
    state: &AppState,
    event: &stripe::Event,
) -> Result<(), AppError> {
    let intent = match &event.data.object {
        stripe::EventObject::PaymentIntent(pi) => pi,
        _ => return Err(AppError::BadRequest("expected PaymentIntent".into())),
    };

    let intent_id = intent.id.to_string();
    db::update_status_by_intent(&state.db, &intent_id, "failed").await?;

    tracing::warn!(intent_id, "payment failed");
    Ok(())
}

4 lock decision idempotent handler B71:

• Dedup qua event.id PRIMARY KEY — Stripe đảm bảo event.id unique cross-event; PRIMARY KEY constraint UNIQUE auto giúp race-safe insert (2 webhook đến cùng lúc → 1 insert thành công, 1 fail unique violation). Pattern reuse cho mọi external webhook Shop API tương lai (GitHub webhook G15, Twilio webhook G18).
• Stripe retry safe — lần 2 thấy event_id đã có trong bảng → log info + return Ok(()) → Stripe nhận 2xx + ngừng retry. Pattern chuẩn industry (Stripe docs khuyến cáo).
• Audit trail webhook events trong bảng riêng — không pollute bảng payments với metadata webhook; admin có thể query "tất cả event đã xử lý hôm qua" + "event nào status = failed" cho debug; G14 analytics dashboard reuse table này.
• Guard status = 'pending' trong UPDATE orders — nếu order đã transition shipped/delivered (admin manual) thì webhook đến không revert ngược về paid (lock B65 state machine continued).

Routes function build 2 endpoint cho module payments — endpoint create_payment_intent nằm trong nest /api/v1 chung; endpoint stripe_webhook nằm NGOÀI /api/v1 theo third-party convention:

// File: crates/shop-api/src/routes/payments.rs (cuối file)
use axum::Router;
use axum::routing::post;

pub fn routes_v1() -> Router<AppState> {
    Router::new()
        .route("/payments/orders/{order_id}/intent", post(create_payment_intent))
}

pub fn routes_webhook() -> Router<AppState> {
    Router::new()
        .route("/webhooks/stripe", post(stripe_webhook))
}

Wire vào crates/shop-api/src/router.rs (B65 đã lock pattern api_v1 nest):

// File: crates/shop-api/src/router.rs (extend)
let api_v1 = Router::new()
    // ... routes cũ B60-B70
    .merge(routes::payments::routes_v1());      // B71 create_payment_intent

let app = Router::new()
    .nest("/api/v1", api_v1)
    .merge(routes::payments::routes_webhook())  // B71 /webhooks/stripe NGOÀI /api/v1
    .with_state(state);

Cập nhật crates/shop-api/src/routes/mod.rs thêm pub mod payments;.

Lock decision URL webhook NGOÀI /api/v1: Stripe + GitHub + Twilio + mọi third-party webhook gọi URL trực tiếp không version. Lý do: (i) third-party service KHÔNG biết version API nội bộ Shop API; (ii) bump version /api/v1 → /api/v2 không nên break webhook; (iii) webhook là protocol contract với Stripe (signature secret), không phải REST resource client query. Convention /webhooks/{provider} top-level.

Test local với Stripe CLI — không cần expose public URL qua ngrok:

# Install Stripe CLI (macOS Homebrew)
brew install stripe/stripe-cli/stripe

# Login với Stripe account dashboard
stripe login
# → mở browser xác nhận device + grant access

# Forward webhook từ Stripe → local Shop API
stripe listen --forward-to localhost:3000/webhooks/stripe
# → "Ready! Your webhook signing secret is whsec_xxx (^C to quit)"
# Copy whsec_xxx set vào .env: STRIPE_WEBHOOK_SECRET=whsec_xxx

# Trigger test event mô phỏng payment succeeded
stripe trigger payment_intent.succeeded
# → Stripe CLI fake event + forward về localhost:3000/webhooks/stripe
# → Server log: "payment succeeded intent_id=pi_xxx order_id=N"

End-to-end test full flow:

# 1. Setup STRIPE_SECRET_KEY (từ dashboard test mode) + STRIPE_WEBHOOK_SECRET (từ stripe listen)
echo 'STRIPE_SECRET_KEY=sk_test_REPLACE_ME' >> .env
echo 'STRIPE_WEBHOOK_SECRET=whsec_REPLACE_ME' >> .env

# 2. Apply migration 14 + start server
cargo sqlx migrate run --source crates/shop-db/migrations
AUTO_MIGRATE=true cargo run -p shop-api

# 3. Create order pending (qua endpoint B66)
curl -X POST http://localhost:3000/api/v1/orders \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items":[{"product_id":1,"quantity":2}],"payment":{"type":"stripe"}}'
# → 201 Created order_id = 1 status = pending

# 4. Create payment intent
curl -X POST http://localhost:3000/api/v1/payments/orders/1/intent
# → 200 OK
# {
#   "client_secret": "pi_xxx_secret_yyy",
#   "payment_intent_id": "pi_xxx"
# }

# 5. Client confirm payment (test mode: dùng Stripe CLI hoặc test card 4242 frontend Elements)
# Stripe gửi webhook payment_intent.succeeded về /webhooks/stripe

# 6. Verify order status updated
curl http://localhost:3000/api/v1/orders/1
# status = "paid"

# 7. Verify payment record
docker compose exec postgres psql -U shop -d shop_dev -c \
  "SELECT id, order_id, status FROM payments WHERE order_id = 1;"
# status = success

# 8. Verify webhook event logged
docker compose exec postgres psql -U shop -d shop_dev -c \
  "SELECT event_id, event_type, status FROM stripe_webhook_events ORDER BY received_at DESC;"
# status = processed

• Stripe PaymentIntent flow: server tạo intent → client confirm 3DS qua Stripe Elements → webhook source of truth.
• stripe-rust crate v0.36+ với feature runtime-tokio-hyper-rustls align tokio + rustls workspace lock B10/B51.
• Env config: STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET qua AppConfig::from_env fail-fast — KHÔNG hard-code (lock B70 security continued).
• PaymentIntent metadata order_id đính kèm — Stripe gửi metadata về trong webhook event payload, giúp trace order khi event đến.
• Currency VND lock Shop API + amount integer (VND KHÔNG có sub-unit, vẫn nhân 100 theo Stripe smallest currency unit convention).
• Webhook::construct_event helper — verify HMAC-SHA256 + parse Event; KHÔNG manual implement HMAC (đỡ 2 class lỗi parse header + constant-time compare quên).
• 5 phút tolerance default — replay attack window; Stripe docs khuyến cáo 300 giây.
• 400 BadRequest cho signature fail — KHÔNG 401 (avoid leak info credential).
• Body MANDATORY String raw (KHÔNG Json<Value>) — re-serialize sẽ thay đổi byte order key → HMAC FAIL (lock B37 continued).
• Idempotent webhook handler dedup qua stripe_webhook_events.event_id PRIMARY KEY — UNIQUE auto race-safe.
• Stripe retry 3 days exponential nếu KHÔNG 2xx — handler MANDATORY idempotent (skip nếu event_id đã tồn tại).
• payment_payload @> JSONB query lock B60 continued cho find_by_intent_id + update_status_by_intent (jsonb_path_ops index O(log n) match).
• ON CONFLICT (order_id) DO UPDATE UPSERT lock B54 — 1 order = 1 payment, không duplicate row khi user click "Pay" 2 lần.
• 2 event handler initial: PaymentIntentSucceeded → orders.status = paid; PaymentIntentPaymentFailed → payment.status = failed; extend G14 thêm refund/dispute event.
• URL /webhooks/stripe NGOÀI /api/v1 — third-party convention KHÔNG version (Stripe gọi trực tiếp không biết version).
• Migration 14 stripe_webhook_events 7 column (event_id PK + event_type + received_at + processed_at + status enum 3 value + error_message + raw_payload JSONB) + 2 index audit trail.
• File path lock B71: NEW crates/shop-api/src/routes/payments.rs + extend crates/shop-db/src/payments.rs (3 function create_stripe_payment + update_status_by_intent + find_by_intent_id) + NEW migration 14 20260616130000_create_stripe_webhook_events.sql + UPDATED config.rs (2 field stripe_secret_key + stripe_webhook_secret) + UPDATED router.rs + routes/mod.rs + .env.example + workspace Cargo.toml.

Tự trả lời, đáp án ở cuối:

1. PaymentIntent flow vs Charge API cũ — pros của PaymentIntent cho SCA compliance? Tại sao Stripe trả client_secret thay vì server-side handle thẳng card data?
2. Webhook signature verify HMAC-SHA256 — pattern attack nếu KHÔNG check timestamp? Giải thích replay attack window 5 phút.
3. Idempotent webhook dedup event.id — Stripe retry policy 3 days exponential. Cho ví dụ scenario network blip + server timeout.
4. payment_payload @> JSONB query — pros so với column riêng payment_intent_id TEXT? Trade-off flexibility vs performance.
5. URL /webhooks/stripe không dưới /api/v1 — lý do tại sao? Third-party convention vs versioning REST resource.

Bài 72: Service Layer Abstraction — Trait Pattern — refactor business logic từ handler → service trait, dependency injection qua AppState, mock service cho test, áp Shop API ProductService + OrderService + PaymentService trait pattern.