Trình mô phỏng Webhooks của PayPal có thể gửi tới máy chủ cục bộ không?

Không trực tiếp. Hiển thị tuyến webhook cục bộ của bạn bằng đường hầm HTTPS công khai, sau đó nhập URL HTTPS đó vào trình mô phỏng. PayPal yêu cầu một người nghe có thể tiếp cận qua internet.

Tại sao việc xác minh chữ ký PayPal không thành công đối với sự kiện mô phỏng?

Không thể đăng các sự kiện giả lập lên điểm cuối chữ ký xác minh-webhook của PayPal. Tài liệu PayPal WEBHOOK_ID để tự xác minh chữ ký mô phỏng; sử dụng sự kiện ứng dụng Sandbox thực để kiểm tra xác minh đăng lại.

Sự khác biệt giữa PayPal Sandbox và webhook giả lập là gì?

Webhook của trình mô phỏng là các tải trọng mô phỏng, độc lập với ứng dụng để kiểm tra người nghe. Webhook của ứng dụng Sandbox là kết quả của hoạt động Sandbox, sử dụng ID webhook thực của ứng dụng, xuất hiện trong công cụ sự kiện của ứng dụng và hỗ trợ quy trình xác minh thông thường.

Webhook PayPal sẽ trả về trạng thái HTTP nào?

Trả về phản hồi 2xx sau khi sự kiện được xác minh và được chấp nhận lâu dài. Từ chối các chữ ký không hợp lệ và chuyển công việc thực hiện chậm hoặc thông báo vào hàng đợi để việc phân phối không bị hết thời gian.

Kiểm thử webhook PayPal Sandbox trên localhost

Để kiểm tra webhooks PayPal Sandbox trên máy chủ cục bộ, hãy chạy trình nghe cục bộ, hiển thị lộ trình của nó thông qua đường hầm HTTPS công cộng, đăng ký URL đó trên ứng dụng Sandbox và kích hoạt giao dịch Sandbox thực hoặc sự kiện mô phỏng trong Trình mô phỏng Webhooks của PayPal. Luôn bật xác minh chữ ký: các sự kiện trình mô phỏng và các sự kiện Sandbox liên quan đến ứng dụng có một sự khác biệt quan trọng trong quá trình xác minh được giải thích bên dưới.

Tại sao PayPal không thể gửi trực tiếp tới localhost

PayPal gửi thông báo webhook từ máy chủ của chính nó. Một địa chỉ như http://localhost:3000/api/paypal trỏ đến máy của PayPal theo quan điểm của PayPal chứ không phải của bạn. localhost đường hầm cung cấp cho quy trình cục bộ một địa chỉ HTTPS công khai trong khi thoát khỏi ứng dụng trên máy tính của bạn.

Tài liệu chính thức PayPal Webhooks Simulator cho biết trình nghe của nó phải có thể truy cập được qua HTTPS trên cổng 443. Một đường hầm xử lý điểm cuối TLS công cộng đó và chuyển tiếp yêu cầu tới bất kỳ cổng cục bộ nào, chẳng hạn như 3000 hoặc 8080.

Chọn đường dẫn kiểm tra PayPal phù hợp

Sự kiện giả lập để phát triển trình nghe

Trình mô phỏng có thể gửi các sự kiện đại diện, bao gồm thu hồi thanh toán, hoàn tiền và sự kiện thanh toán mà không cần tạo giao dịch. Đây là cách nhanh nhất để xác nhận việc định tuyến, phân tích cú pháp JSON, mã phản hồi và gửi sự kiện. Các sự kiện mô phỏng không được liên kết với ứng dụng REST, không xuất hiện trong trình xem sự kiện webhook của ứng dụng, không thể gửi lại và không thể hiện các giao dịch thực.

Sự kiện Sandbox thực cho hành vi từ đầu đến cuối

