Tài liệu tham khảo API MQ-Pay

Tài liệu tham khảo API đầy đủ cho tích hợp thanh toán MQ-Pay.

URL Cơ sở

Production: https://api.your-domain.com/api/mq-pay
Development: http://localhost:3000/api/mq-pay

Điểm cuối Thanh toán

Tạo Thanh toán

POST /payments/checkout
Content-Type: application/json

{
  "source": {
    "type": "Order",
    "id": "order-uuid-123",
    "uid": "ORD-2024-001"
  },
  "payment": {
    "provider": "VNPAY_QR_MMS",
    "method": "100_QR_CODE",
    "total": 100000,
    "currency": "VND"
  },
  "expiration": {
    "mode": "duration",
    "milliseconds": 300000
  }
}

Phản hồi (200 OK)

{
  "transaction": {
    "id": "txn-uuid-001",
    "number": "TXN001",
    "status": "100_NEW",
    "total": "100000.0000",
    "paid": "0.0000"
  },
  "attempt": {
    "id": "att-uuid-001",
    "code": "ATT001",
    "status": "204_SENT",
    "provider": "VNPAY_QR_MMS",
    "method": "100_QR_CODE"
  },
  "payment": {
    "qrCode": "00020101021238...",
    "qrUrl": "https://...",
    "expiresAt": "2024-01-15T10:35:00Z"
  }
}

Xác nhận Thanh toán Hệ thống

POST /payments/system/ipn
Content-Type: application/json

{
  "attempt": { "id": "att-uuid-001" },
  "tendered": 100000,
  "note": "Thanh toán tiền mặt"
}

Phản hồi (200 OK)

{
  "transaction": {
    "id": "txn-uuid-001",
    "status": "304_SETTLED",
    "paid": "100000.0000"
  },
  "attempt": {
    "id": "att-uuid-001",
    "status": "302_SUCCESS",
    "tendered": "100000.0000"
  },
  "change": "0.0000"
}

Hủy Lần thử Thanh toán

POST /payments/cancel
Content-Type: application/json

{
  "attemptId": "att-uuid-001",
  "reason": "Khách hàng đổi phương thức thanh toán"
}

Phản hồi (200 OK)

{
  "transaction": {
    "id": "txn-uuid-001",
    "status": "100_NEW"
  },
  "cancelledAttempts": [
    {
      "id": "cancel-att-uuid",
      "type": "200_CANCEL_PAYMENT",
      "status": "302_SUCCESS",
      "parentId": "att-uuid-001"
    }
  ]
}

NOTE

Bạn cũng có thể hủy tất cả attempts cho giao dịch bằng cách gửi { "transactionId": "txn-uuid-001" } thay vì attemptId.

Xác minh Lần thử Thanh toán

POST /payments/verify
Content-Type: application/json

{
  "attemptId": "att-uuid-001"
}

Phản hồi (200 OK)

{
  "attempt": {
    "id": "att-uuid-001",
    "status": "302_SUCCESS",
    "provider": "VNPAY_QR_MMS"
  },
  "providerStatus": {
    "responseCode": "00",
    "message": "Success"
  }
}

Hoàn tiền Thanh toán

POST /payments/refund
Content-Type: application/json

{
  "attemptId": "att-uuid-001",
  "amount": 50000,
  "reason": "Hoàn tiền một phần cho mặt hàng trả lại"
}

Phản hồi (200 OK)

{
  "refundAttempt": {
    "id": "refund-att-uuid",
    "type": "300_REFUND_PAYMENT",
    "status": "302_SUCCESS",
    "amount": "50000.0000",
    "parentId": "att-uuid-001"
  }
}

IMPORTANT

Số tiền hoàn không thể vượt quá sốTiềnGốc - đãHoànTiền. Attempt gốc phải ở trạng thái 302_SUCCESS.

Điểm cuối Giao dịch (CRUD)

Tự động tạo qua ControllerFactory tại đường dẫn cơ sở /transactions.

