Dữ liệu đơn hàng Shop Cash và tích hợp bên thứ ba

Khi khách hàng sử dụng Shop Cash cho đơn hàng, Shop Cash được xem là phương thức thanh toán. Đây không phải khoản giảm giá, thẻ quà tặng hay tín dụng cửa hàng. Bất kỳ số dư đơn hàng nào còn lại sẽ được thanh toán bằng Shop Pay hoặc Shop Pay Trả góp.

Ví dụ: nếu khách hàng sử dụng 25 USD Shop Cash cho đơn hàng trị giá 100 USD, thì đơn hàng sẽ bao gồm một khoản thanh toán 25 USD qua Shop Cash và một khoản thanh toán 75 USD qua Shop Pay. Dữ liệu đơn hàng có thể chứa nhiều phương thức thanh toán cho cùng một đơn hàng.

Shop Cash xuất hiện dưới dạng giao dịch đơn hàng với giá trị cổng thanh toán là shop_cash, nếu có hỗ trợ. Giao dịch Shop Cash tuân theo vòng đời giao dịch tiêu chuẩn, bao gồm ủy quyền, thu tiền, hủy giá trị và hoàn tiền. Shop Cash không sử dụng loại giao dịch bán hàng kết hợp.

Nếu khách hàng cũng sử dụng ưu đãi Shop từ Shop Campaigns, thì giá trị do chiến dịch tài trợ sẽ được gộp trong cùng một số tiền giao dịch đơn hàng shop_cash. Phần tiền lấy từ số dư người mua và phần tài trợ từ chiến dịch không được thể hiện dưới dạng các giao dịch đơn hàng riêng biệt. Kể từ tháng 1 năm 2026, chi phí chiến dịch sẽ được tính vào hóa đơn Shopify thay vì trừ vào các khoản thanh toán, vì vậy các giao dịch lập hóa đơn chiến dịch trong hoạt động thanh toán chỉ áp dụng cho các chiến dịch chạy trước ngày đó. Để biết thêm thông tin, hãy tham khảo Phí, Shop Campaigns và Shop Cash.

Hệ thống bên thứ ba dùng để nhập đơn hàng, giao dịch, khoản thanh toán, hoàn tất đơn hàng, hoàn tiền hoặc đơn hàng trả lại cần nhận dạng Shop Cash là phương thức thanh toán. Nếu hệ thống không nhận dạng Shop Cash, quá trình nhập đơn hàng có chứa Shop Cash có thể bị lỗi, thiếu dữ liệu thanh toán hoặc cần ánh xạ thủ công.

Xem lại các yêu cầu sau với nhà cung cấp hệ thống bên thứ ba:

• Hệ thống có thể hỗ trợ nhiều phương thức thanh toán trên một đơn hàng.
• Hệ thống có thể ánh xạ shop_cash thành phương thức thanh toán.
• Hệ thống không xem Shop Cash là khoản giảm giá, thẻ quà tặng hoặc tín dụng cửa hàng.
• Hệ thống lưu trữ ID giao dịch đơn hàng đối với từng hoạt động ủy quyền, thu tiền, hủy giá trị và hoàn tiền của Shop Cash.
• Hệ thống lưu toàn bộ giá trị ủy quyền Shop Cash mà không cắt bớt, nếu giá trị này có trong dữ liệu mà hệ thống nhập.
• Hệ thống xem giá trị ủy quyền là chuỗi ký tự ẩn (opaque string) và không phân tích cú pháp, giải mã, chuẩn hóa, băm hay suy diễn ý nghĩa từ các giá trị này.
• Hệ thống có thể xử lý các khoản hoàn tiền trả lại tiền cho cả Shop Pay và Shop Cash.
• Hệ thống có thể đối soát các giao dịch thanh toán Shop Cash tách biệt với các giao dịch thanh toán bằng thẻ.
• Hệ thống không giả định rằng các giao dịch được trả về theo một thứ tự cụ thể.

Nếu hệ thống bên thứ ba giả định rằng mỗi đơn hàng chỉ có một phương thức thanh toán, hãy liên hệ với nhà cung cấp trước khi xử lý đơn hàng Shop Cash qua hệ thống đó.

Giá trị ủy quyền trên giao dịch Shop Cash là một chuỗi ký tự ẩn (opaque string) có độ dài thay đổi. Đây không phải là mã ủy quyền thẻ ngắn và không thể đọc bằng mắt thường.

Nếu hệ thống ERP, OMS hoặc hệ thống bên thứ ba khác có nhập giá trị ủy quyền Shop Cash, hãy lưu toàn bộ giá trị đúng như định dạng ban đầu. Ưu tiên sử dụng trường văn bản có độ dài thay đổi hoặc không giới hạn.

Khi hệ thống lưu trữ giá trị ủy quyền Shop Cash, hãy làm theo các nguyên tắc sau:

