Skip to main content

3.2.3 Callback khi giao dịch hoàn tiền được thực hiện

Thông tin chung​

  • API do Đối tác cung cấp cho hệ thống MB Payment Hub gọi để thông báo khi một giao dịch được thực hiện.
Lưu ý

API này chỉ sử dụng cho khách hàng đăng ký sử dụng tính năng thanh toán.

Đặc tả​

Endpoint​

    Do đối tác tự định nghĩa và gửi lại cho hệ thống MB Payment Hub. API cần được public ra internet.
    Method: POST
    Content-Type: application/json
Lưu ý

API có sử dụng checksum để thẩm tra lại các trường quan trọng trong bản tin không bị thay đổi

Thông tin về checksum​

  • Đối với yêu cầu hoàn tiền, checksum có cấu trúc là: merchantCode+id+transactionId+amount+status

    • Trong đó:

      • merchantCode: Mã đối tác
      • id: ID giao dịch
      • transactionId: Mã loại giao dịch
      • amount: Số tiền thực hiện giao dịch
      • status: Trạng thái giao dịch

      Ví dụ

      Chuỗi dữ liệu tương ứng cần mã hóa là: MICAJX014TUYI1121B2601TYEADT100000SUCCESS

    • Băm chuỗi dữ liệu bằng thuật toán HmacSha256 với khóa bí mật của đối tác để tạo ra chuỗi nhị phân sau đó mã hóa chuỗi nhị phân bằng thuật toán Base64

      Ví dụ

      Đối với CALLBACK_CHECKSUM_SECRET=uLK65GkdfJNGmsRymgxhLm6jnYS6eVvU, kết quả sẽ là: elhZg3hVP1np4K99R5YjHKUaMkIfEwfNI41tlBF0q3s=

Thử Nghiệm​

Click để thử nghiệm !

Dữ liệu truyền lên​

  • Hệ thống MB Payment Hub sẽ thực hiện gọi API khi giao dịch hoàn tiền được thanh toán thành công và sẽ truyền các thông sau vào request body:
Tham số(URL)Mô tả
idBẮT BUỘC Kiểu String, tối đa 30 ký tự. ID của giao dịch hoàn tiền
transactionIdBẮT BUỘC Kiểu String, tối đa 30 ký tự. ID của giao dịch thanh toán
amountBẮT BUỘC Kiểu Number. Số tiền hoàn
descriptionBẮT BUỘC Kiểu String, tối đa 200 ký tự. Nội dung giao dịch hoàn tiền
createdTimeBẮT BUỘC Kiểu Date. Thời điểm tạo yêu cầu hoàn tiền
Theo định dạng yyyy-MM-dd’T’HH:mm:ss (ISO 8601)
refundedTimeKiêu Date. Thời điểm thực hiện hoàn tiền
Theo định dạng yyyy-MM-dd’T’HH:mm:ss (ISO 8601)
statusBẮT BUỘC Kiểu String, tối đa 45 ký tự. Trạng thái của đăng ký bao gồm:
PROCESSING: Đang xử lý
SUCCEEDED: Thành công
FAILED: Thất bại
errorCodeKiểu String, tối đa 100 ký tự.
Mã lỗi trong trường hợp hoàn tiền thất bại bao gồm:
customer-account-invalid: Tài khoản/thẻ của khách hàng không hợp lệ
invalid-refund-amount: Số tiền hoàn không hợp lệ
account-balance-insufficient: Tài khoản chuyên chi của đối tác không đủ số dư để hoàn tiền
refund-period-expired: Thời hạn hoàn tiền của giao dịch đã hết
invalid-transaction-status: Trạng thái giao dịch không cho phép hoàn tiền
unknown: Lỗi không xác định. Vui lòng liên hệ với MB để được hỗ trợ
checksumBẮT BUỘC, Kiểu String. Chuỗi mã hóa tạo ra dựa trên các tham số dưới đây:
merchantCode+id+transactionId+amount+status
Trong đó
merchantCode: Mã đối tác
id: ID giao dịch
transactionId: ID của giao dịch thanh toán
amount: Số tiền hoàn lại
status: Trạng thái giao dịch hoàn tiền

Dữ liệu trả về​

  • Hệ thống chỉ cần trả lại HttpStatus 200 khi request được thực hiện thành công.

Tham khảo​