Hướng Dẫn Quy Trình Thanh Toán Medusa: Xây Dựng E-Commerce Hoàn Chỉnh

Xây dựng một cửa hàng thương mại điện tử yêu cầu triển khai một quy trình thanh toán mạnh mẽ, có khả năng quản lý giỏ hàng, vận chuyển và xử lý thanh toán. Medusa.js cung cấp một bộ API Store toàn diện, giúp quá trình này trở nên đơn giản hơn. Trong bài viết này, chúng ta sẽ khám phá quy trình thanh toán hoàn chỉnh của Medusa bằng cách đi qua từng endpoint API cần thiết để đưa khách hàng từ một giỏ hàng trống đến một đơn hàng hoàn tất.

Hiểu Quy Trình Thanh Toán Medusa

Quy trình thanh toán Medusa bao gồm bảy bước cần thiết:

Tạo Giỏ Hàng - Khởi tạo một giỏ hàng mới
Thêm Sản Phẩm - Thêm sản phẩm vào giỏ hàng
Thiết Lập Địa Chỉ Giao Hàng - Cấu hình thông tin giao hàng
Chọn Phương Thức Vận Chuyển - Lựa chọn tùy chọn giao hàng
Thu Thập Thanh Toán - Khởi tạo việc xử lý thanh toán
Phiên Thanh Toán - Thiết lập nhà cung cấp thanh toán
Hoàn Tất Đơn Hàng - Hoàn tất giao dịch mua

Mỗi bước đều xây dựng dựa trên bước trước đó, tạo ra một trải nghiệm người dùng liền mạch trong khi duy trì tính toàn vẹn dữ liệu trong suốt quá trình.

Các Yêu Cầu và Cài Đặt Ban Đầu

Trước khi bắt đầu triển khai, đảm bảo bạn đã có:

Ứng dụng Medusa v2 đang chạy
Khóa API có thể công khai hợp lệ
Các biến thể sản phẩm, khu vực và tùy chọn giao hàng đã được cấu hình
Nhà cung cấp thanh toán đã được thiết lập (chúng ta sẽ sử dụng mặc định của hệ thống)
curl và jq đã được cài đặt để thực hiện các yêu cầu API và phân tích phản hồi JSON

Cài Đặt `curl` và `jq`

bash Copy

# macOS (sử dụng Homebrew)
brew install curl jq

# Ubuntu/Debian
sudo apt update
sudo apt install curl jq

# Windows (sử dụng Chocolatey)
choco install curl jq

Biến Môi Trường

Thiết lập các biến sau trước khi chạy quy trình thanh toán:

bash Copy

export BASE_URL="http://localhost:9000"
export PUBLISHABLE_KEY="pk_<your_publishable_key_here>"
export REGION_ID="reg_<your_region_id>"
export PRODUCT_VARIANT_ID="variant_<your_variant_id>"
export SHIPPING_OPTION_ID="so_<your_shipping_option_id>"
export PAYMENT_PROVIDER_ID="pp_system_default"

Lưu Ý: Các biến CART_ID và PAYMENT_COLLECTION_ID sẽ được thiết lập trong quá trình thanh toán sau khi tạo giỏ hàng và khởi tạo thu thập thanh toán.

Triển Khai Từng Bước

1. Tạo Giỏ Hàng Mới

Hành trình thanh toán bắt đầu với việc tạo một giỏ hàng mới liên kết với một khu vực cụ thể:

bash Copy

curl -X POST "$BASE_URL/store/carts" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "region_id": "'$REGION_ID'" }'

Điểm Chính:

Mỗi giỏ hàng có một định danh duy nhất được sử dụng trong các cuộc gọi API tiếp theo
Các khu vực xác định tiền tệ, thuế suất và cài đặt thực hiện

2. Thêm Sản Phẩm vào Giỏ Hàng

Khi giỏ hàng đã tồn tại, thêm các biến thể sản phẩm với số lượng đã chỉ định:

bash Copy

curl -X POST "$BASE_URL/store/carts/$CART_ID/line-items" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "variant_id": "'$PRODUCT_VARIANT_ID'", "quantity": 1 }'

Điểm Chính:

Sử dụng variant_id thay vì product_id cho các cấu hình sản phẩm cụ thể
Số lượng có thể được cập nhật bằng cách gọi lại endpoint này
Mức tồn kho sẽ được kiểm tra tự động trong bước này

3. Thiết Lập Địa Chỉ Giao Hàng và Thông Tin Khách Hàng

Cấu hình địa chỉ giao hàng và thông tin liên lạc của khách hàng:

bash Copy

