VKL Shield Tài liệu API

Xem bản Markdown ↗

Stripe

Stripe Express Checkout (wallet) + checkout dạng card-form (select, create-intent, complete)

GET /v1/stripe/select

Chọn một shield Stripe + publishable key từ pool của key

Được gọi bởi StripeShield.init trước khi mount wallet/card form. Kiểm tra origin qua Origin khi key có cấu hình allowedOrigins.

Tham số

tênvị tríkiểumô tả
shield_keyquerystringbắt buộcshield key v1 của đối tác; bắt buộc trên mọi route trừ /v1/keys. Phân đoạn key là live hoặc test; test tương ứng với môi trường sandbox ở mọi nơi khác trong spec này (các field env, SHIELD_KEY_ENV_MISMATCH) — live/test chỉ là quy ước đặt tên key, không phải một bộ giá trị môi trường khác. 6 ký tự cuối là checksum trên toàn bộ phần trước nó — một key sai checksum hoặc sai định dạng đều bị từ chối ngay, không cần tra cứu thêm.
slugquerystringtùy chọn

Phản hồi

200

kết quả chọn pool khi thành công. Với NO_ACTIVE/NO_POOL/SELECT_FAILED (nhánh JSON pool-select chung không set status, nên Express mặc định về 200) đây thay vào đó là một LegacyControllerError — error:true với data.issue là một trong ba mã đó. SELECT_FAILED là một quy ước phía SDK, không do selector chung phát ra (xem ghi chú tương tự của /v1/shield/select).

một trong:

    • error boolean tùy chọn
    • data object tùy chọn
      • shield_domain string tùy chọn
      • publishable_key string tùy chọn
      • card_enabled boolean tùy chọn
      • form_methods array tùy chọn

        mảng gồm:

  • LegacyControllerError
401

SHIELD_KEY_INVALID | SHIELD_KEY_ENV_MISMATCH | SHIELD_KEY_REVOKED | SHIELD_KEY_EXPIRED (hình dạng V1Error).

V1Error
403

SCOPE_DENIED | ORIGIN_NOT_ALLOWED | POOL_MISMATCH (hình dạng V1Error).

V1Error
404

NOT_FOUND (đường bị chặn wallet) | INVALID_SHIELD_KEY (/v1/shield/select, /v1/stripe/select) — body inline thuần, không bao giờ có message/docs (hình dạng LegacyControllerError). KHÔNG THỂ XẢY RA trên v1 — lỗi 404 này chỉ fire trên API cũ (không-v1). Được ghi lại ở đây chỉ để đầy đủ/tương thích với API cũ. Một path sai chữ hoa/thường hoặc có dấu gạch chéo cuối trên route v1 thay vào đó sẽ rơi vào 404 mặc định (HTML, ngoài spec này) vì router v1 xử lý đường dẫn nghiêm ngặt — không theo hình dạng JSON này.

LegacyControllerError
503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error).

V1Error

Mã lỗi đầy đủ

POST /v1/stripe/create-intent

Tạo một PaymentIntent Stripe (deferred-intent cho wallet hoặc card-form)

Kiểm tra origin qua Origin khi key có cấu hình allowedOrigins. publishable_key (từ /v1/stripe/select) định tuyến request tới đúng tài khoản Stripe và phải thuộc cùng pool với shield_key được trình (nếu không sẽ trả 403 PK_POOL_MISMATCH).

Tham số

tênvị tríkiểumô tả
shield_keyquerystringbắt buộcshield key v1 của đối tác; bắt buộc trên mọi route trừ /v1/keys. Phân đoạn key là live hoặc test; test tương ứng với môi trường sandbox ở mọi nơi khác trong spec này (các field env, SHIELD_KEY_ENV_MISMATCH) — live/test chỉ là quy ước đặt tên key, không phải một bộ giá trị môi trường khác. 6 ký tự cuối là checksum trên toàn bộ phần trước nó — một key sai checksum hoặc sai định dạng đều bị từ chối ngay, không cần tra cứu thêm.

Nội dung yêu cầu

trườngkiểumô tả
order_dataobjectbắt buộc

body đơn hàng dạng PayPal

contactobject | nulltùy chọn
wallet_typestring | nulltùy chọn
channelstring | nulltùy chọn
client_form_methodsarray | nulltùy chọn
publishable_keystringbắt buộc
store_domainstring | nulltùy chọn
store_order_idstring | nulltùy chọn

