---
sourceType: api-reference
sourceTypeMatchedRule: api-prefix
slug: TS/apis/createOrder
title: 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](/docs/TS/usage/gen_signature)                                                                                            |

### Sample request

```json
{
  "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

```json
{
  "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ế. |