---
title: Stripe
description: Kết nối Stripe với NexCMP để thanh toán qua thẻ, Apple Pay, Google Pay, Link và Alipay — API key, webhook, đăng ký domain và thanh toán thử nghiệm.
url: https://nexcmp.com/vi/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 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 {#what-it-does}

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](https://nexcmp.com/vi/docs/billing/auto-top-up/). 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 {#requirements}

| Hạng mục | Yêu cầu |
|---|---|
| Tài khoản Stripe | Mộ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 API | Mộ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ạng | Bả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ộc | Không có. |

::: info 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 {#prepare-the-infrastructure}

Về phía Stripe:

1. Đăng nhập vào [Stripe Dashboard](https://dashboard.stripe.com). 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](#webhook).

## Kết nối trong NexCMP {#connect-in-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](https://nexcmp.com/vi/docs/billing/payment-channels/#switches-and-fees-fees-limits).

![Trang Stripe với mode, secret key và publishable key được điền các giá trị mẫu](https://nexcmp.com/vi/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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ục | Giá trị |
|---|---|
| URL | `https://<your-domain>/v1/billing/stripe/webhook` |
| Sự kiện | `checkout.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. |
| Idempotency | Mỗ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**).

### Apple Pay, Google Pay và Link {#apple-pay-google-pay-and-link}

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](https://nexcmp.com/vi/docs/images/billing/stripe-03-wallets.webp)

::: tip 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}

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 {#verify}

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 ý {#limits-notes}

- **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](https://nexcmp.com/vi/docs/billing/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](https://nexcmp.com/vi/docs/customers/resellers/).

## Xử lý sự cố {#troubleshooting}

| Hiện tượng | Nguyên nhân | Cách khắc phục |
|---|---|---|
| "Secret key phải bắt đầu bằng sk_live_/sk_test_" | Dán sai khóa | Dá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óa | Sử dụng publishable key. |
| Kiểm tra báo kết nối thất bại | Sai khóa, khóa đã bị thu hồi hoặc máy chủ không thể kết nối tới `api.stripe.com` | Dá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ưu | Nhấ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 đổi | Webhook 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ại | URL không phải HTTPS hoặc không thể truy cập | Sử dụng tên miền `https://` công khai của bạn. |
| Trạng thái Apple Pay không hoạt động | Tên miền chưa được xác thực | Nhấ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 Check | Chưa được kích hoạt trên Stripe | Kí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 key | Bật tùy chọn này trong **Fees & limits** và lưu các khóa. |