curl -X POST "$BASE_URL/store/carts/$CART_ID" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "Nordmarksvej 9",
      "city": "Billund",
      "country_code": "dk",
      "postal_code": "7190",
      "phone": "1234567890"
    },
    "email": "john.doe@example.com"
  }'

Điểm Chính:

country_code phải khớp với các quốc gia có sẵn trong khu vực
Email là bắt buộc để xác nhận đơn hàng và liên kết tài khoản khách hàng
Địa chỉ thanh toán có thể được thiết lập riêng nếu khác với địa chỉ giao hàng

4. Chọn Phương Thức Vận Chuyển

Lựa chọn từ các tùy chọn vận chuyển có sẵn cho khu vực và địa chỉ của giỏ hàng:

bash Copy

curl -X POST "$BASE_URL/store/carts/$CART_ID/shipping-methods" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "option_id": "'$SHIPPING_OPTION_ID'" }'

5. Tạo Thu Thập Thanh Toán

Khởi tạo hệ thống xử lý thanh toán cho giỏ hàng:

bash Copy

curl -X POST "$BASE_URL/store/payment-collections" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "cart_id": "'$CART_ID'" }'

6. Khởi Tạo Phiên Thanh Toán

Thiết lập phiên nhà cung cấp thanh toán để xử lý:

bash Copy

curl -X POST "$BASE_URL/store/payment-collections/$PAYMENT_COLLECTION_ID/payment-sessions" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "provider_id": "'$PAYMENT_PROVIDER_ID'" }'

Điểm Chính:

Các nhà cung cấp thanh toán (Stripe, PayPal, v.v.) yêu cầu khởi tạo phiên cụ thể
ID của nhà cung cấp phải khớp với các nhà cung cấp thanh toán đã cấu hình trong thiết lập Medusa của bạn
Phiên này chứa ý định thanh toán hoặc tương đương cho nhà cung cấp

7. Hoàn Tất Đơn Hàng

Hoàn tất quy trình thanh toán và tạo đơn hàng:

bash Copy

curl -X POST "$BASE_URL/store/carts/$CART_ID/complete" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY"

Điểm Chính:

Bước này xác nhận tất cả thông tin giỏ hàng và xử lý thanh toán
Tồn kho được giữ lại và xác nhận đơn hàng được kích hoạt
Giỏ hàng được chuyển đổi thành một bản ghi đơn hàng không thể thay đổi

Ví Dụ Triển Khai Hoàn Chỉnh

Dưới đây là một script shell hoàn chỉnh thực hiện toàn bộ quy trình thanh toán:

bash Copy

#!/bin/bash

# Cấu hình
BASE_URL="http://localhost:9000"
PUBLISHABLE_KEY="pk_"
REGION_ID="reg_"
PRODUCT_VARIANT_ID="variant_"
SHIPPING_OPTION_ID="so_"
PAYMENT_PROVIDER_ID="pp_system_default"

# 1. Tạo giỏ hàng
echo "Đang tạo giỏ hàng..."
CART_RESPONSE=$(curl -s -X POST "$BASE_URL/store/carts" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "region_id": "'$REGION_ID'" }')

CART_ID=$(echo $CART_RESPONSE | jq -r '.cart.id')
echo "Giỏ hàng đã được tạo với ID: $CART_ID"

# 2. Thêm sản phẩm vào giỏ hàng
echo "Đang thêm sản phẩm vào giỏ hàng..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID/line-items" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "variant_id": "'$PRODUCT_VARIANT_ID'", "quantity": 1 }' > /dev/null

# 3. Thiết lập địa chỉ giao hàng và email
echo "Đang thiết lập địa chỉ giao hàng..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "Nordmarksvej 9",
      "city": "Billund",
      "country_code": "dk",
      "postal_code": "7190",
      "phone": "1234567890"
    },
    "email": "john.doe@example.com"
  }' > /dev/null

# 4. Thiết lập phương thức vận chuyển
echo "Đang thiết lập phương thức vận chuyển..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID/shipping-methods" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "option_id": "'$SHIPPING_OPTION_ID'" }' > /dev/null

# 5. Tạo thu thập thanh toán
echo "Đang tạo thu thập thanh toán..."
PAYMENT_COLLECTION_RESPONSE=$(curl -s -X POST "$BASE_URL/store/payment-collections" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "cart_id": "'$CART_ID'" }')

PAYMENT_COLLECTION_ID=$(echo $PAYMENT_COLLECTION_RESPONSE | jq -r '.payment_collection.id')
echo "Thu thập thanh toán đã được tạo với ID: $PAYMENT_COLLECTION_ID"

