VI
Nhận NexCMP miễn phí
Áp dụng cho NexCMP 1.6.1·Đã cập nhật ·Xem dưới dạng Markdown

Stripe ​

Vị trí trong admin: Finance › Payment channels › Stripe (/payments/stripe). Bật tắt và phí: Finance › Payment channels › Fees & limits (/payments/fees).

Chức năng ​

Stripe xử lý thanh toán qua thẻ để nạp tiền vào ví. Với cùng một tài khoản, bạn cũng có thể cung cấp Apple Pay, Google Pay, Link và Alipay, đồng thời cho phép khách hàng lưu thẻ để nạp tiền tự động. Hãy sử dụng kênh này làm kênh chính cho khách hàng quốc tế.

Yêu cầu ​

Hạng mụcYêu cầu
Tài khoản StripeMột tài khoản Stripe có thể chấp nhận thanh toán bằng USD. Alipay được tính phí bằng JPY và cần được Stripe kích hoạt cho tài khoản của bạn.
Khóa APIMột secret key (sk_live_... hoặc sk_test_...) và một publishable key (pk_live_... hoặc pk_test_...). Biểu mẫu chỉ chấp nhận các khóa có tiền tố này.
MạngBảng điều khiển của bạn phải có thể truy cập được qua HTTPS từ Internet (Stripe gọi webhook) và phải kết nối được tới api.stripe.com qua cổng 443.
Domain (chỉ dành cho ví điện tử)Domain phía khách hàng phải phục vụ /.well-known/apple-developer-merchantid-domain-association — NexCMP sẽ tự động xử lý việc này cho bạn.
Thành phần phụ thuộcKhông có.

Tài khoản Stripe dùng chung

NexCMP chỉ xử lý các sự kiện webhook cho các khoản thanh toán do chính nó tạo ra, vì vậy bạn có thể sử dụng một tài khoản Stripe đang phục vụ cho cả ứng dụng khác.

Chuẩn bị hạ tầng ​

Về phía Stripe:

  1. Đăng nhập vào Stripe Dashboard. Bật hoặc tắt Test mode để quyết định bạn đang chạy thử nghiệm hay đưa vào hoạt động chính thức. Khóa của chế độ này không bao giờ hoạt động với chế độ kia.
  2. Mở Developers › API keys. Sao chép Publishable key, sau đó hiện và sao chép Secret key. Hãy bảo mật secret key.
  3. (Tùy chọn) Mở Settings › Payment methods và kích hoạt Alipay nếu bạn muốn cung cấp phương thức này.
  4. Bạn không cần phải tạo webhook thủ công — NexCMP có thể tạo tự động cho bạn (xem bước 5 bên dưới). Nếu muốn tạo thủ công, hãy tạo một endpoint trong Developers › Webhooks với URL và các sự kiện được liệt kê trong Webhook.

Kết nối trong NexCMP ​

  1. Mở Finance › Payment channels › Stripe (/payments/stripe).
  2. Trong thẻ API keys, chọn Mode (live hoặc test), dán Secret key và Publishable key.
  3. Nhấp vào Save. Các khóa được ghi vào tệp cấu hình trên máy chủ mà chỉ tài khoản dịch vụ của NexCMP mới có quyền đọc. Chúng không bao giờ được gửi ngược lại trình duyệt; sau đó trang sẽ chỉ hiển thị 4 ký tự cuối.
  4. Nhấp vào Check. Hộp thoại sẽ báo cáo kết nối, chế độ, số dư khả dụng và đang chờ xử lý, ID tài khoản, trạng thái bật tính phí, sự tồn tại của webhook và tính khả dụng của Alipay. Dòng màu đỏ biểu thị phần đó cần được xử lý.
  5. Trong thẻ Webhook, nhấp vào Create webhook và xác nhận. NexCMP sẽ yêu cầu Stripe tạo endpoint với đầy đủ các sự kiện cần thiết và tự động điền Webhook signing secret (whsec_...). URL được điền sẵn trong trường này là https://<your-domain>/v1/billing/stripe/webhook, ví dụ https://cloud.example.com/v1/billing/stripe/webhook.
  6. Mở Fees & limits (/payments/fees), giữ bật Card (Stripe), đặt Stripe fee % và Stripe fixed fee (cents) theo mức phí thực tế của bạn, rồi nhấp vào Save channels & fees. Xem Payment channels.