Phản hồi

200

intent đã được tạo

trườngkiểumô tả
errorbooleantùy chọn
dataobjecttùy chọn
  • id string tùy chọn
  • client_secret string tùy chọn
400

INVALID_ORDER | INVALID_EMAIL | INVALID_PHONE | INVALID_SHIPPING_ADDRESS | NO_METHOD_FOR_AMOUNT (hình dạng LegacyControllerError) HOẶC MISSING_PK | UNKNOWN_PK khi publishable_key không xác định được (hình dạng LegacyGateError — {error:"Why you do that?"} trần, không có data/issue nào cả).

một trong:

401

lỗi xác thực key (V1Error) HOẶC tổng đơn hàng vượt MAX_ORDER_AMOUNT (body rỗng).

V1Error
403

ORIGIN_NOT_ALLOWED (hình dạng V1Error) | PK_POOL_MISMATCH khi publishable_key không cùng pool với shield_key (hình dạng LegacyGateError — {error:"Why you do that?"} trần).

một trong:

404

CHỈ LEGACY — shield_key thiếu/không hợp lệ, body rỗng. KHÔNG thể xảy ra trên v1 (xem ghi chú của NotFoundError); được ghi lại để tương thích với API cũ.

429

RATE_LIMITED | TEMPORARILY_LOCKED (giới hạn tốc độ thanh toán theo IP dùng chung, hoặc giới hạn riêng cho card-form theo IP mỗi giờ) — cùng hình dạng LegacyControllerError

LegacyControllerError
500

Chuyển tiếp lỗi API Stripe nguyên bản — issue = error.code của Stripe khi Stripe cung cấp, nếu không là chuỗi literal STRIPE_ERROR; KHÔNG phải enum đóng cho response này (xem StripeErrorPassthrough) — HOẶC "Shield misconfigured" (lệch chế độ key pk/sk của Stripe) | "Internal server error" (hình dạng LegacyStringError, không có data).

một trong:

503

PAYMENT_ENV_MISMATCH | SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE

V1Error

Mã lỗi đầy đủ

POST /v1/stripe/complete

Xác nhận một PaymentIntent đã thành công và nhận envelope đã ký

Không kiểm tra origin (ràng buộc qua metadata lúc create-time của chính PaymentIntent thay vào đó). Bằng chứng đã ký là đường hoàn tất CHÍNH (store hoàn tất ngay, không chờ webhook). Chính sách retry (SDK): lỗi network và 502/503/504 với issue ∈ {SIGNING_UNAVAILABLE, SHIELD_REGISTRY_UNAVAILABLE, SHIELD_REGISTRY_STALE} (hoặc không có issue) được retry tối đa 3 lần với backoff 1s/3s/9s — mọi mã khác là cuối cùng (terminal). Khi hết lượt retry hoặc một lỗi cuối cùng xảy ra sau một lần charge đã xác nhận, SDK hiển thị charged_but_unconfirmed: người mua đã bị charge; không retry hay hiển thị lỗi — đơn hàng được hoàn tất bởi webhook AIO transaction.completed (khớp theo settle_ref) như đường fallback. Một key đã hết hạn/bị thu hồi giữa create-intent và complete vẫn được ủy quyền nếu nó đang hoạt động lúc create-time (grace hậu-charge). Khi thành công trả về một SignedEnvelope mà signed_payload parse ra StripeCompleteV1Payload, cùng với một field contact không được ký.

Tham số

tênvị tríkiểumô tả
shield_keyquerystringbắt buộcshield key v1 của đối tác; bắt buộc trên mọi route trừ /v1/keys. Phân đoạn key là live hoặc test; test tương ứng với môi trường sandbox ở mọi nơi khác trong spec này (các field env, SHIELD_KEY_ENV_MISMATCH) — live/test chỉ là quy ước đặt tên key, không phải một bộ giá trị môi trường khác. 6 ký tự cuối là checksum trên toàn bộ phần trước nó — một key sai checksum hoặc sai định dạng đều bị từ chối ngay, không cần tra cứu thêm.

Nội dung yêu cầu

