xStore.checkout#

Quy trình thanh toán bốn bước, hoặc placeOrder() một lần gọi khi giao diện chỉ có một biểu mẫu — rồi pay() để khởi tạo thanh toán ở cổng, và paymentReturn() để đọc kết quả khi khách quay lại từ cổng.

Phương thức#

Ví dụ đầy đủ#

<script>
  // Bốn bước PHẢI gọi đúng thứ tự: mỗi bước kiểm tra kết quả của bước trước.
  // getToken() chạy cục bộ nên không await.
  async function placeOrder(address, shippingTier, paymentMethod) {
    const cartToken = xStore.cart.getToken();
    if (!cartToken) {
      alert('Giỏ hàng đang trống.');
      return;
    }

    try {
      // 1. Mở phiên thanh toán từ giỏ hiện tại.
      let session = await xStore.checkout.start(cartToken);

      // 2. Địa chỉ nhận hàng — gửi kèm province_code / ward_code để có báo giá
      //    vận chuyển khớp vùng, thay vì rơi về so khớp theo tên.
      session = await xStore.checkout.setAddress(session.id, address);

      // 3. Gói vận chuyển. MÁY CHỦ tính phí — không còn shipping_amount để gửi.
      session = await xStore.checkout.setShipping(session.id, {
        shipping_tier: shippingTier,
      });

      // 4. Ghi nhận phương thức thanh toán vào phiên. KHÔNG trả về đường dẫn
      //    chuyển hướng — bước 6 (checkout.pay) mới làm việc đó.
      session = await xStore.checkout.initiatePayment(session.id, {
        payment_method: paymentMethod,
      });

      // 5. Tạo đơn hàng thật từ các lựa chọn ở trên.
      const don = await xStore.checkout.placeOrder(cartToken, {
        address,
        shipping: { shipping_tier: shippingTier },
        payment:  { payment_method: paymentMethod },
      });

      // 6. Khởi tạo thanh toán ở cổng CHO ĐƠN VỪA TẠO. Gửi cartToken, không phải
      //    order_id — route này không yêu cầu đăng nhập.
      const thanhToan = await xStore.checkout.pay(cartToken);

      // redirect_url là null với cổng không cần chuyển hướng (COD) — không phải
      // lỗi, chỉ là không có đường dẫn để rời trang.
      window.location.href = thanhToan.redirect_url || '/tai-khoan/don-hang/' + don.order_id;
    } catch (err) {
      if (err.status === 401) {
        window.location.href = '/dang-nhap?next=' + encodeURIComponent(location.pathname);
      } else {
        alert(err.message);
      }
    }
  }

  // MỘT biểu mẫu, MỘT lần gọi: placeOrder() gộp địa chỉ + vận chuyển + phương
  // thức thanh toán, nhưng vẫn cần pay() sau đó để lấy đường dẫn cổng thanh toán.
  async function placeOrderInOneCall(address, shippingTier, paymentMethod) {
    const cartToken = xStore.cart.getToken();
    if (!cartToken) return;

    const don = await xStore.checkout.placeOrder(cartToken, {
      address,
      shipping: { shipping_tier: shippingTier },
      payment:  { payment_method: paymentMethod },
    });

    // Bấm hai lần vẫn an toàn: lần sau trả về đúng đơn cũ.
    console.log(don.code, don.already_placed);

    const thanhToan = await xStore.checkout.pay(cartToken);
    window.location.href = thanhToan.redirect_url || '/tai-khoan/don-hang/' + don.order_id;
  }

  // Danh sách cổng thanh toán tenant này đã bật — dùng để dựng giao diện chọn,
  // đừng viết cứng danh sách cổng trong giao diện.
  async function renderPaymentMethods() {
    const trang = await xStore.checkout.paymentMethods();
    document.getElementById('payment').innerHTML = trang.items.map((pm) => `
      <label>
        <input type="radio" name="payment_method" value="${pm.code}">
        ${pm.label}
        ${pm.instruction ? `<small>${pm.instruction}</small>` : ''}
      </label>
    `).join('');
  }

  // Trang khách quay về sau khi rời cổng thanh toán.
  async function renderPaymentResult() {
    // ⚠️ query_string là chuỗi NGUYÊN VĂN — không tự parse rồi build lại,
    // chữ ký của cổng tính trên đúng chuỗi cổng gửi.
    const ketQua = await xStore.checkout.paymentReturn({
      query_string: window.location.search.slice(1),
    });

    // ⚠️ paymentReturn KHÔNG GHI GÌ — nó chỉ đọc lại trạng thái, đơn được chốt
    // bằng IPN máy-tới-máy của cổng, chạy độc lập và có thể tới trước hoặc sau
    // khi khách bấm quay lại.
    //
    // ⚠️ settled: false KHÔNG PHẢI là thất bại — chỉ nghĩa là IPN chưa tới.
    // Hiển thị "đang xác nhận", ĐỪNG hiển thị "thất bại".
    const el = document.getElementById('result');
    if (!ketQua.settled) {
      el.textContent = 'Đơn hàng đang được xác nhận…';
    } else if (ketQua.status === 'succeeded') {
      el.textContent = `Thanh toán thành công cho đơn ${ketQua.code}.`;
    } else {
      el.textContent = 'Thanh toán chưa hoàn tất: ' + ketQua.status;
    }
  }
</script>

Thư viện gọi tới /api/... trên chính tên miền cửa hàng, nên không cần khai báo địa chỉ máy chủ ở bất kỳ đâu.

Xem thêm Sự kiện để giao diện tự cập nhật sau mỗi thao tác.