# VKL Shield API

VKL Shield đứng trước thanh toán PayPal và Stripe cho các cửa hàng đối tác: trang của bạn nhúng một script, SDK hiển thị giao diện thanh toán, và bạn nhận lại bằng chứng ký Ed25519 ngay khi giao dịch hoàn tất — không cần chờ webhook trong luồng thành công.

v1 là API hiện hành, xác thực bằng key. Mọi request (trừ endpoint JWKS) đều mang tham số query `shield_key` theo dạng `shpk_live_…` / `shpk_test_…`. Phản hồi capture và completion là các envelope đã ký mà bạn xác minh dựa trên JWKS bên dưới.

## Bắt đầu nhanh

1. Yêu cầu key sandbox (`shpk_test_…`) từ đội vận hành VKL Shield.
2. Nhúng script SDK và gọi `init()` — xem [hướng dẫn PayPal SDK](/docs/v1/sdk/paypal) hoặc [hướng dẫn Stripe SDK](/docs/v1/sdk/stripe).
3. Tại `onCompleted`, xác minh envelope đã ký ở phía server dựa trên JWKS sandbox trước khi hoàn tất đơn hàng — xem [ví dụ verify-signed-payload](/docs/v1/examples/verify-signed-payload.mjs).
4. Khi checkout sandbox + xác minh hoạt động trọn vẹn, yêu cầu key live và chuyển host.

Đang chuyển từ API cũ (không có version)? Đọc [hướng dẫn chuyển đổi](/docs/v1/migration) trước — định dạng key, hình dạng payload callback, và cách xác minh bằng chứng đều đã thay đổi.

## Danh sách host

| Mục đích | Host |
|---|---|
| Shield API live (production) | `https://live.vkl-shield.com` |
| Shield API sandbox (testing) | `https://sandbox.vkl-shield.com` |
| JWKS — live | `https://keys.vkl-shield.com/v1/keys` |
| JWKS — sandbox | `https://keys.vkl-shield.com/sandbox/v1/keys` |

Một đối tác có thể được cấp một shield host riêng thay vì host dùng chung mặc định — nếu vậy, dùng host đó ở mọi nơi hướng dẫn này ghi `live.vkl-shield.com` / `sandbox.vkl-shield.com` (script `src`, `selectBase`). Host JWKS ở trên luôn là host chuẩn, bất kể request được phục vụ bởi shield host nào.

## v1 gồm những gì

- **PayPal** — checkout smart-buttons (render trang, tạo/capture order, chọn pool).
- **Stripe** — Express Checkout (Apple Pay / Google Pay) cùng checkout dạng card-form.
- **Keys** — JWKS Ed25519 để xác minh mọi envelope đã ký mà v1 trả về.

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 hoặc Stripe.

## Tiếp theo

- [Tài liệu API](/docs/v1) — mọi endpoint, tham số, và mã lỗi.
- [Hướng dẫn PayPal SDK](/docs/v1/sdk/paypal) · [Hướng dẫn Stripe SDK](/docs/v1/sdk/stripe)
- [Hướng dẫn chuyển đổi](/docs/v1/migration) — rời khỏi API cũ.
- [Nhật ký thay đổi](/docs/changelog)