Xem bản Markdown ↗

#Tích hợp PayPal Shield SDK

#Tổng quan v1

SDK JavaScript phía parent cho PayPal Smart Buttons. Store nhúng một script và gọi PaypalShield.init(config); SDK chọn một shield server, hiển thị các nút thanh toán trong một iframe do nó quản lý, và đưa ra toàn bộ chu trình thanh toán dưới dạng callback — store không cần viết code postMessage.

Không bao giờ nạp cả SDK legacy và v1 trên cùng một trang. Cả hai đều dùng biến global window.PaypalShield; hành vi không xác định và chỉ v1 cảnh báo trong console. Chỉ nạp một: chuyển đổi toàn bộ trang bằng cách cập nhật URL script, key shpk_, và server verifier cùng lúc.

#Bắt đầu nhanh

<div id="paypal-shield"></div>
<!-- Host mặc định: live.vkl-shield.com (production) / sandbox.vkl-shield.com (testing, minh họa dưới đây).
     Tham số ?domain= là tùy chọn (xem Pinned mode). Một đối tác có thể được cấp một
     shield host riêng — load script từ host đó (hoặc truyền selectBase) thay cho host mặc định. -->
<script src="https://sandbox.vkl-shield.com/assets/v1/paypal-shield-sdk.js"></script>
<script>
  var handle = PaypalShield.init({
    container: '#paypal-shield',
    shieldKey: 'shpk_test_xxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx',
    getOrderData: function (fundingSource) {
      return fetchYourOrderBody(fundingSource);
    },
    onCompleted: function (envelope, orderId) {
      // Xác minh envelope ở phía server trước khi hoàn tất đơn hàng
      console.log(envelope);
    }
  });
  // Re-init trong SPA: gọi handle.destroy() trước khi init() lại
</script>

#Pinned mode (tùy chọn)

Nếu store của bạn luôn phân giải tới một shield domain cố định (không xoay vòng pool), bạn có thể bỏ qua lời gọi /v1/shield/select bằng cách pin (cố định) domain:

<!-- Pinned mode: iframe dùng trực tiếp domain này, bỏ qua /v1/shield/select -->
<script src="https://live.vkl-shield.com/assets/v1/paypal-shield-sdk.js?domain=live.vkl-shield.com"></script>

Script bản thân nó vẫn được nạp từ shield trung tâm (mặc định live.vkl-shield.com / sandbox.vkl-shield.com, hoặc host riêng nếu được cấp); chỉ origin của iframe thay đổi. Config init không thay đổi.

Đánh đổi: Pinning cũng bỏ qua việc kiểm tra shield đang hoạt động (active-shield check). Nếu shield bị vô hiệu hóa, lỗi sẽ xuất hiện bên trong iframe tại /v1/create_order (sau khi người mua click) thay vì được phát hiện sớm qua onFailed({code: 'NO_POOL'}).

Dùng pinning khi: Store được phục vụ bởi đúng một shield và không có pool để xoay vòng.

KHÔNG pin khi: Store dùng một pool nhiều shield; việc pin sẽ vô hiệu hóa cơ chế xoay vòng pool và cố định mọi người mua vào một shield duy nhất.

#Tham chiếu các tùy chọn init

#Callback & event

#Sơ đồ chuỗi (sequence diagram)

sequenceDiagram
    participant Store as Store Page
    participant SDK as PaypalShield SDK
    participant Central as Central Shield
    participant ShieldServer as Shield Server
    participant PayPal as PayPal API

    Store->>SDK: init(config)
    SDK->>Central: GET /v1/shield/select?shield_key=...
    Central-->>SDK: {shield_domain}
    SDK->>SDK: Tạo iframe<br/>pin vào shield_domain
    
    Store->>SDK: (Người mua click nút)
    SDK->>ShieldServer: postMessage CHECKOUT_ORDER_DATA
    ShieldServer->>ShieldServer: onClicked → emit
    SDK-->>Store: onClicked(fundingSource)
    
    Store->>SDK: getOrderData(fundingSource)
    SDK->>ShieldServer: postMessage {id, body}
    ShieldServer->>PayPal: POST /v2/checkout/orders<br/>(OrdersCreateRequest)
    PayPal-->>ShieldServer: {id: order_id}
    
    ShieldServer->>ShieldServer: onCapturing → emit
    SDK-->>Store: onCapturing()
    
    ShieldServer->>PayPal: POST /v2/checkout/orders/{order_id}/capture<br/>(OrdersCaptureRequest)
    PayPal-->>ShieldServer: {id, status, purchase_units, ...}
    
    ShieldServer->>ShieldServer: Dựng envelope v1<br/>(ký bằng Ed25519)
    ShieldServer->>SDK: postMessage PAYPAL_PAYMENT_COMPLETED<br/>{signed_payload, sig, kid, alg, v, data}
    SDK-->>Store: onCompleted(envelope, orderId)
    
    Store->>Store: Xác minh sig qua JWKS<br/>(endpoint chuẩn)
    Store->>Store: Assert partner_id,<br/>invoice_id, iat
    Store->>Store: Hoàn tất đơn hàng,<br/>redirect