trườngkiểumô tả
payment_intent_idstringbắt buộc
wallet_typestring | nulltùy chọn
publishable_keystringbắt buộc
store_domainstring | nulltùy chọn
store_order_idstring | nulltùy chọn
client_staticobject | nulltùy chọn

Phản hồi

200

đã hoàn tất — envelope đã ký

SignedEnvelope
400

payment_intent_id thiếu hoặc không phải id pi_… an toàn — data ở đây là một STRING thuần (ví dụ "Invalid payment_intent_id"), không phải object {issue,...} — HOẶC MISSING_PK | UNKNOWN_PK khi publishable_key không xác định được (hình dạng LegacyGateError — {error:"Why you do that?"} trần, không có data/issue nào cả).

một trong:

401

lỗi xác thực key, bao gồm cả việc một key đã hết hạn/thu hồi ngoài khoảng ân hạn hậu-charge bị từ chối bằng SHIELD_KEY_REVOKED/SHIELD_KEY_EXPIRED.

V1Error
403

SCOPE_DENIED | POOL_MISMATCH (PaymentIntent thuộc key khác, hình dạng V1Error) | WALLET_REQUIRED (hình dạng LegacyControllerError) | PK_POOL_MISMATCH khi publishable_key không cùng pool với shield_key (hình dạng LegacyGateError — {error:"Why you do that?"} trần).

một trong:

404

CHỈ LEGACY — shield_key thiếu/không hợp lệ (ngoài khoảng ân hạn hậu-charge), body rỗng. KHÔNG thể xảy ra trên v1 — xem ghi chú của NotFoundError.

409

NOT_SUCCEEDED (mang data.status = trạng thái Stripe của PI) | ALREADY_COMPLETED (chỉ API cũ — v1 phát lại một envelope mới khi replay thay vì trả 409) | AMOUNT_MISMATCH

LegacyControllerError
500

Chuyển tiếp lỗi API Stripe nguyên bản (route này không bao giờ trả 502 — CAPTURED_PROOF_UNAVAILABLE chỉ dành cho PayPal); issue = error.code của Stripe khi có, nếu không là STRIPE_ERROR — KHÔNG phải enum đóng cho response này (xem StripeErrorPassthrough) — HOẶC "Shield misconfigured" (lệch chế độ key pk/sk của Stripe) | "Internal server error" (hình dạng LegacyStringError, không có data).

một trong:

503

SIGNING_UNAVAILABLE | SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE (SDK tự retry, xem ghi chú retry của x-sdk.stripe) | PAYMENT_ENV_MISMATCH (KHÔNG được SDK retry — lệch cuối cùng giữa env của key và livemode của PaymentIntent).

V1Error

Mã lỗi đầy đủ

POST /v1/wallet_beacon

Telemetry phía client theo kiểu best-effort (không bao giờ chặn checkout)

Kiểm tra origin qua Origin khi key có cấu hình allowedOrigins. Fire-and-forget từ SDK (navigator.sendBeacon hoặc fetch(..., {keepalive:true})); lỗi ở đây không bao giờ hiển thị cho người mua.

Tham số

tênvị tríkiểumô tả
shield_keyquerystringbắt buộcshield key v1 của đối tác; bắt buộc trên mọi route trừ /v1/keys. Phân đoạn key là live hoặc test; test tương ứng với môi trường sandbox ở mọi nơi khác trong spec này (các field env, SHIELD_KEY_ENV_MISMATCH) — live/test chỉ là quy ước đặt tên key, không phải một bộ giá trị môi trường khác. 6 ký tự cuối là checksum trên toàn bộ phần trước nó — một key sai checksum hoặc sai định dạng đều bị từ chối ngay, không cần tra cứu thêm.

Nội dung yêu cầu

trườngkiểumô tả
sourcestringtùy chọn
storestringtùy chọn
stagestringtùy chọn
detailstring | nulltùy chọn

Phản hồi

204

đã nhận — body rỗng; SDK bỏ qua body

401

SHIELD_KEY_INVALID | SHIELD_KEY_ENV_MISMATCH | SHIELD_KEY_REVOKED | SHIELD_KEY_EXPIRED (hình dạng V1Error).

V1Error
403

SCOPE_DENIED | ORIGIN_NOT_ALLOWED | POOL_MISMATCH (hình dạng V1Error).

V1Error
503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error).

V1Error

Mã lỗi đầy đủ