--- title: "Giới thiệu Tapaya Checkout" description: "Thẻ, Apple Pay và Google Pay qua một API duy nhất. Chuyển khách hàng đến trang thanh toán được lưu trữ sẵn, hoặc nhúng các trường thẻ bảo mật vào trang thanh toán của chính bạn. Dưới đây là cách từng phương án hoạt động và cách lựa chọn." url: "https://tapaya.com/vi/blog/introducing-tapaya-checkout-vi" lang: "vi" last_updated: "2026-11-13" --- # Giới thiệu Tapaya Checkout > Thẻ, Apple Pay và Google Pay qua một API duy nhất. Chuyển khách hàng đến trang thanh toán được lưu trữ sẵn, hoặc nhúng các trường thẻ bảo mật vào trang thanh toán của chính bạn. Dưới đây là cách từng phương án hoạt động và cách lựa chọn. Tapaya Checkout mang thanh toán trực tuyến đến Tapaya. Người bán của bạn có thể nhận thẻ, Apple Pay và Google Pay trên bất kỳ trang web nào, và bạn chọn mình sẽ tự kiểm soát bao nhiêu phần của trang thanh toán. - **Hosted Checkout.** Máy chủ của bạn tạo một phiên và chuyển khách hàng đến trang thanh toán bảo mật do Tapaya lưu trữ. Gần như không cần làm gì ở front-end. - **Embedded Checkout.** Các trường thẻ bảo mật và nút ví điện tử nằm ngay trong trang thanh toán của bạn, cạnh nút Thanh toán của chính bạn. Cả hai dùng chung một mô hình phía máy chủ: tạo, chuyển hướng hoặc nhúng, rồi xác minh trên máy chủ trước khi xử lý đơn hàng. Bạn có thể bắt đầu ngay hôm nay trong sandbox tại [docs.tapaya.com](https://docs.tapaya.com). {% youtube #PejafWaMx24 title="Introducing Tapaya Checkout: New way to payments online" poster="/images/posts/introducing-tapaya-checkout-video-poster.jpg" /%} ## Tapaya Checkout là gì Tapaya Checkout là phần trực tuyến của Tapaya. Nó nhận thanh toán bằng thẻ, Apple Pay và Google Pay cho người bán của bạn, qua một API và một Node.js SDK. Ý tưởng giống như thanh toán tại quầy: bạn tích hợp một lần, trải nghiệm của người bán vẫn nằm trong sản phẩm của bạn, còn Tapaya lo toàn bộ sự phức tạp của thanh toán phía sau. ![Tapaya Checkout tóm tắt: thẻ, Apple Pay và Google Pay, tích hợp sẵn 3-D Secure, không thanh toán trùng lặp, tự động thử lại, dữ liệu thẻ không bao giờ chạm vào trang của bạn, một API và SDK cho cả Hosted và Embedded Checkout](/images/posts/introducing-tapaya-checkout-at-a-glance.jpg) - **Hosted Checkout** cung cấp cho bạn một trang thanh toán dựng sẵn trên tên miền của Tapaya, dùng được trên máy tính và di động. - **Embedded Checkout** cung cấp cho bạn các trường bảo mật để gắn vào trang của chính bạn. Thông tin thẻ nằm trong khung (iframe) của Tapaya và không bao giờ đến được trang của bạn. Cả hai cùng dựa trên những thành phần cơ bản: một khóa phía máy chủ, số tiền tính theo đơn vị nhỏ nhất của tiền tệ (vì vậy `1880` nghĩa là 18,80 EUR), yêu cầu idempotent và xác minh phía máy chủ. Khi đã xây xong một phương án, bạn đã nắm phần lớn phương án còn lại. ## Hosted hay Embedded: chọn phương án nào ![Embedded Checkout giữ khách hàng ở trang thanh toán của chính bạn. Hosted Checkout đưa họ đến một trang bảo mật do Tapaya lưu trữ.](/images/posts/introducing-tapaya-checkout-embedded-vs-hosted.jpg) {% table %} -   - Hosted Checkout - Embedded Checkout --- - **Khách hàng thanh toán ở đâu** - Trên trang do Tapaya lưu trữ, sau đó quay lại cửa hàng của bạn - Ngay trong trang thanh toán của bạn --- - **Công việc front-end** - Một lần chuyển hướng - Gắn các trường, xử lý `submit()` và trạng thái --- - **Nút Thanh toán** - Trên trang của Tapaya - Nút của chính bạn --- - **Apple Pay và Google Pay** - Trên trang được lưu trữ - Hiển thị trong khung của Tapaya cạnh các trường thẻ --- - **3-D Secure** - Xử lý trên trang được lưu trữ - Xử lý bên trong `submit()`, trong khung của Tapaya --- - **Phù hợp nhất cho** - Triển khai nhanh, cửa hàng đơn giản, nền tảng có nhiều người bán - Các nhóm muốn toàn quyền kiểm soát trải nghiệm thanh toán {% /table %} Nếu chưa chắc, hãy bắt đầu với Hosted Checkout. Chuyển sang Embedded về sau vẫn dùng lại cùng các khóa, cùng mô hình đơn hàng và cùng logic xác minh. ## Hosted Checkout trong năm bước 1. **Tạo phiên trên máy chủ của bạn.** Gọi `POST /merchant/checkout-sessions` với `merchantOrderId`, `amount` (theo đơn vị nhỏ nhất), `currency`, `customer`, `successUrl` và `cancelUrl`. Gửi kèm header `Idempotency-Key`. 1. **Lưu ID phiên** vào đơn hàng. 1. **Chuyển hướng trình duyệt** đến `session.url` bằng HTTP 303. Dùng URL đúng như được trả về. 1. **Khách hàng thanh toán trên trang được lưu trữ.** Thẻ bị từ chối có thể thử lại ngay trên cùng trang. Mỗi phiên nhận thanh toán trong 30 phút. 1. **Xác minh trên máy chủ.** Khi khách hàng quay lại một trong hai URL trả về, hãy gọi `GET /merchant/checkout-sessions/{id}`. Kiểm tra ID, ID đơn hàng, số tiền và tiền tệ khớp với đơn hàng của bạn, và chỉ xử lý đơn khi `paymentStatus` là `successful`. Với Node.js SDK (`npm install @tapayadot/checkout`, Node.js 22.13.0 trở lên), phần cốt lõi trông như sau: ```typescript import { Tapaya } from '@tapayadot/checkout' // Reads TAPAYA_SECRET_KEY from the server environment. const tapaya = new Tapaya() // 1–3. Create the session and redirect the customer const session = await tapaya.checkout.sessions.create(params, { idempotencyKey }) return Response.redirect(session.url, 303) // 5. Later, on the return URL: verify before you fulfil const current = await tapaya.checkout.sessions.get(sessionId) ``` Toàn bộ tham số có trong kiểu `CreateHostedCheckoutSessionParams` và trong hướng dẫn Hosted Checkout. ## Embedded Checkout: trường bảo mật ngay trong trang của bạn Embedded Checkout chia công việc giữa trang của bạn và một endpoint `prepare` nhỏ trên máy chủ của bạn. Trên trình duyệt, bạn tải Tapaya từ `@tapayadot/checkout/client` và gắn các trường: ```typescript import { loadTapaya } from '@tapayadot/checkout/client' const tapaya = await loadTapaya(publishableKey, { apiOrigin }) const payment = tapaya.createPayment({ prepare: '/api/payments', // your server endpoint wallets: { amount: 1880, currency: 'EUR' }, onChange: (snapshot) => { /* enable Pay when snapshot.canSubmit */ }, }) payment.mount('#card-fields') // In your form handler: await payment.submit() // validates, runs 3-D Secure, confirms ``` Trên máy chủ, endpoint `prepare` tải đơn hàng và dùng lại thanh toán hiện có nếu đã có. Nếu chưa, nó tạo thanh toán mới bằng `POST /merchant/payments` cùng một khóa idempotency. Sau đó nó trả về `{ clientSecret, status }`. Ứng dụng React có thể dùng `usePayment()` từ `@tapayadot/checkout/react`. Một vài điều cần biết: - Thêm `https://js.tapaya.com` vào `script-src` và `frame-src` trong Content Security Policy của bạn. - Chỉ import `@tapayadot/checkout` trên máy chủ. Trình duyệt dùng điểm vào `/client`. - `snapshot.outcome` cho bạn biết cần hiển thị gì: `open`, `pending`, `completed` hoặc `ended`. - Nút ví điện tử chỉ xuất hiện ở nơi được hỗ trợ và đã bật. Apple Pay cần một tên miền cửa hàng đang hoạt động, và Google Pay ở môi trường thật cần merchant ID. Toàn bộ luồng có trong hướng dẫn Embedded Checkout. ## Được xây dựng cho tích hợp đáng tin cậy Thanh toán thất bại theo những cách lộn xộn: hết thời gian chờ, khách hàng đóng tab, một lần thử lại đến hai lần. Tapaya Checkout được xây dựng để bạn xử lý được từng trường hợp đó. - **Khóa idempotency cho mọi lần tạo.** Thử lại với cùng khóa và cùng nội dung, bạn nhận lại đúng phiên hoặc thanh toán ban đầu. Nội dung đã thay đổi sẽ trả về HTTP 409. - **Tự động thử lại trong Node.js SDK.** Mặc định SDK thử lại hai lần khi gặp lỗi kết nối, hết thời gian chờ và HTTP 429, 502, 503 và 504, với khoảng chờ ngẫu nhiên (jitter). - **Một thanh toán cho mỗi đơn hàng.** Phiên mới cho cùng một đơn hàng sẽ làm phiên trước hết hạn. Đơn hàng đã thanh toán, hoặc đang có thanh toán dở dang, sẽ bị từ chối. - **Webhook kèm polling.** Đăng ký nhận sự kiện của phiên thanh toán, và tiếp tục kiểm tra các phiên chưa có kết quả để dự phòng. - **Xác minh rồi mới xử lý, và chỉ một lần.** Riêng việc khách truy cập URL thành công không chứng minh điều gì. Luôn xác nhận trạng thái trên máy chủ và ghi nhận việc xử lý đơn hàng một cách nguyên tử (atomic). Trước khi chạy thật, hãy thử mọi kết quả bằng thẻ thử nghiệm trong sandbox và đi hết QA checklist. ## Xây dựng nhanh hơn với máy chủ MCP của tài liệu Tapaya Tài liệu của Tapaya có máy chủ MCP riêng. Các công cụ lập trình AI của bạn có thể tìm trong các hướng dẫn và tra cứu API endpoint ngay khi bạn đang phát triển, không cần rời trình soạn thảo. Nó hoạt động với Claude Code, Claude Desktop, Cursor, VS Code, Codex và mọi MCP client khác. Máy chủ này công khai và không cần API key. ```bash claude mcp add --transport http tapaya-docs https://docs.tapaya.com/mcp ``` Nó không bao giờ gọi API Tapaya thật và không bao giờ yêu cầu khóa. Cách thiết lập cho từng client có trong [MCP Setup](https://docs.tapaya.com/mcp-server). ## Từ sandbox đến môi trường thật 1. **Đăng ký người bán** với tính năng thanh toán trực tuyến, và chờ đến khi người bán hiển thị trạng thái Ready trong mục Checkout trên Tapaya Platform. 1. **Thêm cửa hàng của bạn** vào Allowed websites và đặt URL thành công và URL hủy mặc định. 1. **Phát triển trong sandbox** với khóa `tapaya_test_`, chỉ lưu trên máy chủ của bạn. 1. **Chuyển sang production:** khóa production, `TAPAYA_ENVIRONMENT=production` và các URL trả về production. 1. **Thiết lập ví điện tử cho môi trường thật:** tên miền cửa hàng cho Apple Pay và merchant ID cho Google Pay. Hướng dẫn Quick Start đưa bạn từ con số không đến khoản thanh toán sandbox đầu tiên chỉ với vài lệnh gọi máy chủ. ## Câu hỏi thường gặp ### Tapaya Checkout hỗ trợ những phương thức thanh toán nào? Thẻ, Apple Pay và Google Pay, trên cả Hosted và Embedded Checkout. ### Thông tin thẻ có đi qua máy chủ hoặc trang của tôi không? Không. Với Hosted Checkout, khách hàng thanh toán trên trang của Tapaya. Với Embedded Checkout, các trường thẻ và 3-D Secure chạy bên trong khung của Tapaya, và dữ liệu thẻ không bao giờ đến được trang của bạn. ### Một phiên Hosted Checkout có hiệu lực bao lâu? 30 phút kể từ khi tạo. Khoản thanh toán được gửi trước thời điểm đó vẫn được hoàn tất. Nếu sau đó đơn hàng vẫn chưa được thanh toán, hãy tạo phiên mới. ### Có SDK không? Có, `@tapayadot/checkout` cho Node.js 22.13.0 trở lên. SDK hỗ trợ Hosted Checkout trên máy chủ, cùng các điểm vào cho trình duyệt và React dành cho Embedded Checkout. Các nền tảng khác có thể gọi trực tiếp REST API. ### Nền tảng có thể nhận thanh toán cho nhiều người bán không? Có. Dùng Secret key của tổ chức và gửi token của người bán kèm mỗi yêu cầu. ## Bắt đầu ngay Đọc phần tổng quan Online Payments tại [docs.tapaya.com](https://docs.tapaya.com), tạo khóa sandbox và nhận khoản thanh toán thử nghiệm đầu tiên ngay hôm nay. Có câu hỏi về tích hợp? Hãy viết cho chúng tôi qua [developers@tapaya.com](mailto:developers@tapaya.com). ## Sitemap - [Sitemap](https://tapaya.com/sitemap.md): every page on tapaya.com, as markdown links