Skip to main content

Create a new order​

Merchant Server establish order information then send to Zalopay Server to create order.

Request Body required
  • app_id int32 required

    The unique ID of the application will be provided after the merchant registered successfully with Zalopay.

  • app_user string required

    The merchant ID.

  • app_trans_id string required

    Unique transaction ID of application, format: yyMMddxxxxxxxxx. Max length is 40. For example: 180208181007242

  • app_time int64 required

    The timestamp that order was created at in ms. The different limit is 15 mitnutes.

  • amount int64 required

    Amount of money will be charged.

  • title string

    Optional title of order.

  • description string required

    Users will see this text when they are in the confirm payment screen.

  • callback_url string

    Zalopay will use this URL to notify when the payment success. If not provided, the default app callback URL will be used.

  • device_info string

    JSON string describes the device specification.

  • item string required

    JSON string describes order items.

  • embed_data string required

    Application's own data. Use "{}" if empty".
    JSON string include special information of order.
    Specific embed_data's fields:
    preferred_payment_method

    + DataType: array string
    + Format: ["domestic_card", "vietqr", "..."]. Refer to here
    + Description: Used to display optional payment methods on the Zalopay portal, example: {"preferred_payment_method":["vietqr"]}

    redirecturl

    + DataType: string
    + Format: URL
    + Description: Redirect to this url after successful / failure payment via Zalopay Gateway (This will override the merchant's redirect url registered with Zalopay). Example: {"redirecturl": "https://docs.Zalopay.vn/result"}

    columninfo

    + DataType: json string
    + Format: {"column_name": "value"}
    + Description: Add information into the section Management of transaction details on Merchant site, If the column does not yet exist, please go to the Display data configuration setting to configure. Example: {"columninfo": "{\"branch_id\": \"HCM\",\"store_id\": \"CH123\",\"store_name\": \"Saigon Centre\",\"mc_campaign_id\": \"FREESHIP\"}"}

    promotioninfo

    + DataType: json string
    + Format: {"campaigncode":"code"}
    + Description: Use to launch promotions campaign. Example: {"promotioninfo": "{\"campaigncode\":\"blackfriday\"}"}

    zlppaymentid

    + DataType: string
    + Description: Payment information. Only needed when you need to receive money for different accounts. Zalopay system will generate a Payment code (corresponding to each partner bank account provided) and send it back to the partner to set up. Example: {"zlppaymentid": "P4201372"}

    subscription

    + DataType: json string
    + Description: Information about subscription payment.

    - id: A unique identifier for each subscription package, reuse this id when renewing the same subscription package.
    - plan_name: Name of subscription.
    - base_price: This is the initial subscription cost, before any discounts, taxes, or additional fees are applied. This is the expected renewal amount in the next cycle.
    - start_date: The date and time when the subscription was activated.
    - end_date: The date and time when the subscription period ends.
    - reminder_before: X days before the renewal to send a reminder (optional).
    - billing_cycle: The recurring interval. Valid values: yearly, monthly, weekly, 3 months, 2 weeks, 10 days,... (optional)

    + Example: {"subscription":"{\"id\":\"PACKAGE_1\",\"name\":\"Monthly TV Package\",\"base_price\":100000,\"start_date\":\"2024-11-01T00:00:00+07:00\",\"end_date\":\"2024-11-30T23:59:59+07:00\",\"reminder_before\":3,\"billing_cycle\":\"monthly\"}"}
    + Notes: start_date and end_date follow the ISO 8601. For example: "2024-11-01T00:00:00+07:00".

  • mac string required

    It is signature of order. It's calculated by following input: hmac_input = app_id + | + app_trans_id + | + app_user + | + amount

    • | + app_time + | + embe_data + | + item and use SHA256 with app's hmac key as sign key.

    Please refer to secure data transmission for detailed information.

  • product_code string

    Possible values: [AGREEMENT]

    If the order is for Agreement, this field must be AGREEMENT.

  • bank_code string
  • phone string

    User phone

  • email string

    User email

  • address string

    User address

Responses

OK

Schema
  • return_code integer

    Status code of this operation. Please refer to status code for possible values

  • return_message string
  • sub_return_code integer

    The detailed reason explains if the operation has failed. Please refer to sub status code for possible values

  • sub_return_message string
  • zp_trans_token string
  • order_url string
Loading...