Chuyển nhượng & đối chiếu hợp đồng

Hướng dẫn này hướng tới Agent Java SDK v0.3.0, Java 8+ và hợp đồng công khai được gắn thẻ. Các ví dụ chạy trong phần phụ trợ của đối tác sau khi khởi tạo client trong Bắt đầu nhanh.

Điều kiện tiên quyết mẫu

Đoạn mã Java chia sẻ những nội dung nhập này. Khởi tạo client bằng cách sử dụng Bắt đầu nhanh và lấy platformUserId từ liên kết đã lưu. ID người dùng/đơn đặt hàng mẫu phải được thay thế bằng các giá trị cố định của riêng bạn.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

Chuyển số tiền cố định

Sử dụng transfer để chuyển số tiền cố định. Direction.IN có nghĩa là chuyển từ nền tảng đối tác vào 6MM. Direction.OUT có nghĩa là chuyển từ 6MM quay lại nền tảng đối tác.

Sử dụng chuỗi hoặc BigDecimal cho số lượng. Không sử dụng double hoặc float.

Chuyển khoản bằng `agentUserId`

import com.sixmm.agent.model.Direction;
import com.sixmm.agent.model.TransferRequest;
import com.sixmm.agent.model.TransferResponse;
TransferResponse resp = client.transfer(TransferRequest.fixed(
        "AGT-ORDER-1001",
        "agent-user-001",
        Direction.IN,
        "USDT",
        "10.00"));
System.out.println(resp.orderNo);
System.out.println(resp.orderStatus);
System.out.println(resp.agentUserId);
System.out.println(resp.platformUserId);

Chuyển khoản bằng `platformUserId`

TransferResponse resp = client.transfer(TransferRequest.fixedByPlatformUserId(
        "AGT-ORDER-1002",
        "1188041528",
        Direction.OUT,
        "USDT",
        "5.00"));

Cung cấp cả hai ID

Nếu cả hai ID đều được cung cấp, dịch vụ sẽ xác thực rằng chúng trỏ đến cùng một người dùng bị ràng buộc.

TransferRequest req = TransferRequest
        .fixed("AGT-ORDER-1003", "agent-user-001", Direction.IN, "USDT", "20.00")
        .withPlatformUserId("1188041528");
TransferResponse resp = client.transfer(req);

Các trường yêu cầu:

Cánh đồng	Kiểu	Yêu cầu	Sự miêu tả
`agentOrderNo`	string	Đúng	Số đơn đặt hàng đối tác duy nhất trên toàn cầu
`agentUserId`	string	có điều kiện	Bắt buộc khi `platformUserId` vắng mặt
`platformUserId`	string	có điều kiện	Bắt buộc khi `agentUserId` vắng mặt
`direction`	liệt kê	Đúng	`IN` hoặc `OUT`
`currency`	string	KHÔNG	Được điền từ `defaultCurrency` khi vắng mặt
`amount`	string	Đúng	Chuỗi số thập phân

Các trường phản hồi:

Cánh đồng	Kiểu	Sự miêu tả
`orderNo`	string	Số thứ tự nền tảng
`orderStatus`	string	`SUCCESS`, `FAILED`, `PROCESSING`, v.v.
`agentUserId`	string	ID người dùng phía đối tác
`platformUserId`	string	6MM ID người dùng bên ngoài

Xác nhận đơn hàng và quyền sở hữu

Sau khi transfer được gọi, dịch vụ Đại lý sẽ gọi đồng bộ giao dịch core trên đường dẫn chính. Trong hầu hết các trường hợp, phản hồi API đã chứa kết quả cốt lõi giao dịch đồng bộ.

Kết quả	Nghĩa	Hành động của đối tác
`SUCCESS`	Chuyển thành công	Đánh dấu đơn hàng địa phương là thành công
`FAILED`	Quá trình chuyển bị từ chối hoặc không thành công	Lưu lý do thất bại và hiển thị nó khi thích hợp
`PROCESSING`	Hết thời gian chờ giao dịch hoặc mạng không chắc chắn	Đừng thử lại với số đơn hàng mới. Đợi webhook hoặc gọi `queryOrder`

Yêu cầu về tính bất lực:

Sử dụng một agentOrderNo cho một giao dịch kinh doanh.
Nếu HTTP hết thời gian hoặc mạng bị lỗi, trước tiên hãy truy vấn agentOrderNo tương tự.
Webhooks có thể được thử lại. Sao chép chúng bằng khóa idempotency.

Chuyển tất cả ra ngoài

transferAllOut di chuyển số dư bên 6MM của người dùng có thể rút trở lại nền tảng đối tác.

import com.sixmm.agent.model.TransferAllOutRequest;
import com.sixmm.agent.model.TransferAllOutResponse;
TransferAllOutResponse resp = client.transferAllOut(
        TransferAllOutRequest.of("AGT-ORDER-2001", "agent-user-001", "USDT"));