Để tích hợp thực tế, hãy tạo ứng dụng REST trong Trang tổng quan dành cho nhà phát triển PayPal, thêm điểm cuối đường hầm dưới dạng webhook, chọn loại sự kiện bắt buộc và hoàn tất quy trình kiểm tra Sandbox hoặc thao tác API. Những sự kiện đó thuộc về ứng dụng Sandbox và sử dụng cùng thông tin xác thực ứng dụng, ID webhook, trình xem sự kiện và quy trình gửi lại mà bạn sẽ sử dụng trước khi sản xuất.

Thiết lập webhook PayPal trên localhost

Bắt đầu ứng dụng của bạn và xác nhận tuyến đường hoạt động cục bộ: curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'.
Chạy npx portpreview 3000 và sao chép URL HTTPS đã tạo.
Tạo lệnh gọi lại đầy đủ, ví dụ https://your-subdomain.portpreview.dev/api/webhooks/paypal.
Để thử nghiệm mô phỏng, hãy dán mô hình đó vào Trình mô phỏng Webhooks và chọn một sự kiện. Để thử nghiệm ứng dụng, hãy thêm nó vào phần cài đặt webhook của ứng dụng REST Sandbox của bạn.
Gửi sự kiện và kiểm tra phương thức đến, tiêu đề PayPal, nội dung thô, nhật ký trình xử lý và phản hồi HTTP.

Chỉ đăng ký các sự kiện mà ứng dụng của bạn xử lý. Đăng ký rộng rãi sẽ tạo ra tiếng ồn và khiến việc vô tình chạy logic kinh doanh cho một sự kiện mà bạn chưa từng lập mô hình trở nên dễ dàng hơn.

A practical Express listener

import express from 'express';

const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
  req.rawBody = Buffer.from(buf);
}}));

app.post('/api/webhooks/paypal', async (req, res) => {
  const event = req.body;

  // Verify first; do not fulfill an order from untrusted JSON.
  const verified = await verifyPayPal(req.headers, event);
  if (!verified) return res.status(401).send('invalid signature');

  // Claim the event ID atomically so retries cannot duplicate work.
  const firstDelivery = await claimEvent(event.id);
  if (!firstDelivery) return res.sendStatus(200);

  if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
    await markOrderPaid(event.resource.id);
  }

  return res.sendStatus(200);
});

app.listen(3000);

Giữ công việc xác nhận ngắn gọn. Lưu trữ sự kiện, trả về phản hồi 2xx và thực hiện công việc gửi email hoặc xử lý đơn hàng chậm trong hàng đợi. ID sự kiện là khóa bình thường tự nhiên; thực thi ràng buộc cơ sở dữ liệu duy nhất thay vì dựa vào bộ nhớ trong.

Xác minh chính xác chữ ký PayPal

PayPal gửi siêu dữ liệu truyền trong các tiêu đề bao gồm PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG và PAYPAL-TRANSMISSION-TIME. Đối với các sự kiện liên quan đến ứng dụng, bạn có thể gửi các giá trị đó, ID webhook và sự kiện tới API Sandbox /v1/notifications/verify-webhook-signature. Phản hồi HTTP thành công là chưa đủ; yêu cầu verification_status bằng SUCCESS. PayPal cũng ghi lại quá trình xác minh mật mã cục bộ trong hướng dẫn tích hợp webhook.

Cảnh báo về trình mô phỏng: Điểm cuối xác minh đăng lại của PayPal không hỗ trợ các sự kiện mô phỏng. PayPal ghi lại ID webhook theo nghĩa đen WEBHOOK_ID để tự xác minh chữ ký trình mô phỏng. Đừng nhầm lẫn giá trị đặc biệt đó với ID webhook thực được gán cho ứng dụng Sandbox. Nếu mục tiêu trước mắt của bạn là kiểm tra chính API đăng lại, hãy tạo giao dịch Sandbox thực tế thay vì sự kiện mô phỏng.

Xác thực rằng mọi URL chứng chỉ đều tuân theo các quy tắc được ghi lại của PayPal trước khi tải xuống, giữ lại bản trình bày sự kiện chính xác mà phương thức xác minh yêu cầu và không bao giờ ghi nhật ký mã thông báo truy cập, bí mật của khách hàng, chữ ký hoặc tải trọng thanh toán hoàn chỉnh.

