The document describes ZaloPay's APIs for integrating the Zalo On Delivery (ZOD) payment solution. It includes APIs for creating ZOD invoices, getting invoice details, querying order statuses, and receiving payment notifications via callbacks. The APIs use JSON requests and responses along with HMAC authentication to securely integrate payment and order functions.
The document describes ZaloPay's APIs for integrating the Zalo On Delivery (ZOD) payment solution. It includes APIs for creating ZOD invoices, getting invoice details, querying order statuses, and receiving payment notifications via callbacks. The APIs use JSON requests and responses along with HMAC authentication to securely integrate payment and order functions.
The document describes ZaloPay's APIs for integrating the Zalo On Delivery (ZOD) payment solution. It includes APIs for creating ZOD invoices, getting invoice details, querying order statuses, and receiving payment notifications via callbacks. The APIs use JSON requests and responses along with HMAC authentication to securely integrate payment and order functions.
The document describes ZaloPay's APIs for integrating the Zalo On Delivery (ZOD) payment solution. It includes APIs for creating ZOD invoices, getting invoice details, querying order statuses, and receiving payment notifications via callbacks. The APIs use JSON requests and responses along with HMAC authentication to securely integrate payment and order functions.
1. Introduction 2. Domain Analysis & Design 3. Deployment Architecture 4. APIs specification o 4.1 Create ZOD Invoice o 4.2 Get Invoice o 4.3 Query Status o 4.4 Callback ( Instant Payment Notification )
Page 1 / 14 1. Introduction
ZOD ( ZaloPay on delivery ) is a solution, which provides a way for Merchant to create order has the ability to pay later and support ZNS/ZMS notification message
2. Domain Analysis & Design
Page 2 / 14 3. Deployment Architecture
Environment Endpoint Sandbox https://sbapimep.zalopay.vn Production https://apimep.zalopay.vn
Page 3 / 14 4. APIs specification
4.1 Create ZOD Invoice
Sequence diagram
Page 4 / 14 Request o URI: /v2/zod o Method: POST o Content-Type: application/json o Params
No Params Datatype Required Description Comment Example
Identification of the 1 appId string Y application 2 mcRefId string Y 3 hubId string N requested field 4 driverId string N requested field 5 amount int Y 6 mac sting Y 7 receiver metadata Y array of 8 orderInfo Y OrderInfo JSON Object merchandiseSubtotal, Used for external "{\"merchandiseSubtotal\":100000, 9 mcExtInfo Y (string:string) shippingSubtotal info. \"shippingSubtotal\":10000}"
Page 5 / 14 Metadata
No Field name Datatype Description
1 contact string Receiver name
OrderInfo
No Field name Datatype Description
1 trackingNumber string Order's tracking number 2 description string Order's description 3 amount int Order's amount
Create authentication information
mac = HMAC(HmacSHA256, macKey, macInput)
macKey: key generated by ZaloPay system for each merchant macInput = app_id|mc_ref_id|amount|mcExtInfo
Request Page 8 / 14 o URI: /v2/zod/invoice o Method: GET o Params
No Params Datatype Mandatory Description Comment
1 app_id int Y 2 mc_ref_id String Y 3 mac String Y
Create authentication information
mac = HMAC(HmacSHA256, macKey, macInput)
macKey: key generated by ZaloPay system for each merchant macInput = app_id|mc_ref_id
Response
Content-Type: application/json JSON body
No Field name Datatype Description Comment
1 order_url string
Page 9 / 14 4.3 Query Status
Sequence diagram
Request o URI: /v2/zod/status o Method: GET o Content-Type: application/json o Params
Page 10 / 14 No Params Datatype Required MaxLength Description Comment 1 appId string Y AppID provided by ZaloPay 2 mcRefId string Y 64 Merchant's reference ID of the order 3 mac string Y
Create authentication information
mac = HMAC(HmacSHA256, macKey, macInput)
macKey: key generated by ZaloPay system for each merchant macInput = appId|mcRefId
Response
Content-Type: application/json JSON body
No Field name Datatype Description Comment
1: SUCCESS
1 status int Order's status 2: FAILURE
3: UNPAID 2 amount int Order's amount 3 zpTransId string ZaloPay transaction's ID
Description: When the payment is successful, this notification will send to the Merchant server to notify about the transaction. Integration: o Protocol: HTTPS o Method: POST o Content-Type: application/json o URI: provided by the merchant Request body
No Field name Datatype Description
1 data JSON string Data callback 2 mac string Mac string for validating the request. Type of callback: 3 type int 1: Order 2: Agreement
data
No Field name Datatype Description Comment
1 appId string The app identifier is provided by ZaloPay. 2 mcRefId string Merchant order's reference ID 3 amount int Amount of order. 4 zpTransId int The ZaloPay transaction id.
Page 12 / 14 5 serverTime int Server timestamp in milliseconds. 6 channel int Payment channel 7 zpUserId string The identifier of ZaloPay user per merchant. 8 userFeeAmount int Fee amount. 9 discountAmount int Discount amount. 10 userChargeAmount int Amount charged from user
Security:
mac = HMAC(HmacSHA256, callbackKey, {data})
callbackKey: key generated by ZaloPay system for each merchant.