System.out.println(resp.orderStatus);
System.out.println(resp.amount);

Bởi platformUserId:

TransferAllOutResponse resp = client.transferAllOut(
        TransferAllOutRequest.byPlatformUserId("AGT-ORDER-2002", "1188041528", "USDT"));

amount trong phản hồi là số tiền thực tế được chuyển.

Thứ tự ngược lại

Đảo ngược được sử dụng để bù đắp cho lệnh chuyển thành công khi phần phụ trợ hỗ trợ dòng chảy ngược. Các trường hợp điển hình bao gồm các trường hợp ngoại lệ đối với đơn đặt hàng địa phương của đối tác hoặc khôi phục điều chỉnh thủ công.

import com.sixmm.agent.model.ReverseOrderRequest;
import com.sixmm.agent.model.ReverseOrderResponse;
ReverseOrderResponse resp = client.reverse(ReverseOrderRequest.of(
        "AGT-ORDER-1001",
        "REV-ORDER-1001",
        "partner order rollback"));
System.out.println(resp.orderStatus);

Lĩnh vực:

Cánh đồng	Kiểu	Yêu cầu	Sự miêu tả
`origOrderNo`	string	Đúng	Số lệnh chuyển gốc
`reverseOrderNo`	string	Đúng	Số thứ tự đảo ngược duy nhất trên toàn cầu
`reverseReason`	string	Đúng	Lý do đảo ngược

Ghi chú:

Đảo ngược không phải là thao tác hủy thông thường.
Các lệnh đảo ngược cũng phải bình đẳng theo số thứ tự.
Sau khi lệnh ban đầu bị đảo ngược, webhook có thể đẩy lệnh ban đầu REVERSED trạng thái cuối cùng.

Thứ tự truy vấn

import com.sixmm.agent.model.OrderQueryType;
import com.sixmm.agent.model.QueryOrderRequest;
import com.sixmm.agent.model.QueryOrderResponse;
QueryOrderResponse resp = client.queryOrder(
        QueryOrderRequest.of("AGT-ORDER-1001", OrderQueryType.TRANSFER_IN));
System.out.println(resp.status);
System.out.println(resp.failReason);

Các giá trị orderType được hỗ trợ:

TRANSFER_IN
TRANSFER_OUT

Các trường phản hồi phổ biến:

Cánh đồng	Kiểu	Sự miêu tả
`orderType`	string	Loại lệnh
`orderNo`	string	Số đơn đặt hàng của đối tác
`status`	string	Trạng thái đơn hàng
`direction`	string	`IN` hoặc `OUT`
`transferMode`	string	`FIXED_AMOUNT` hoặc `ALL_OUT`
`currency`	string	Tiền tệ
`amount`	string	Số lượng
`agentUserId`	string	ID người dùng phía đối tác
`platformUserId`	string	6MM ID người dùng bên ngoài
`failReason`	string	Lý do thất bại
`createdAt`	string	Thời gian sáng tạo
`completedAt`	string	Thời gian hoàn thành

Liệt kê đơn hàng

import com.sixmm.agent.model.ListOrdersRequest;
import com.sixmm.agent.model.ListOrdersResponse;
ListOrdersRequest req = ListOrdersRequest.page(1, 20);
req.orderType = "TRANSFER_IN";
req.status = "SUCCESS";
req.startTime = "2026-06-01T00:00:00Z";
req.endTime = "2026-06-16T00:00:00Z";
ListOrdersResponse resp = client.listOrders(req);
System.out.println(resp.total);
resp.orders.forEach(order -> System.out.println(order.orderNo));

Đề xuất phân trang:

page bắt đầu từ 1.
Giữ pageSize ở mức hoặc dưới 100.
Đối với công việc đối chiếu, hãy thực hiện theo từng trang và loại bỏ trùng lặp trước orderNo.

Nguồn và hướng dẫn liên quan

Cuộc gọi lại sự kiện quỹ

transfer.completed có thể mang theo SUCCESS, FAILED hoặc bản cập nhật đơn hàng ban đầu của REVERSED; reverse.completed là sự kiện kết thúc lệnh đảo ngược. transfer.dead có nghĩa là trạng thái cuối cùng vẫn chưa được xác nhận sau khi thử lại và cần điều chỉnh thủ công chứ không phải là lỗi được xác nhận. Chỉ riêng tên sự kiện không chứng minh được tiền đã được ghi có.

Xác nhận thành công khác với chuyển tiền thành công: sau khi ghi lại thông báo targetStatus=FAILED hợp lệ, hãy trả lại HTTP 2xx. Duy trì việc loại bỏ trùng lặp quỹ-sự kiện theo orderType:orderId:targetStatus trong phạm vi người bán và environment.

Các trường sự kiện và ví dụ JSON · Xác minh chữ ký, phản hồi và thử lại