#Hợp đồng postMessage

#Envelope bằng chứng (chỉ v1)

Khi onCompleted được fire, bạn nhận một envelope bằng chứng đã ký:

{
  "error": false,
  "data": {
    "id": "5O190127TN364715T",
    "purchase_units": [
      {
        "reference_id": "partner-code-example",
        "payee": {
          "merchant_id": "MERCHANTEXAMPLE"
        },
        "payments": {
          "captures": [
            {
              "id": "3C679366HH908993F",
              "status": "COMPLETED",
              "amount": {
                "value": "19.99",
                "currency_code": "USD"
              },
              "invoice_id": "1001"
            }
          ]
        }
      }
    ]
  },
  "signed_payload": "{\"amount\":\"19.99\",\"capture_id\":\"3C679366HH908993F\",\"currency\":\"USD\",\"env\":\"sandbox\",\"iat\":1793500000,\"invoice_id\":\"1001\",\"key_id\":\"key_EXAMPLE000000000\",\"order_id\":\"5O190127TN364715T\",\"partner_id\":\"acme\",\"payee_merchant_id\":\"MERCHANTEXAMPLE\",\"reference_id\":\"partner-code-example\",\"shield\":\"shield-sandbox.example\",\"status\":\"COMPLETED\",\"store_domain\":\"store.example\",\"typ\":\"paypal_capture\",\"v\":1}",
  "sig": "S668XzUJHlMJirZWTW8CEwzjerdaKI6r8Qwtbo6EX7U2YzMMYX4sGWDdQxT3tPeo0ZCtzSV1t_PvBrDK-Wk9CA",
  "kid": "shsig_TESTVECTORPAYPAL00000000",
  "alg": "Ed25519",
  "v": 1
}

kid/sig ở trên lấy từ tests/fixtures/v1-ed25519-test-vector.json — một test vector mà private key của nó được công khai có chủ ý (có thể suy ra từ một seed label đã công bố) để đảm bảo tái lập được. kid này KHÔNG BAO GIỜ xuất hiện trong JWKS thật; không xử lý đặc biệt hoặc hardcode nó. Luôn resolve kid bằng cách tra cứu trong response từ JWKS URL CHUẨN (keys.vkl-shield.com) — không bao giờ pin việc xác minh vào một giá trị kid cụ thể.

Hướng dẫn các field:

Trong signed_payload (sau khi parse JSON):

Vì sao các kiểm tra này quan trọng:

• reference_id / invoice_id / amount / currency: Client cung cấp khi tạo đơn hàng; dễ bị giả mạo khi truyền nếu không được xác minh bằng mật mã học
• partner_id / env / typ: Do shield đóng dấu; chứng minh đối tác và môi trường nào đã phát hành bằng chứng này (ranh giới bảo mật)
• key_id ∈ allowedKeyIds: Bảo vệ việc định tuyến tiền giữa các pool của riêng bạn — một key bị lộ hoặc đã xoay vòng không được phép capture tiền

Bạn PHẢI xác minh sig dựa trên signed_payload ở phía server (dùng JWKS URL chuẩn, không bao giờ lấy từ envelope) trước khi tin tưởng bất kỳ field nào.

#Mã lỗi & cách xử lý

#Tham chiếu mã lỗi