Kiểm tra các sự kiện đổi tiền hoặc truy cập

PAYMENT.CAPTURE.COMPLETED: chỉ cấp quyền thực hiện sau khi kiểm tra số nhận dạng đơn hàng dự kiến, số tiền, đơn vị tiền tệ và trạng thái thu thập.
PAYMENT.CAPTURE.REFUNDED: đảo ngược quyền lợi một cách an toàn và hỗ trợ hoàn lại một phần.
Sự kiện đặt hàng thanh toán: phân biệt phê duyệt với quá trình chụp hoàn tất; Chỉ phê duyệt thôi không phải là bằng chứng cho thấy tiền đã được thu.
Sự kiện đăng ký: kích hoạt thử nghiệm, tạm dừng, hủy, thanh toán không thành công và giao hàng không theo đơn đặt hàng đối với máy ở trạng thái thanh toán của bạn.

Sự kiện của nhà cung cấp là thông báo, không phải là lệnh cơ sở dữ liệu không thể nghi ngờ. Đối với các chuyển đổi nhạy cảm, hãy truy xuất tài nguyên PayPal được tham chiếu bằng thông tin xác thực API đã được xác thực và so sánh nó với bản ghi đơn hàng của riêng bạn.

Khắc phục sự cố khi giao hàng tận nơi không thành công

Trình mô phỏng không thể kết nối

Xác nhận URL bắt đầu bằng https://, bao gồm đường dẫn webhook chính xác và vẫn trỏ đến một đường hầm đang chạy. Hãy tự mình kiểm tra URL công khai bằng curl. 404 thường có nghĩa là đường dẫn hoặc lộ trình khung bị sai; 502 thường có nghĩa là đường hầm không thể tiếp cận quy trình cục bộ.

Trình xử lý trả về 401

Trước tiên hãy xác định xem sự kiện đến từ trình mô phỏng hay ứng dụng Sandbox đã đăng ký. Kiểm tra ID webhook và phương thức xác minh tương ứng. Sau đó, hãy xác minh rằng proxy đã giữ nguyên tất cả các tiêu đề PAYPAL-* và bạn không trộn lẫn thông tin xác thực trực tiếp với api-m.sandbox.paypal.com.

PayPal thử lại hoặc đánh dấu phân phối không thành công

Chỉ trả lại 2xx sau khi sự kiện đã được chấp nhận lâu dài. Tránh chuyển hướng, trang lỗi HTML, phần mềm trung gian xác thực và các công việc đồng bộ dài trên tuyến. Sử dụng trình xem sự kiện cho các sự kiện trong ứng dụng thực và kết quả mô phỏng để chẩn đoán phân phối mô phỏng. Xem hướng dẫn thử lại và tạm thời để biết các mẫu xử lý bền bỉ.

Danh sách kiểm tra bảo mật trước khi phát hành

Sử dụng Sandbox riêng biệt và thông tin xác thực ứng dụng khách trực tiếp, ID webhook và bí mật điểm cuối.
Xác minh mọi chữ ký trước khi phân tích các lĩnh vực kinh doanh hoặc thay đổi trạng thái.
Loại bỏ trùng lặp bằng ID sự kiện PayPal và thực hiện các giao dịch thực hiện nguyên tử.
Chỉ cho phép POST, giới hạn kích thước yêu cầu, áp dụng giới hạn tốc độ và giữ URL đường hầm ở chế độ riêng tư khi có thể.
Xóa lại dữ liệu và thông tin xác thực của người mua từ nhật ký; xoay mọi thứ được hiển thị trong quá trình gỡ lỗi.
Thay thế URL đường hầm tạm thời bằng điểm cuối sản xuất ổn định và lặp lại kiểm tra chữ ký và thử lại.

Để có lược đồ xác minh và sự kiện hoàn chỉnh, hãy sử dụng Tham chiếu API Webhooks chính của PayPal. Để biết chi tiết không phụ thuộc vào khung về nội dung thô và so sánh an toàn, hãy đọc hướng dẫn xác minh chữ ký webhook.