Khởi tạo giao dịch

API cho phép Merchant Server gửi thông tin đơn hàng đến Transfer Service để khởi tạo giao dịch

• URL: https://api-transfer.zaloplatforms.com/v1/order/create
• Method: POST
• Response Type: application/json

Parameters

Trường	Kiểu dữ liệu	Bắt buộc	Mô tả	Yêu cầu
app_id	String	true	ID ứng dụng merchant đăng ký với Transfer Service	Phải là app_id đã đăng ký với Transfer Service
merchant_order_id	String	true	Mã giao dịch của merchant	Unique trong phạm vi merchant, format YYMMDD_${client_id}, client_id chấp nhận số, chữ hoa, chữ thường, -, _, tối đa 40 ký tự (bao gồm cả YYMMDD_)
merchant_order_time	Long	true	Thời gian tạo đơn hàng phía merchant (timestamp)	Không quá 15 phút so với thời gian hiện tại
timestamp	Long	true	Thời điểm tạo request (timestamp)	Dùng để validate request
expire_duration	Integer	false	Thời gian hết hạn giao dịch (phút)	Min: 5, Max: 180, nếu không truyền/ = 0 → default 15 phút, nếu nhỏ hơn 5 hoặc lớn hơn 180 → báo lỗi
amount	Long	true	Số tiền thanh toán	>= 2.000 VNĐ, <= 20.000.000 VNĐ
description	String	true	Mô tả đơn hàng	Không rỗng, tối đa 25 ký tự
callback_url	String	false	URL callback nhận kết quả thanh toán	Valid HTTPS URL, nếu không truyền sẽ dùng config trên Application Portal
embed_data	String	false	Thông tin bổ sung cho đơn hàng	Chuỗi hợp lệ (ví dụ JSON đã escape)
signature	String	true	Thông tin xác thực request	Chữ ký dùng để xác thực request. Xem tài liệu

Sample request

{
  "app_id": "0752a0528b1762493b06",
  "merchant_order_id": "251208_topup0000",
  "app_time": 1765174194413,
  "amount": 100000,
  "description": "test topup",
  "expire_duration": 5,
  "callback_url": "https://merchant.com/api/callback",
  "embed_data": "{\"promotion_code\":\"SALE2025\",\"customer_tier\":\"gold\"}",
  "timestamp": 1764039951659,
  "signature": "xxxx"
}

Sample response

{
  "error_code": 0,
  "error_message": "Thành công",
  "data": {
    "merchant_order_id": "251209_topup1234",
    "ts_order_id": "291f1c09374cde12875d",
    "status": "QR_GENERATED",
    "app_time": 1765259044935,
    "status_code": 1,
    "created_time": 1765259044980,
    "expire_time": 1765259344980,
    "callback_URL": "",
    "amount": 100000,
    "description": "test topup checkout kit",
    "qr_data": "00020101021238570010A000000727012700069704220113VQRQAAUMJ54060208QRIBFTTA530370454061000005802VN62380107NPS68690823test topup checkout kit6304A058"
  }
}

Error codes

Error code	Error message	Ghi chú
-105	Invalid signature	Lỗi chữ ký xác thực request
-201	Invalid merchant id	Merchant id không hợp lệ
-302	Invalid bank account id	Tài khoản ngân hàng không hợp lệ
-403	Invalid order amount	Số tiền giao dịch không hợp lệ
-410	Invalid order description	Mô tả đơn hàng không hợp lệ
-411	Invalid order expire duration seconds	Thời gian hết hạn giao dịch không hợp lệ
-412	Invalid order client id	Mã client của đơn hàng không hợp lệ
-409	Invalid merchant order time	Thời gian đơn hàng không hợp lệ
-501	Invalid application id	Application id không hợp lệ
-414	Invalid callback url	Callback URL không hợp lệ
-510	Application not exist	Application không tồn tại
-514	Application has no linked bank account	Application chưa liên kết tài khoản ngân hàng

Order status

Status code	Status message	Mô tả
1	QR_GENERATED	Đang chờ thanh toán
2	PAID	Đã thanh toán
3	EXPIRED	Đã hết hạn chờ thanh toán từ ngân hàng. Merchant tự kiểm tra sao kê tài khoản để biết trạng thái thực tế.