Lỗi phía SDK (HTTP 200 với cờ error): Các lỗi này fire onFailed({code: '...', message?: string}) sau lời gọi select của SDK hoặc trong iframe.

Lỗi phía shield, theo bước thực sự sinh ra lỗi (fire từ iframe):

Đọc error.issue ?? error.code trong handler của bạn — lỗi select dùng code, lỗi capture dùng issue (hoặc là một PayPal SDK Error trần không có cả hai), không bao giờ có cả hai cùng lúc.

#CAPTURED_PROOF_UNAVAILABLE (502) — Xử lý đặc biệt

Lỗi này có nghĩa là người mua ĐÃ bị charge. Thanh toán đã thành công ở phía PayPal, nhưng bằng chứng v1 (chữ ký) không thể tạo được.

var captureStarted = false; // chuyển thành true khi onCapturing, reset mỗi lần thử mới

// onCapturing() fire ngay khi capture_order đang được chuẩn bị gọi (hook
// iframe post nó như điều ĐẦU TIÊN trong onApprove, trước khi fetch) — đây
// là ranh giới: trước nó, PayPal CHƯA được yêu cầu capture; sau nó, một lần
// thử capture đang diễn ra hoặc đã chạy xong. Reset ở đầu mỗi lần thử
// (onClicked) để lần thử thứ 2 sau một capture THẤT BẠI không còn bị đánh
// dấu "đã bắt đầu capture" từ lần thử đầu.
// onClicked: function () { captureStarted = false; },
// onCapturing: function () { captureStarted = true; },

onFailed: function (error) {
  var RETRYABLE_CAPTURE_ISSUES = ['RATE_LIMITED', 'TEMPORARILY_LOCKED', 'SIGNING_UNAVAILABLE',
    'SHIELD_REGISTRY_UNAVAILABLE', 'SHIELD_REGISTRY_STALE'];
  if (error.issue === 'CAPTURED_PROOF_UNAVAILABLE' ||
      (captureStarted && !error.details && !error.issue && !error.code)) {
    // (a) Lỗi tạo bằng chứng đã biết, HOẶC capture đã bắt đầu và lỗi này
    // không có hình dạng từ-chối của PayPal cũng không có BẤT KỲ issue/code
    // nào — trạng thái không xác định SAU KHI capture đã bắt đầu (ví dụ lỗi
    // network/parse giữa lời gọi capture và response của nó). Người mua có
    // thể đã bị charge; không bao giờ giả định điều ngược lại. Loại trừ
    // RETRYABLE_CAPTURE_ISSUES dưới đây: các lỗi đó mang `issue` và fire từ
    // ROUTE capture trước khi PayPal từng được gọi — chưa bị charge, dù
    // captureStarted là true.
    showMessage('Đã nhận thanh toán! Đang xác nhận đơn hàng của bạn...');

    // Đối soát qua webhook AIO transaction.completed, khớp theo settle_ref.
    // Backend của bạn sẽ nhận thông báo webhook trong vài phút.
    // KHÔNG BAO GIỜ retry capture.

  } else if (!captureStarted || Array.isArray(error.details) ||
             RETRYABLE_CAPTURE_ISSUES.indexOf(error.issue) !== -1 || error.code) {
    // (b) Chưa bị charge: hoặc capture chưa từng bắt đầu (create_order — một
    // `Error` trần của PayPal JS SDK, hoặc một `{issue}`/`{code}` phía
    // shield từ select/create), HOẶC một object từ-chối của PayPal
    // (`{details:[{issue}]}`) từ một capture THẤT BẠI, HOẶC một lỗi route
    // capture trước-PayPal (429/503 RETRYABLE_CAPTURE_ISSUES) chưa từng đến
    // PayPal.
    var reason = (Array.isArray(error.details) && error.details[0] && error.details[0].issue) || error.issue || error.code;
    showError('Thanh toán thất bại (' + reason + '). Vui lòng thử lại.');
  } else {
    // (c) captureStarted với một `error.issue` không phải
    // CAPTURED_PROOF_UNAVAILABLE cũng không phải một issue route-capture có
    // thể retry đã biết (ví dụ một chuỗi issue mới/chưa nhận diện) — trạng
    // thái charge KHÔNG XÁC ĐỊNH, không phải "chưa bị charge". KHÔNG bảo
    // người mua thử lại; xử lý giống như charged-but-unconfirmed cho đến khi
    // webhook đối soát xong.
    showMessage('Đang xác nhận đơn hàng của bạn...');
  }
}

