Nhảy tới nội dung

callback

API đối tác xây dựng sẽ nhận kết quả thanh toán từ Checkout SDK.

Khi và chỉ khi hoàn tất quá trình thanh toán thì Checkout SDK mới gọi API này để thông báo kết quả.

Merchant Server dựa vào kết quả này để thực hiện hoàn thành thanh toán cho người dùng.

Nếu sau 20 phút mà Merchant Server vẫn không nhận được kết quả, vui lòng gọi API getOrderStatus để tra cứu kết quả cuối cùng.

Đặc tả​

Khi hoàn tất quá trình thanh toán, Checkout SDK Server callback cho Merchant Server theo CallbackURL . Merchant dùng PrivateKey để xác thực data do Checkout SDK Server POST qua.

Lưu ý:

Đối tác cần whitelist cho danh sách địa chỉ IP của Checkout SDK Server:

  • 118.102.2.29
  • 49.213.78.2

Dữ liệu nhận được từ callback​

PropertyTypeDescription
dataObjectDữ liệu gởi về cho ứng dụng
macStringThông tin xác thực của dữ liệu giao dịch, dùng PrivateKey được cung cấp để chứng thực dữ liệu giao dịch. Các dữ liệu sau được sử dụng để tạo mã hash cho thông tin:
  • appId, orderId, transId, amount, description, resultCode, message
overallMacStringThông tin xác thực của toàn bộ dữ liệu, dùng PrivateKey được cung cấp để chứng thực toàn bộ dữ liệu. Các dữ liệu được sắp xếp theo thứ tự từ điển tăng dần để tạo mã hash cho thông tin

  • Đối tác vui lòng tham khảo cách tạo mã hash ở ví dụ phía dưới.
  • Trường hợp đối tác sử dụng các dữ liệu như "method", "extradata", ..., vui lòng kiểm tra overallMac để đảm bảo tính đúng đắn của dữ liệu

Lưu ý:

Đối tác cần kiểm tra tính hợp lệ của mac/overallMac trong callback để đảm bảo kết quả của giao dịch. Lưu ý rằng amount ứng với orderId trong callback cần phải khớp với amount đối tác lưu tại hệ thống của đối tác.

Dữ liệu của trường data​

PropertyTypeDescriptionUse to build mac
appIdStringId định danh của mini apptrue
orderIdStringId của yêu cầu thanh toán đã tạo ở API createOrdertrue
transIdStringId của yêu cầu thanh toán từ hệ thống đối tác thanh toántrue
methodStringPhương thức thanh toán. Tham khảo mã tại đây
transTimeLongThời gian giao dịch của đối tác thanh toán
merchantTransIdStringMã giao dịch của đối tác thanh toán
amountLongSố tiền thanh toántrue
descriptionStringThông tin đơn hàngtrue
resultCodeIntTrạng thái giao dịch của đơn hàng:
  • 1 : Thành công
  • -1 : Thất bại
true
messageStringMô tả mã resultCodetrue
extradataStringThông tin thêm
Lưu ý: Dữ liệu này đã được encodeURIComponent

Kiểm tra tính hợp lệ của dữ liệu​

Kiểm tra mac​

dataForMac =
  "appId={appId}&amount={amount}&description={description}&orderId={orderId}&message={message}&resultCode={resultCode}&transId={transId}";

// Tạo mac từ dữ liệu
reqMac = HMAC("HmacSHA256", privateKey, dataForMac);

// Kiểm tra tính hợp lệ của dữ liệu giao dịch
if (reqMac == mac) {
  // dữ liệu giao dịch hợp lệ
} else {
  // dữ liệu giao dịch không hợp lệ
}

Kiểm tra overallMac​

/*
  Ví dụ với data nhận được bao gồm các trường sau: 
    data = {
      "appId": "123456",
      "orderId": "123456789",
      "transId": "987654321",
      "method": "ZALOPAY",
      "transTime": "1710832784000",
      "merchantTransId": "MT123456789",
      "amount": 10000,
      "description": "Payment_for_goods",
      "resultCode": 1,
      "message": "Payment_successful",
      "extradata": "%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D"
    }
 */

// Sắp xếp toàn bộ dữ liệu theo thứ tự từ điển tăng dần
// Đối với NodeJS
dataOverallMac = Object.keys(data)
  .sort() // sắp xếp key của Object data theo thứ tự từ điển tăng dần
  .map((key) => `${key}=${data[key]}`) // trả về mảng dữ liệu dạng [{key=value}, ...]
  .join("&"); // chuyển về dạng string kèm theo "&", ví dụ: amount={amount}&appId={appId}&description={description}&extradata={extradata}&merchantTransId={merchantTransId}&message={message}&method={method}&orderId={orderId}&resultCode={resultCode}&transId={transId}&transTime={transTime}

// Tạo overall mac từ dữ liệu
reqOveralMac = HMAC("HmacSHA256", privateKey, dataOverallMac);

// Kiểm tra tính hợp lệ của toàn bộ dữ liệu
if (reqOveralMac == overallMac) {
  // dữ liệu hợp lệ
} else {
  // dữ liệu không hợp lệ
}
  • HmacSHA256: Là phương thức bảo mật HmacSHA256
  • PrivateKey: Do Checkout SDK cung cấp cho ứng dụng lúc đăng ký ứng dụng

Thông tin AppServer trả về cho Checkout SDK Server khi nhận callback​

Đối tác vui lòng trả về cho Checkout SDK Server theo định dạng sau:

PropertyTypeDescription
returnCodeintCó các giá trị sau:
  • 1 : thành công
  • 2 : trùng mã giao dịch transId (đã cung cấp dịch vụ cho người dùng trước đó)
  • != : thất bại (không callback lại)
returnMessageStringMô tả chi tiết mã trạng thái

callback

zi-chevron-up