Giới thiệu Tapaya Checkout

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.

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.

• 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

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.
2. Lưu ID phiên vào đơn hàng.
3. Chuyển hướng trình duyệt đến session.url bằng HTTP 303. Dùng URL đúng như được trả về.
4. 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.
5. 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:

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:

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.

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.

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.
2. 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.
3. Phát triển trong sandbox với khóa tapaya_test_, chỉ lưu trên máy chủ của bạn.
4. Chuyển sang production: khóa production, TAPAYA_ENVIRONMENT=production và các URL trả về production.
5. 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, 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.