Vì sao điều này xảy ra:

• Key ký đã hết hạn giữa lúc capture và lúc tạo bằng chứng
• Không có key hợp lệ nào đang hoạt động trên registry vào thời điểm capture
• Registry không truy cập được chính xác vào thời điểm cần tạo bằng chứng

Khôi phục:

• Người mua ĐÃ bị charge trên PayPal. Đối soát qua webhook AIO transaction.completed. AIO nhận các webhook từ nhà cung cấp PayPal/Stripe cho các tài khoản merchant của shield và thông báo cho platform của bạn (ký HMAC, header X-Signature: t=…,v1=…; endpoint, secret và hợp đồng payload do đội vận hành shield/AIO cấp). Khớp với đơn hàng của bạn bằng settle_ref bạn đã gửi (PayPal purchase_units[0].custom_id; Stripe: cùng custom_id trong getOrderData, lưu dưới dạng metadata PaymentIntent settle_ref). Chỉ đơn hàng KHÔNG có bằng chứng đã xác minh mới chờ webhook này (hiển thị đã nhận thanh toán, đang xác nhận); không bao giờ yêu cầu người mua trả tiền lại.
• Yêu cầu người mua liên hệ hỗ trợ nếu họ không thấy xác nhận trong vòng 10 phút

#Xác minh ở phía server

Mô hình xác nhận — bằng chứng (proof) là chính, AIO là fallback dự phòng.

1. Chính (đồng bộ): xác minh bằng chứng Ed25519 ở phía server ngay sau callback (trang này) → hoàn tất đơn hàng ngay và hiển thị trang cảm ơn. Không chờ bất kỳ webhook nào.
2. Fallback / đối soát: webhook AIO transaction.completed (ký HMAC X-Signature: t=…,v1=…, khớp theo settle_ref = custom_id của bạn) hoàn tất các đơn hàng mà bằng chứng chưa từng đến — PayPal CAPTURED_PROOF_UNAVAILABLE, Stripe charged_but_unconfirmed, hoặc người mua đã đóng tab — và có thể dùng để đối soát sau. Nó phải idempotent (lặp lại an toàn) với bước 1 (một đơn hàng đã hoàn tất từ bằng chứng thì webhook này là no-op). Không bao giờ charge người mua lần nữa khi đơn hàng đang chờ fallback.

Xem docs/api/examples/ để có mẫu hoạt động đầy đủ:

• Node.js (verify-signed-payload.mjs) — Khuyến nghị dùng; hỗ trợ Ed25519 đầy đủ
• PHP (verify-signed-payload.php) — Dùng sodium_crypto_sign_verify_detached()
• Python (verify-signed-payload.py) — Dùng thư viện cryptography

#Checklist xác minh

Để có cách triển khai tham chiếu đầy đủ (Node.js, PHP, Python), xem docs/api/examples/verify-signed-payload.mjs.

Các điểm quan trọng khi xác minh:

1. Chỉ fetch JWKS từ URL chuẩn (không bao giờ lấy từ envelope). Dùng URL đã cấu hình ở backend của bạn:

   const CANONICAL_JWKS_URL = {
     live: 'https://keys.vkl-shield.com/v1/keys',
     sandbox: 'https://keys.vkl-shield.com/sandbox/v1/keys'
   };
   const jwksUrl = CANONICAL_JWKS_URL[expectedEnv]; // set before calling onCompleted

2. Xác minh chữ ký TRƯỚC khi parse — xác minh dựa trên các byte UTF-8 chính xác của signed_payload:

   const publicKey = crypto.createPublicKey({
     key: {kty: 'OKP', crv: 'Ed25519', x: jwk.x}, // định dạng JWK OKP Ed25519
     format: 'jwk'
   });
   const verified = crypto.verify(
     null,
     Buffer.from(envelope.signed_payload, 'utf8'),
     publicKey,
     Buffer.from(envelope.sig, 'base64url')
   );