# 6. Khởi tạo phiên thanh toán
echo "Đang khởi tạo phiên thanh toán..."
curl -s -X POST "$BASE_URL/store/payment-collections/$PAYMENT_COLLECTION_ID/payment-sessions" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "provider_id": "'$PAYMENT_PROVIDER_ID'" }' > /dev/null

# 7. Hoàn tất giỏ hàng
echo "Đang hoàn tất đơn hàng..."
ORDER_RESPONSE=$(curl -s -X POST "$BASE_URL/store/carts/$CART_ID/complete" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY")

ORDER_ID=$(echo $ORDER_RESPONSE | jq -r '.order.id')
echo "Đơn hàng đã hoàn tất thành công: $ORDER_ID"

Khắc Phục Sự Cố

Kiểm Tra Tình Trạng Dịch Vụ: Kiểm tra xem dịch vụ có phản hồi hay không bằng cách truy cập http://localhost:9000/store/products trong trình duyệt. Bạn sẽ thấy một phản hồi JSON với các sản phẩm có sẵn.
Xác Nhận Khóa API: Đảm bảo khóa API có thể công khai của bạn là chính xác và có quyền truy cập cho các hoạt động trong cửa hàng.
Không Có Sản Phẩm Nào Có Sẵn: Xác minh rằng có sản phẩm trong cửa hàng của bạn bằng cách kiểm tra endpoint /store/products. Đảm bảo sản phẩm đã được công bố và có biến thể có sẵn.
Địa Chỉ Giao Hàng Không Hợp Lệ:
- Xác nhận định dạng địa chỉ khớp với tiêu chuẩn quốc gia mong đợi
- Đảm bảo country_code có trong danh sách các quốc gia cho phép của khu vực
- Kiểm tra /store/regions/{region_id} để xem các quốc gia có sẵn cho khu vực của bạn
Tùy Chọn Vận Chuyển Không Có Sẵn: Xác minh rằng tùy chọn vận chuyển được kích hoạt cho khu vực và địa chỉ đã chọn. Kiểm tra /store/shipping-options để biết các tùy chọn có sẵn trong khu vực của bạn.
Tồn Kho Không Đủ: Kiểm tra mức tồn kho trước khi thêm sản phẩm. API sẽ trả về lỗi tồn kho nếu số lượng yêu cầu vượt quá mức hàng có sẵn.
Vấn Đề Với Nhà Cung Cấp Thanh Toán:
- Đảm bảo nhà cung cấp thanh toán đã được cấu hình đúng trong thiết lập Medusa của bạn
- Xử lý các lỗi thanh toán một cách nhẹ nhàng với thông báo lỗi phù hợp
- Xác minh thông tin xác thực của nhà cung cấp thanh toán là hợp lệ

Kết Luận

Quy trình thanh toán Medusa cung cấp một nền tảng vững chắc cho các ứng dụng thương mại điện tử với các endpoint API được cấu trúc tốt. Bằng cách làm theo quy trình bảy bước này, bạn có thể xây dựng trải nghiệm thanh toán đáng tin cậy, đáp ứng các yêu cầu thương mại điện tử hiện đại.

Những Điểm Chính:

Mỗi bước phụ thuộc vào việc hoàn thành bước trước đó
Thực hiện xác thực và logic thử lại hợp lý
Theo dõi trạng thái giỏ hàng trong suốt quá trình
Cung cấp phản hồi cho người dùng tại mỗi bước

Cách tiếp cận này hỗ trợ nhiều kịch bản thanh toán khác nhau bao gồm quy trình cho khách, nhiều phương thức thanh toán và mua hàng theo hình thức đăng ký.

Hướng Dẫn Quy Trình Thanh Toán Medusa: Xây Dựng E-Commerce Hoàn Chỉnh

Hướng Dẫn Quy Trình Thanh Toán Medusa: Xây Dựng E-Commerce Hoàn Chỉnh

Hiểu Quy Trình Thanh Toán Medusa

Các Yêu Cầu và Cài Đặt Ban Đầu

Cài Đặt curl và jq

Biến Môi Trường

Triển Khai Từng Bước

1. Tạo Giỏ Hàng Mới

2. Thêm Sản Phẩm vào Giỏ Hàng

3. Thiết Lập Địa Chỉ Giao Hàng và Thông Tin Khách Hàng

4. Chọn Phương Thức Vận Chuyển

5. Tạo Thu Thập Thanh Toán

6. Khởi Tạo Phiên Thanh Toán

7. Hoàn Tất Đơn Hàng

Ví Dụ Triển Khai Hoàn Chỉnh

Khắc Phục Sự Cố

Kết Luận

Những Điểm Chính:

Bình luận

Cài Đặt `curl` và `jq`