Hướng dẫn bắt đầu nhanh

Onboarding merchant của bạn

Hoàn tất onboarding merchant với tính năng thanh toán trực tuyến, hoặc cả thanh toán trực tuyến lẫn thanh toán tại cửa hàng. Một merchant chỉ dùng Checkout không cần máy thanh toán. Cung cấp website của cửa hàng và thông tin kinh doanh trực tuyến, rồi chờ đơn vị xử lý thanh toán phê duyệt. Chỉ riêng việc tạo bản ghi merchant hoặc API key không kích hoạt thanh toán.

Mở Checkout trong Tapaya Platform. Các merchant yêu cầu thanh toán trực tuyến tự động xuất hiện, kể cả những merchant đang chờ phê duyệt. Tiếp tục khi merchant ở trạng thái Ready.

Mở Settings của merchant. Trong Merchant API key redirects, 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. Một nền tảng dùng Secret key của tổ chức sẽ đặt các giá trị này trong Organization defaults. Các ví dụ dùng https://shop.example. Xem Cài đặt Checkout để biết về ví và thương hiệu.

Lưu key trên máy chủ

Trong Settings của merchant, chọn Create merchant key và sao chép key tapaya_test_…. Key chỉ hiển thị một lần. Chỉ giữ key trong cấu hình phía máy chủ. Key không bao giờ được nằm trong mã trình duyệt hoặc hệ thống quản lý mã nguồn.

TAPAYA_ENVIRONMENT=sandbox
TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com
TAPAYA_SECRET_KEY=tapaya_test_...

SDK tự động đọc TAPAYA_SECRET_KEY và TAPAYA_ENVIRONMENT. Các ví dụ HTTP bên dưới dùng TAPAYA_CHECKOUT_API_URL. Hãy nạp các biến này vào tiến trình máy chủ của bạn; SDK không tải tệp .env.

Gửi key dưới dạng Authorization: Bearer <key>. Key của merchant tự xác định merchant của nó, nên không cần header nào khác. Một nền tảng phục vụ nhiều merchant sẽ dùng Secret key của tổ chức và gửi X-Tapaya-Merchant-Token trong mọi yêu cầu. Xem Xác thực Checkout.

Tạo một phiên Checkout

Khi khách hàng nhấn Checkout trong cửa hàng của bạn, hãy tính tổng tiền cuối cùng trên máy chủ, lưu đơn hàng cùng một key duy nhất cho lần thử thanh toán và tạo phiên. merchantOrderId là bắt buộc, và một đơn hàng chỉ có thể được thanh toán một lần. Số tiền được tính theo đơn vị nhỏ nhất của tiền tệ, nên 12100 là 121,00 EUR.

Với Node.js 22.13.0 trở lên, hãy cài đặt ESM SDK trước khi dùng ví dụ Node.js SDK:

npm install @tapayadot/checkout

const response = await fetch(
  new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL),
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': order.checkoutAttemptKey,
    },
    body: JSON.stringify({
      merchantOrderId: order.id,
      amount: order.totalInMinorUnits,
      currency: order.currency,
      successUrl: 'https://shop.example/checkout/return',
      cancelUrl: 'https://shop.example/checkout/cancel',
    }),
  },
);
if (!response.ok) throw new Error(`Checkout failed (${response.status})`);
const session = await response.json();

Nếu yêu cầu hết thời gian chờ, hãy thử lại với cùng key và phần thân. API sẽ trả về lại phiên ban đầu thay vì tạo phiên thứ hai.

Chuyển hướng khách hàng

Lưu session.id cùng với đơn hàng, sau đó chuyển trình duyệt đến session.url bằng HTTP 303. Dùng URL đúng như được trả về.

// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);

Tapaya hiển thị tóm tắt đơn hàng và biểu mẫu thanh toán bảo mật, đồng thời xử lý tokenization, 3-D Secure và việc trừ tiền. Sau khi bị từ chối, khách hàng có thể thử thẻ khác trên cùng trang. Các phiên nhận thanh toán mới trong 30 phút.

Xác minh thanh toán trên máy chủ của bạn

Khi khách hàng đến URL thành công hoặc URL hủy của bạn, hãy truy xuất phiên bằng Secret key và so sánh với đơn hàng đã lưu. Chỉ riêng một lần chuyển hướng không bao giờ chứng minh việc thanh toán.

const response = await fetch(
  new URL(
    `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`,
    process.env.TAPAYA_CHECKOUT_API_URL,
  ),
  { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } },
);
if (!response.ok) throw new Error(`Status check failed (${response.status})`);
const current = await response.json();

Với cả hai cách tích hợp, hãy so sánh kết quả với đơn hàng đã lưu trước khi hoàn tất đơn hàng:

const matches =
  current.id === order.checkoutSessionId &&
  current.merchantOrderId === order.id &&
  current.amount === order.totalInMinorUnits &&
  current.currency === order.currency;

if (matches && current.paymentStatus === 'successful') {
  await fulfillOnce(order); // idempotent, safe on repeated visits
}

Nếu trạng thái vẫn là unpaid hoặc việc truy xuất thất bại, hãy giữ ID phiên và kiểm tra lại. Hiện chưa có webhook, vì vậy hãy chạy một tác vụ đối soát cho những khách hàng đóng tab trước khi quay lại.