# VKL Shield API — v1

v1 là API shield xác thực bằng key, ký bằng Ed25519. Mọi request (trừ JWKS) đều mang `?shield_key=` (định dạng `shpk_live_…` / `shpk_test_…`). Response capture/complete là các envelope đã ký có thể xác minh dựa trên JWKS bên dưới — xem `/v1/keys`. Các route chỉ dành cho wallet trong API cũ không còn trong v1; dùng trực tiếp route PayPal/Stripe.

Đặc tả đầy đủ (máy đọc được): [openapi.json](/docs/v1/openapi.json) · [openapi.yaml](/docs/v1/openapi.yaml)

## Host

- `https://live.vkl-shield.com` — shield host live mặc định (production). Một đối tác có thể được cấp một shield host riêng — truyền nó làm `selectBase` của SDK (hoặc load script SDK từ host đó) thay cho host mặc định này.
- `https://sandbox.vkl-shield.com` — shield host sandbox mặc định (testing). Áp dụng cùng cơ chế ghi đè host riêng như trên host live mặc định.
- `https://keys.vkl-shield.com` — host JWKS chuẩn (live); sandbox là https://keys.vkl-shield.com/sandbox — luôn dùng host này cho JWKS bất kể request được phục vụ bởi shield host nào (mặc định hoặc riêng)

## PayPal

Xem đầy đủ: [/docs/v1/paypal/](/docs/v1/paypal/)

- **GET** `/v1/` — Trang iframe smart-buttons PayPal
- **GET** `/v1/card-fields` — Trang iframe card-fields nâng cao của PayPal
- **POST** `/v1/create_order` — Tạo một đơn hàng PayPal
- **POST** `/v1/capture_order` — Capture một đơn hàng PayPal và nhận envelope đã ký
- **GET** `/v1/shield/select` — Chọn một shield PayPal từ pool của key

## Stripe

Xem đầy đủ: [/docs/v1/stripe/](/docs/v1/stripe/)

- **GET** `/v1/stripe/select` — Chọn một shield Stripe + publishable key từ pool của key
- **POST** `/v1/stripe/create-intent` — Tạo một PaymentIntent Stripe (deferred-intent cho wallet hoặc card-form)
- **POST** `/v1/stripe/complete` — Xác nhận một PaymentIntent đã thành công và nhận envelope đã ký
- **POST** `/v1/wallet_beacon` — Telemetry phía client theo kiểu best-effort (không bao giờ chặn checkout)

## Keys (JWKS)

Xem đầy đủ: [/docs/v1/keys/](/docs/v1/keys/)

- **GET** `/v1/keys` — Lấy JWKS Ed25519 hiện tại

## Thêm

- [Schema](/docs/v1/schemas/)
- [Mã lỗi](/docs/v1/errors/)
- [OpenAPI](/docs/v1/openapi/)