Chuyển đến nội dung chính

Tạo đơn hàng​

Merchant Server gửi thông tin đơn hàng tới Zalopay Server để tạo đơn hàng.

Request Body required
  • app_id int32 required

    Định danh cho ứng dụng (web, app, pos ...) hay dịch vụ (auto-debit, disbursement ...) của Merchant được cấp khi đăng ký tích hợp phương thức thanh toán với Zalopay.

  • app_user string(50) required

    Thông tin của người dùng thanh toán đơn hàng: id/username của user. Nếu không định danh được có thể dùng thông tin mặc định, chằng hạn như tên ứng dụng và không được để trống.

  • app_trans_id string(40) required

    Mã giao dịch Merchant gửi qua hệ thống Zalopay để user thực hiện thanh toán (TXID của giao dịch đơn hàng). Mã giao dịch phải bắt đầu theo format yymmdd của ngày hiện tại.
    Theo format yymmdd_Mã đơn hàng thanh toán. Ví dụ: 250210_OrderID.
    Merchant dùng giá trị này cho việc tra cứu thông tin trạng thái giao dịch và đối soát, yymmdd phải đúng TimeZone Vietnam (GMT+7) (Vì các giao dịch đối soát theo ngày giờ Việt Nam).

  • app_time int64 required

    Thời gian tạo đơn hàng (unix timestamp in milisecond). Thời gian tính đến milisecond, lấy theo giờ hiện hành.

  • expire_duration_seconds long

    Thời gian hết hạn của đơn hàng. Thời gian tính bằng giây (giá trị nhỏ nhất: 300, giá trị lớn nhất: 2592000).

  • amount int64 required

    Giá trị của đơn hàng.

  • description string(256) required

    Thông tin mô tả về dịch vụ đang được thanh toán dùng để hiển thị cho user trên ứng dụng Zalopay và trên tool quản lý Merchant của Zalopay (mctool).

  • callback_url string

    Đây là URL của Merchant, sau khi Zalopay thu tiền thành công sẽ thông báo kết quả thanh toán của đơn hàng về cho Merchant, theo phương thức callback (server-to-server).
    callback_url có thể được truyền động theo từng đơn hàng hoặc cấu hình mặc định trên hệ thống của Zalopay.

  • sub_app_id string(50)

    Đây là định danh dịch vụ/nhóm dịch vụ sử dụng thanh toán trên ứng dụng của Merchant. Đối với các Merchant đặc biệt, khi tạo đơn hàng cần truyền thông tin này vào.

  • item string(2048) required

    Mảng JSON mô tả các mục đơn hàng. Sử dụng "[]" nếu rỗng

  • embed_data string(2048) required

    Chuỗi JSON bao gồm thông tin đặc biệt của đơn hàng.
    Sử dụng "{}" nếu rỗng
    Một số trường đặc biệt của embed_data:
    preferred_payment_method

    + Kiểu dữ liệu: Array string
    + Định dạng: ["domestic_card", "vietqr", "..."]. Tham khảo tại đây
    + Mô tả: Dùng để hiển thị phương thức thanh toán tùy chọn trên cổng Zalopay, ví dụ: {"preferred_payment_method":["vietqr"]}

    redirecturl

    + Kiểu dữ liệu: string
    + Định dạng: URL
    + Mô tả: Redirect về url này sau khi thanh toán trên cổng Zalopay (override redirect url lúc đăng ký app với Zalopay). Ví dụ: {"redirecturl": "https://docs.zalopay.vn/result"}

    columninfo

    + Kiểu dữ liệu: JSON string
    + Định dạng: {"column_name": "value"}
    + Mô tả: Thêm thông tin hiển thị ở phần Quản lý giao dịch chi tiết trên Merchant tool, nếu cột chưa tồn tại cần vào phần Cài đặt hiển thị dữ liệu để cấu hình. Ví dụ: {"columninfo": "{\"branch_id\": \"HCM\",\"store_id\": \"CH123\",\"store_name\": \"Saigon Centre\",\"mc_campaign_id\": \"FREESHIP\"}"}

    zlppaymentid

    + Kiểu dữ liệu: string
    + Mô tả: Mã thông tin thanh toán. Chỉ truyền khi đối tác cần nhận tiền đối soát về nhiều tài khoản khác nhau. Hệ thống Zalopay sẽ tạo ra một mã Thanh toán (tương ứng với mỗi Tài khoản ngân hàng đối tác cung cấp) và gởi lại cho đối tác thiết lập. Ví dụ: {"zlppaymentid": "P4201372"}

  • mac string required

    Thông tin chứng thực: mac = HMAC(hmac_algorihtm, mac key, hmacinput), chi tiết như bên dưới:
    - hmac_algorihtm: là phương thức bảo mật được Merchant đăng ký với Zalopay, mặc định là HmacSHA256.
    - mac key: được cung cấp bởi Zalopay.
    - hmac_input = app_id + | + app_trans_id + | + app_user + | + amount + | + app_time + | + embed_data + | + item.
    Vui lòng tham khảo phần truyền dữ liệu an toàn để biết thêm chi tiết.

  • bank_code string

    Chỉ áp dụng trong trường hợp thanh toán online, tham khảo chi tiết bên dưới:
    - "bank_code": "", "embed_data": "{"preferred_payment_method": []}": Cổng Zalopay hiển thị danh sách tất cả các hình thức và ngân hàng được hỗ trợ (ATM, CC, Zalopay, Zalopay QR đa năng, Apple Pay ...).
    - "bank_code": "", "embed_data": "{"preferred_payment_method": ["domestic_card", "account"]}": Cổng Zalopay hiển thị form cho người dùng nhập thông tin thẻ ATM để thanh toán.
    - "bank_code": "", "embed_data": "{"preferred_payment_method": ["international_card"]}": Cổng Zalopay hiển thị form cho người dùng nhập thông tin thẻ Tín dụng để thanh toán.
    - "bank_code": "", "embed_data": "{"preferred_payment_method": ["zalopay_wallet"]}": Cổng Zalopay hiển thị Zalopay QR để thanh toán bằng Zalopay/Zalopay trên Zalo.
    - "bank_code": "", "embed_data": "{"preferred_payment_method": ["vietqr"]}": Cổng Zalopay hiển thị Zalopay QR đa năng (VietQR) để thanh toán bằng các ứng dụng Ngân hàng và Zalopay.
    - "bank_code": "", "embed_data": "{"preferred_payment_method": ["bnpl"]}": Cổng Zalopay hiển thị Zalopay QR để thanh toán bằng Zalopay/Zalopay trên Zalo và nguồn tiền thanh toán của user sẽ ưu tiên Tài khoản trả sau.