Trang Stripe với mode, secret key và publishable key được điền các giá trị mẫu

Webhook ​

Biểu ngữ màu đỏ "Missing webhook_secret" sẽ tiếp tục hiển thị cho đến khi signing secret được lưu. Nếu không có nó, các khoản nạp tiền qua Stripe sẽ không được ghi nhận, mặc dù Stripe đã trừ tiền.

Hạng mụcGiá trị
URLhttps://<your-domain>/v1/billing/stripe/webhook
Sự kiệncheckout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
Chữ kýHeader Stripe-Signature của Stripe, HMAC-SHA256, dung sai 300 giây. Các yêu cầu có chữ ký không hợp lệ sẽ nhận mã HTTP 400.
IdempotencyMỗi event ID chỉ được lưu một lần; việc gửi lại không bao giờ cộng tiền hai lần.

Nếu bạn đã nâng cấp từ một bản phát hành đăng ký ít sự kiện hơn, hãy nhấp lại vào Create webhook — endpoint cũ vẫn được giữ lại, vì vậy hãy xóa nó thủ công trong Stripe Dashboard sau đó.

Các hàng 24h events và Latest event trong thẻ Webhook cho bạn biết liệu Stripe có đang kết nối được tới panel hay không. Các sự kiện riêng lẻ được liệt kê trong Payment channels › Gateway events (/payments/events, tab Stripe), nơi bạn có thể xem từng sự kiện (Payload) hoặc phát lại (Replay).

  1. Trong thẻ Wallets (Apple Pay · Google Pay · Link) & Alipay, trường Customer app Domain registered with Stripe được điền sẵn hostname của trang web bạn (ví dụ: cloud.example.com).
  2. Nhấp vào Register / verify domain và xác nhận. NexCMP sẽ đăng ký domain trong payment method domains của Stripe và yêu cầu Stripe xác thực.
  3. Kết quả sẽ hiển thị trạng thái của Apple Pay, Google Pay và Link. Apple Pay chỉ hiển thị khi trạng thái là active.
  4. Trong Fees & limits, hãy bật Apple Pay · Google Pay · Link.

Thẻ Wallet hiển thị domain đã đăng ký cùng trạng thái của Apple Pay, Google Pay và Link

Apple Pay vẫn không hoạt động

Apple Pay yêu cầu file domain-association phải phản hồi HTTP 200 trên public domain của bạn. Nếu bạn đặt Cloudflare hoặc proxy khác phía trước, đừng chặn /.well-known/.

Alipay ​

Alipay là tùy chọn. Kích hoạt tính năng này trong Stripe Dashboard › Settings › Payment methods, nhấp vào Check và đợi cho đến khi hộp thoại hiển thị Alipay đã khả dụng, sau đó bật Alipay (Stripe, JPY display) trong Fees & limits. Thiết lập Alipay fee %, Alipay fixed fee, tỷ giá ¥/USD rate (50–500) và FX spread % (0–20). Cập nhật tỷ giá ¥/USD thường xuyên; trang sẽ cảnh báo khi tỷ giá này cũ hơn 7 ngày.

Kiểm tra ​

  1. Trong chế độ test mode, hãy đăng nhập vào portal với tư cách khách hàng thử nghiệm, mở Billing, nhấp vào Deposit, chọn Card và thanh toán số tiền tối thiểu bằng thẻ test của Stripe 4242 4242 4242 4242 (ngày bất kỳ trong tương lai, CVC bất kỳ).
  2. Số dư sẽ tăng lên trong vài giây và khoản thanh toán sẽ xuất hiện trong Finance › Billing › Top-ups với trạng thái Completed.
  3. Mở Payment channels › Gateway events › Stripe: bạn sẽ thấy checkout.session.completed hoặc payment_intent.succeeded kèm theo thời gian đã xử lý.
  4. Quay lại trang Stripe, giá trị 24h events sẽ lớn hơn 0.

Trước khi đưa vào hoạt động chính thức, hãy chuyển Mode sang live, dán các live key và nhấp lại vào Create webhook (webhook của chế độ test và live là riêng biệt).