3. Sau khi chữ ký hợp lệ, parse và assert các claim:

   const payload = JSON.parse(envelope.signed_payload);
   
   // Assert các ranh giới bảo mật bất biến
   assert(payload.typ === 'paypal_capture');
   assert(payload.status === 'COMPLETED');
   assert(payload.env === 'live'); // hoặc 'sandbox' trên sandbox
   assert(payload.partner_id === YOUR_PARTNER_ID);
   assert(YOUR_APPROVED_KEYS.includes(payload.key_id));
   
   // Assert các field client cung cấp (ràng buộc tiền)
   assert(payload.invoice_id === your_order.invoice_id);
   assert(payload.amount === your_order.total); // chuỗi decimal
   assert(payload.currency === your_order.currency);
   
   // Assert độ mới của timestamp
   const now = Math.floor(Date.now() / 1000);
   assert(payload.iat >= now - 600 && payload.iat <= now + 300);
   
   // Assert chống replay (tùy chọn nhưng khuyến nghị)
   assert(!hasBeenSeen(payload.capture_id));
   recordCapture(payload.capture_id);

#Cache & xoay vòng JWKS

Endpoint JWKS chuẩn phục vụ các public key dùng để xác minh chữ ký. Tuân theo các quy tắc sau:

Fetch JWKS từ:

• Live: https://keys.vkl-shield.com/v1/keys
• Sandbox: https://keys.vkl-shield.com/sandbox/v1/keys

Chiến lược cache:

• Xác minh chữ ký, sau đó kiểm tra kid có trong cache không; chỉ refetch JWKS nếu chưa biết
• Tuân theo header Cache-Control: max-age=600 (thường là 10 phút; cache theo cặp (url, kid))
• Nếu không tìm thấy key ID (kid) trong cache, refetch JWKS ngay (có rate-limit: tối đa 1 lần/phút cho mỗi JWKS URL)
• Loại bỏ các key ID không xác định; không bao giờ tin tưởng một kid nằm ngoài JWKS

Vòng đời key:

• Key đối tác (shpk_): hết hạn cứng sau 180 ngày; key hết hạn trả về 401 SHIELD_KEY_EXPIRED khi select
• Key ký (xuất bản lên JWKS):
  • Được xuất bản ≥7 ngày trước khi kích hoạt (không cần rollover gấp — bạn có một tuần)
  • Được giữ trong JWKS 30 ngày sau khi ngừng dùng
  • JWKS max-age=600 (10 phút), nên đối tác cache theo (url, kid) và refetch các kid chưa biết
• Xoay key đối tác: Thêm key id mới vào allowlist trong config shield trước (không cần deploy), chuyển key SDK, chờ TTL cache trang + 10 phút, xóa key id cũ
• Nếu không xoay key: Sau khi key đối tác hết hạn, mọi lời gọi select trả về 401 SHIELD_KEY_EXPIRED

#Test trên sandbox

Dùng key bắt đầu bằng shpk_test_:

shieldKey: 'shpk_test_xxxxxxxxxxxxxxxxxxxxxxxx_xxxxxx'

Fetch JWKS từ: https://keys.vkl-shield.com/sandbox/v1/keys

#Checklist go-live

• Đã yêu cầu key live từ đội vận hành shield (key đối tác do đội vận hành shield cấp)
• Code verifier đã deploy và test dựa trên endpoint JWKS live
• Đã test với key shpk_live_* trên staging
• Đã xử lý lỗi CAPTURED_PROOF_UNAVAILABLE (502)
• Endpoint webhook AIO transaction.completed đã cấu hình và xác minh; mọi đơn hàng đều gửi settle_ref trong custom_id

#Khắc phục sự cố

Các nút không hiển thị

• Kiểm tra URL script SDK (phải là đường dẫn v1)
• Xác minh định dạng và scope của shield_key
• Kiểm tra console trình duyệt để tìm lỗi xác minh origin

Thanh toán thất bại với NO_POOL

• Pinned mode hoặc tất cả shield đã bị vô hiệu hóa
• Kiểm tra trạng thái pool trong dashboard

Xác minh bằng chứng thất bại

• Đảm bảo JWKS được fetch từ URL chuẩn
• Xác minh các byte signed_payload khớp chính xác (encoding quan trọng)
• Kiểm tra kid có tồn tại trong JWKS hiện tại