Responses

OK

Schema
  • return_code integer

    Mã trạng thái. Vui lòng tham khảo mã trạng thái để biết thêm chi tiết.

  • return_message string

    Mô tả mã trạng thái.

  • sub_return_code integer

    Mã trạng thái chi tiết. Vui lòng tham khảo mã trạng thái để biết thêm chi tiết.

  • sub_return_message string

    Mô tả mã trạng thái.

  • zp_trans_token string

    Token của giao dịch.
    Trong trường hợp tích hợp theo mô hình AppToApp, dùng giá trị này để mở ứng dụng Zalopay trên thiết bị của người dùng để người dùng thực hiện thanh toán.
    Trong trường hợp thanh toán token, dùng giá trị này để gọi API Pay by token.

  • order_token string

    Token của đơn hàng.

  • order_url string

    Dùng để chuyển tiếp người dùng đến trang thanh toán trên Cổng Zalopay.

  • qr_code string

    Dùng để tạo Zalopay QR đa năng hiển thị trên ứng dụng bán hàng của Doanh nghiệp.
    Zalopay QR đa năng là một trong những giải pháp thanh toán hoàn toàn mới, chấp nhận thanh toán được thực hiện bởi ứng dụng Zalopay/Zalo & các ngân hàng thuộc hệ thống NAPAS.

Loading...