Hạn mức & lưu ý ​

  • Số tiền và đơn vị tiền tệ. Ví được tính bằng USD. Các khoản thanh toán bằng thẻ, ví và link được tính phí bằng USD; Alipay hiển thị cho khách hàng bằng JPY và được quy đổi theo tỷ giá của bạn.
  • Phí. Phí thực tế của Stripe không được tự động đọc lại; phần trăm phí bạn thiết lập sẽ quyết định những gì khách hàng nhìn thấy và số tiền được cộng vào ví. Chọn Customer pays top-up fee trong Fees & limits để tính thêm phí này.
  • Thẻ đã lưu. Khi khách hàng tích chọn Save card for auto top-up, thẻ sẽ được lưu tại Stripe, không phải trên máy chủ của bạn. Xem Saved payment methods.
  • Hoàn tiền. Hoàn tiền về thẻ là quy trình gồm hai bước: quản trị viên tạo yêu cầu hoàn tiền cho một khoản thanh toán đã hoàn tất (Finance › Billing › Top-ups, thao tác hoàn tiền trên giao dịch) và sau đó phê duyệt yêu cầu đó trong Finance › Payouts › Card refunds (/billing/payouts). Hoàn tiền Alipay là bất đồng bộ; nếu thất bại (refund.failed), số tiền tạm giữ sẽ được hoàn lại vào ví.
  • Tranh chấp. Khi xảy ra charge.dispute.created, NexCMP sẽ khóa tài khoản của khách hàng, tạm dừng các dịch vụ trả trước của họ (không có gì bị xóa) và gửi cảnh báo tới quản trị viên. Nếu bạn thắng (charge.dispute.closed), số tiền sẽ được cộng lại vào ví.
  • Thanh toán đang chờ. Nếu webhook không bao giờ đến, NexCMP sẽ tự kiểm tra các khoản thanh toán ở trạng thái chờ quá 10 phút với Stripe và hoàn tất chúng. Các khoản thanh toán cũ hơn 7 ngày sẽ bị bỏ qua.
  • Resellers có thể kết nối tài khoản Stripe của riêng họ (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>); xem Resellers.

Xử lý sự cố ​

Hiện tượngNguyên nhânCách khắc phục
"Secret key phải bắt đầu bằng sk_live_/sk_test_"Dán sai khóaDán secret key từ Developers › API keys.
"Secret key không khớp với chế độ live/test"Chế độ và khóa không khớp nhauĐảm bảo Mode khớp với tiền tố của khóa.
"Publishable key phải bắt đầu bằng pk_"Sai khóaSử dụng publishable key.
Kiểm tra báo kết nối thất bạiSai khóa, khóa đã bị thu hồi hoặc máy chủ không thể kết nối tới api.stripe.comDán lại khóa; kiểm tra bằng curl -I https://api.stripe.com từ máy chủ.
Banner màu đỏ "Missing webhook_secret"Signing secret chưa được lưuNhấp vào Create webhook hoặc dán secret whsec_... từ Stripe Dashboard và Save.
Đã trừ tiền nhưng số dư không thay đổiWebhook không được chuyển đến hoặc chữ ký không hợp lệKiểm tra URL có kết thúc bằng /v1/billing/stripe/webhook hay không, secret có khớp với endpoint không, và gửi lại sự kiện trong Gateway events. Trên Stripe, hãy mở endpoint và kiểm tra các lần gửi (HTTP 400 nghĩa là sai signing secret).
"Create webhook" thất bạiURL không phải HTTPS hoặc không thể truy cậpSử dụng tên miền https:// công khai của bạn.
Trạng thái Apple Pay không hoạt độngTên miền chưa được xác thựcNhấp lại vào Register / verify domain sau khi tệp liên kết tên miền trả về mã 200.
Alipay không khả dụng trong hộp thoại CheckChưa được kích hoạt trên StripeKích hoạt phương thức này trên Stripe Dashboard, sau đó nhấp vào Check.
Khách hàng không thấy biểu mẫu thẻCard (Stripe) đang tắt hoặc thiếu secret keyBật tùy chọn này trong Fees & limits và lưu các khóa.