Phương thức	Đường dẫn	Mô tả
GET	/transactions	Liệt kê giao dịch (hỗ trợ filter, phân trang, sắp xếp)
GET	/transactions/:id	Lấy giao dịch theo ID
GET	/transactions/count	Đếm giao dịch khớp với filter
POST	/transactions	Tạo giao dịch
PATCH	/transactions/:id	Cập nhật giao dịch
DELETE	/transactions/:id	Xóa mềm giao dịch

Ví dụ Filter:

GET /transactions?filter={"where":{"sourceType":"Order","sourceId":"order-uuid"}}

Điểm cuối Lần thử Thanh toán (CRUD)

Tự động tạo qua ControllerFactory tại đường dẫn cơ sở /payment-attempts.

Phương thức	Đường dẫn	Mô tả
GET	/payment-attempts	Liệt kê lần thử thanh toán
GET	/payment-attempts/:id	Lấy lần thử theo ID
GET	/payment-attempts/count	Đếm lần thử khớp với filter
POST	/payment-attempts	Tạo lần thử
PATCH	/payment-attempts/:id	Cập nhật lần thử
DELETE	/payment-attempts/:id	Xóa mềm lần thử

Điểm cuối Kết quả Thanh toán (CRUD)

Tự động tạo qua ControllerFactory tại đường dẫn cơ sở /payment-results.

Phương thức	Đường dẫn	Mô tả
GET	/payment-results	Liệt kê kết quả thanh toán
GET	/payment-results/:id	Lấy kết quả theo ID
GET	/payment-results/count	Đếm kết quả khớp với filter
POST	/payment-results	Tạo kết quả
PATCH	/payment-results/:id	Cập nhật kết quả
DELETE	/payment-results/:id	Xóa mềm kết quả

Điểm cuối Mặt hàng Giao dịch (CRUD)

Tự động tạo qua ControllerFactory tại đường dẫn cơ sở /transaction-items.

Phương thức	Đường dẫn	Mô tả
GET	/transaction-items	Liệt kê mặt hàng giao dịch
GET	/transaction-items/:id	Lấy mặt hàng theo ID
GET	/transaction-items/count	Đếm mặt hàng khớp với filter
POST	/transaction-items	Tạo mặt hàng
PATCH	/transaction-items/:id	Cập nhật mặt hàng
DELETE	/transaction-items/:id	Xóa mềm mặt hàng

Mã Trạng thái

Trạng thái Giao dịch

Trạng thái	Mã	Mô tả
NEW	100_NEW	Đã tạo, chưa thanh toán
PARTIAL	300_PARTIAL	Thanh toán một phần
SETTLED	304_SETTLED	Đã thanh toán đầy đủ
CANCELLED	505_CANCELLED	Tất cả attempts bị hủy
BLOCKED	403_BLOCKED	Bị chặn tạm thời
CLOSED	404_CLOSED	Đã đóng vĩnh viễn

Trạng thái Lần thử

Trạng thái	Mã	Mô tả
NEW	100_NEW	Đã tạo, chưa gửi
SENT	204_SENT	Đã gửi đến nhà cung cấp
SUCCESS	302_SUCCESS	Thanh toán đã xác nhận
FAIL	500_FAIL	Lỗi nhà cung cấp
EXPIRED	501_EXPIRED	Hết thời gian chờ

Phản hồi Lỗi

{
  "error": {
    "code": "INVALID_TRANSACTION_STATUS",
    "message": "Không thể thêm thanh toán vào giao dịch đã hoàn tất"
  }
}

Các Mã lỗi Thường gặp

Mã	Mô tả
INVALID_TRANSACTION_STATUS	Trạng thái giao dịch sai
PAYMENT_ATTEMPT_NOT_FOUND	Không tìm thấy ID lần thử
PROVIDER_NOT_CONFIGURED	Nhà cung cấp chưa được kích hoạt
SIGNATURE_MISMATCH	Xác minh IPN thất bại
REFUND_EXCEEDS_REMAINING	Số tiền hoàn > phần còn lại có thể hoàn
ATTEMPT_NOT_SUCCESS	Không thể hoàn tiền lần thử chưa thành công

Liên quan

• Các nhà cung cấp
• Webhooks
• Tổng quan MQ-Pay