VKL Shield Tài liệu API

Xem bản Markdown ↗

PayPal

Checkout smart-buttons PayPal (render trang, tạo/capture order, chọn pool)

GET /v1/

Trang iframe smart-buttons PayPal

Render trang HTML mà iframe do SDK quản lý sẽ load (src của iframe trong PaypalShield.init). Kiểm tra origin qua Referer khi key có cấu hình allowedOrigins (chống hotlink, không phải ranh giới xác thực). Bị chặn bởi pool guard (POOL_MISMATCH nếu pool của key không bao gồm host này).

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ọnslug định tuyến pool tùy chọn (hỗ trợ nhiều slug phân tách bằng dấu |)

Phản hồi

200

trang HTML

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
500

Lỗi server nội bộ — {error:string} trần, không có data

LegacyStringError
503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error) HOẶC shield chưa được cấu hình secret (hình dạng LegacyStringError, không có data).

một trong:

Mã lỗi đầy đủ

GET /v1/card-fields

Trang iframe card-fields nâng cao của PayPal

Chặn giống /v1/; render trang biến thể card-fields.

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.

Phản hồi

200

trang HTML

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
500

Lỗi server nội bộ — {error:string} trần, không có data

LegacyStringError
503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error) HOẶC shield chưa được cấu hình (hình dạng LegacyStringError, không có data).

một trong:

Mã lỗi đầy đủ

POST /v1/create_order

Tạo một đơn hàng PayPal

Kiểm tra origin qua sec-fetch-or-origin khi key có cấu hình allowedOrigins. Được gọi từ bên trong iframe của SDK (cùng origin với shield domain đã chọn).

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ả
dataobjectbắt buộc

body đơn hàng dạng PayPal (purchase_units[0].amount/invoice_id/reference_id, …)

store_domainstring | nulltùy chọn
fraudnet_sessionstring | nulltùy chọn

Phản hồi

200

đơn hàng đã được tạo

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

INVALID_SHIPPING_ADDRESS | INVALID_EMAIL | INVALID_ORDER

LegacyControllerError
401

lỗi xác thực key (V1Error) HOẶC tổng đơn hàng vượt MAX_ORDER_AMOUNT (body rỗng, res.status(401).send() — cùng mức giới hạn mà PayPal/Stripe chia sẻ; phân biệt bằng body RỖNG so với body JSON V1Error).

V1Error
403

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

V1Error
429

RATE_LIMITED | TEMPORARILY_LOCKED (giới hạn tốc độ thanh toán theo IP dùng chung)

LegacyControllerError
500

Chuyển tiếp lỗi API PayPal nguyên bản — data là JSON lỗi gốc đã parse của PayPal, không phải hình dạng {issue,...} — HOẶC "Internal server error" (hình dạng LegacyStringError, không có data).

một trong:

503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error) HOẶC shield chưa được cấu hình (hình dạng LegacyStringError, không có data).

một trong:

Mã lỗi đầy đủ

POST /v1/capture_order

Capture một đơn hàng PayPal và nhận envelope đã ký

Không kiểm tra origin (ràng buộc thực hiện lúc tạo order thông qua ràng buộc capture-key hậu-charge). Khi thành công trả về một SignedEnvelope mà data mang kết quả capture gốc của PayPal và signed_payload parse ra PaypalCaptureV1Payload. Bằng chứng đã ký là đường hoàn tất CHÍNH (store hoàn tất ngay, không chờ webhook). Một capture THÀNH CÔNG (tiền đã chuyển) nhưng không thể ký trả về 502 CAPTURED_PROOF_UNAVAILABLE: 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.

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ả
capture_idstringbắt buộc

id đơn hàng PayPal trả về từ create_order

order_idstring | nulltùy chọn

id đơn hàng của store

store_domainstring | nulltùy chọn
fraudnet_sessionstring | nulltùy chọn
client_staticobject | nulltùy chọn
payment_sourcestring | nulltùy chọn

paypal | card | googlepay | applepay | venmo | paylater | credit

Phản hồi

200

đã capture — envelope đã ký

SignedEnvelope
400

capture_id/order_id thiếu hoặc không an toàn — data ở đây là một STRING thuần (ví dụ "Capture ID is required"), không phải object {issue,...} (validate trước khi gọi PayPal trên route này).

trườngkiểumô tả
errorbooleanbắt buộc
datastringbắt buộc
401

lỗi xác thực key (V1Error) HOẶC gate fraud blocklist đã từ chối capture này (body rỗng, res.status(401).send() — không lộ lý do cho client; phân biệt bằng body RỖNG so với JSON V1Error).

V1Error
403

SCOPE_DENIED | POOL_MISMATCH (cố gắng capture bằng key khác). LƯU Ý: /v1/capture_order không kiểm tra origin — ràng buộc origin được thực hiện lúc tạo order — nên ORIGIN_NOT_ALLOWED không bao giờ xảy ra ở route này dù nó có trong danh sách issue chung của ForbiddenError.

V1Error
429

RATE_LIMITED | TEMPORARILY_LOCKED (giới hạn tốc độ thanh toán theo IP dùng chung)

LegacyControllerError
500

Chuyển tiếp lỗi API PayPal nguyên bản — data là JSON lỗi gốc đã parse của PayPal, không phải hình dạng {issue,...} — HOẶC "Internal server error" (hình dạng LegacyStringError, không có data).

một trong:

502

CAPTURED_PROOF_UNAVAILABLE — 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.

V1Error
503

SHIELD_REGISTRY_UNAVAILABLE | SHIELD_REGISTRY_STALE | SHIELD_ENV_MISCONFIGURED | PAYMENT_ENV_MISMATCH | SIGNING_UNAVAILABLE (hình dạng V1Error) HOẶC shield chưa được cấu hình (hình dạng LegacyStringError, không có data).

một trong:

Mã lỗi đầy đủ

GET /v1/shield/select

Chọn một shield PayPal từ pool của key

Được gọi bởi PaypalShield.init trước khi mount iframe (bỏ qua khi script SDK mang pin ?domain=). 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 (selector chung không bao giờ phát ra chuỗi đó; nó được dành riêng cho việc phân loại network/timeout của SDK trên lời gọi này), được giữ trong enum V1Issue chung cho các caller muốn một tập hợp đóng duy nhất trên cả hai lớp.

một trong:

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 đủ