• Không cắt bớt giá trị thành một độ dài cố định ngắn (ví dụ: 50 hoặc 100 ký tự).
• Không phân tích cú pháp hoặc suy diễn ý nghĩa từ bất kỳ phần nào của giá trị.
• Không sử dụng giá trị ủy quyền để xác định giao dịch cho các hoạt động API thu tiền, hủy giá trị hoặc hoàn tiền.

Giá trị ủy quyền bị cắt bớt có thể khiến quá trình nhập dữ liệu của bên thứ ba hoặc hoạt động xử lý nối tiếp của ERP và OMS bị lỗi.

Để hỗ trợ thu tiền, hủy giá trị và hoàn tiền qua Admin API, hãy lưu ID giao dịch đơn hàng và mối quan hệ giao dịch gốc. Hoạt động thu tiền và hủy giá trị trong Admin API sẽ xác định giao dịch ủy quyền thông qua parentTransactionId. Hoạt động hoàn tiền sẽ xác định giao dịch thu tiền có thể hoàn tiền thông qua parentId.

Khi một ứng dụng hoặc tiện ích tích hợp thực hiện hoàn tiền Shop Cash qua API, giao dịch hoàn tiền này phải được gắn với giao dịch gốc là giao dịch thu tiền Shop Cash, không phải giao dịch ủy quyền Shop Cash. Yêu cầu hoàn tiền dựa trên giao dịch ủy quyền sẽ bị từ chối.

Các ứng dụng hoàn tiền và trình xử lý webhook cần xác định giao dịch thu tiền Shop Cash có thể hoàn tiền, tính số dư còn có thể hoàn tiền cho giao dịch thu tiền đó, rồi tạo yêu cầu hoàn tiền dựa trên ID giao dịch thu tiền.

Khi sử dụng Admin API, tệp xuất đơn hàng, tệp xuất khoản thanh toán hoặc tệp xuất của ứng dụng bên thứ ba, hãy xử lý Shop Cash như dữ liệu thanh toán. Tùy thuộc vào tệp xuất hoặc tài nguyên API đang sử dụng, thông tin Shop Cash có thể được thể hiện qua phương thức thanh toán, cổng, giao dịch đơn hàng, giao dịch thanh toán và dữ liệu hoàn tiền.

Khi xây dựng hoặc cập nhật tiện ích tích hợp, hãy lưu trữ các thông tin sau đối với đơn hàng có Shop Cash:

• ID đơn hàng và tên đơn hàng.
• Phương thức thanh toán hoặc giá trị cổng, ví dụ như shop_cash (nếu có).
• ID giao dịch đơn hàng đối với từng giao dịch thanh toán.
• Loại và trạng thái giao dịch, ví dụ như ủy quyền, thu tiền, hoàn tiền hoặc hủy giá trị.
• Số tiền và tiền tệ của giao dịch.
• Mối quan hệ với giao dịch gốc, nếu có.
• ID thanh toán, nếu có.
• Đầy đủ giá trị ủy quyền, nếu hệ thống của bạn có nhập các giá trị này.
• ID thanh toán và ID giao dịch số dư khi đối soát khoản thanh toán.
• ID giao dịch hoàn tiền khi đối soát đơn hàng trả lại.

Để biết chi tiết về các trường Admin API hiện có, hãy xem tài liệu cho nhà phát triển về giao dịch đơn hàng Admin API. Tránh dựa vào các trường không còn dùng nữa như OrderTransaction.authorizationCode đối với tiện ích tích hợp mới.

Ví dụ rút gọn sau đây minh họa đơn hàng 100 USD được thanh toán 75 USD qua Shopify Payments và 25 USD qua Shop Cash. Các giá trị chỉ mang tính minh họa.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash có vẻ giống các giá trị thanh toán hoặc khuyến mãi khác nhưng hệ thống của bạn cần xử lý riêng biệt từng giá trị:

Trước khi phụ thuộc vào hệ thống bên thứ ba đối với đơn hàng có Shop Cash, hãy xác nhận các yêu cầu sau:

• Shop Cash được ánh xạ dưới dạng phương thức thanh toán.
• Đơn hàng sử dụng Shop Cash và Shop Pay được nhập với cả hai phương thức thanh toán.
• Logic của phương thức thanh toán không giả định mỗi đơn hàng có một phương thức thanh toán.
• Giá trị ủy quyền được lưu dưới dạng chuỗi mờ dài và không bị cắt bớt.
• Logic hoàn tiền có thể hoàn lại đúng giao dịch thu tiền.
• Logic hoàn tiền có thể hoàn trả tiền đúng phương thức thanh toán.
• Quá trình đối soát khoản thanh toán có thể tính đến các loại giao dịch tín dụng, hoàn tiền và chiến dịch Shop Cash.
• Dòng công việc hoàn tất đơn hàng, kế toán và trả lại hàng không xử lý Shop Cash là khoản giảm giá.

Nếu bạn sử dụng nhiều hệ thống, hãy hoàn thành quy trình xem xét này với từng hệ thống nhận dữ liệu đơn hàng, giao dịch, khoản thanh toán, quá trình hoàn tất đơn hàng, khoản hoàn tiền hoặc đơn hàng trả lại.