Lấy chi tiết Payment Session (Backend)

API cho phép Order Backend / MiniApp Backend truy vấn chi tiết và trạng thái của một Payment Session (luồng thanh toán tập trung). Dùng khi cần kiểm tra trạng thái session (PENDING, PROCESSING, COMPLETED, CANCELLED, EXPIRED) hoặc lấy thông tin breakdown (VPoint, voucher, số tiền cuối) mà chưa nhận IPN hoặc cần đồng bộ trạng thái.

Xem luồng thanh toán tập trung: Thanh toán tập trung (MiniApp).

Use case

MiniApp Backend cần poll/query trạng thái payment session tương ứng với order (thay vì chỉ chờ IPN).
Hiển thị trạng thái thanh toán cho user (đang xử lý, thành công, thất bại, đã hết hạn).
Đối soát / audit: xem chi tiết session (số tiền gốc, VPoint đã tiêu, voucher đã áp, số tiền cuối).

Endpoint

GET /api/payments/v1/payment-sessions

Authentication

API yêu cầu xác thực bằng X-Payment-API-Key. Dành cho Order Backend / service nội bộ, không dành cho client/frontend gọi trực tiếp.

Headers

Header	Required	Mô tả
`X-Payment-API-Key`	✅	API key của merchant/terminal
`X-Request-ID`	❌	Unique request ID (UUID) – khuyến nghị cho tracing

Query Parameters

Phải cung cấp một trong hai cách sau:

Cách 1: paymentSessionId (nếu đã có từ SDK / event trước đó).
Cách 2: orderId + referenceId (khớp với order đã dùng khi gọi initPaymentSession).

Parameter	Required	Type	Mô tả
`paymentSessionId`	Không*	string (UUID)	ID payment session
`orderId`	Không*	string	Mã đơn hàng
`referenceId`	Không*	string	Mã tham chiếu

*Bắt buộc: gửi paymentSessionId HOẶC cả orderId và referenceId.

Response

Success (200 OK)

{
  "code": 0,
  "message": "Success",
  "data": {
    "paymentSessionId": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "Order_001",
    "referenceId": "Ref_001",
    "status": "COMPLETED",
    "amount": 70000,
    "currency": "VND",
    "originalAmount": 100000,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:05:00Z",
    "expiresAt": "2024-01-15T10:30:00Z",
    "breakdown": [
      {
        "type": "PAYMENT",
        "amount": 70000,
        "status": "SUCCESS",
        "referenceId": "PSP_TXN_123",
        "referenceType": "TRANSACTION",
        "details": { "method": "CARD", "provider": "ONEPAY" }
      },
      {
        "type": "VOUCHER",
        "amount": 10000,
        "status": "SUCCESS",
        "referenceId": "PROMO_REV_123",
        "referenceType": "RESERVATION",
        "details": { "voucherCodes": ["VOUCHER_2025"], "promotionIds": ["PROMO_001"] }
      },
      {
        "type": "VPOINT",
        "amount": 20000,
        "status": "SUCCESS",
        "referenceId": "PROMO_REV_123",
        "referenceType": "REDEMPTION",
        "details": { "points": "20000" }
      }
    ],
    "transactionId": "Txn_001"
  }
}

Response field details

Field	Type	Mô tả
`data.paymentSessionId`	string (UUID)	ID payment session
`data.orderId`	string	Mã đơn hàng
`data.referenceId`	string	Mã tham chiếu
`data.status`	string	Trạng thái session: `PENDING`, `PROCESSING`, `COMPLETED`, `CANCELLED`, `EXPIRED`
`data.amount`	number	Số tiền cuối cùng (sau VPoint/voucher) – số tiền user thực trả qua kênh online
`data.currency`	string	Mã tiền tệ (VD: VND, USD)
`data.originalAmount`	number	Số tiền gốc đơn hàng (trước giảm giá)
`data.createdAt`	string (ISO 8601)	Thời điểm tạo session
`data.updatedAt`	string (ISO 8601)	Thời điểm cập nhật gần nhất
`data.expiresAt`	string (ISO 8601)	Thời điểm session hết hạn (nếu có)
`data.breakdown`	array	Chi tiết nguồn tiền (có khi session đã COMPLETED); format giống Breakdown trong IPN
`data.breakdown[].type`	string	Loại: `PAYMENT`, `VOUCHER`, `VPOINT`, v.v.
`data.breakdown[].amount`	number	Số tiền tương ứng
`data.breakdown[].status`	string	Trạng thái từng item (phần tử) trong `breakdown`: `PENDING`, `SUCCESS`, `FAILED`, `CANCELLED` — Breakdown trong IPN
`data.breakdown[].referenceId`	string	(Optional) ID tham chiếu từ downstream cho dòng breakdown; cùng contract Breakdown trong IPN
`data.breakdown[].referenceType`	string	(Optional, đi cặp `referenceId`) `TRANSACTION` / `RESERVATION` / `REDEMPTION`, …
`data.breakdown[].details`	object (map)	Map key-value theo từng `type`; giá trị có thể là scalar hoặc mảng (ví dụ `voucherCodes`). Đồng bộ payment-ipn.
`data.transactionId`	string	ID giao dịch thanh toán (có khi status = COMPLETED/FAILED)

Lưu ý: breakdown thường chỉ có khi status = COMPLETED. Tổng amount của tất cả phần tử trong breakdown bằng tổng giá trị đơn (thường bằng data.originalAmount). Trong đó data.amount là phần tiền user thực trả qua kênh online (tương ứng mục type: PAYMENT trong breakdown).

Session status

Status	Mô tả
`PENDING`	Session vừa tạo; user đang thao tác (VPoint, voucher, chọn phương thức)
`PROCESSING`	Đang gọi provider thanh toán
`COMPLETED`	Thanh toán thành công; có thể có `breakdown` và `transactionId`
`CANCELLED`	User hoặc hệ thống đã hủy session
`EXPIRED`	Session hết hạn (không thao tác trong thời gian cho phép)

Error responses

HTTP Status	Code	Mô tả
400	4001	Thiếu hoặc invalid params (phải có paymentSessionId HOẶC orderId + referenceId)
401	4101	Thiếu hoặc invalid `X-Payment-API-Key`
404	4404	Không tìm thấy payment session với điều kiện truy vấn

Routing qua Mule

API được gọi từ Order Backend tới Payment Hub qua MuleSoft. Base URL và headers (client_id, client_secret) giống các API payment khác – xem Lấy danh sách phương thức thanh toán.

Ví dụ (qua Mule):

curl --location '{MULE_INTERNAL_BASE_URL}/payment-hub/api/payments/v1/payment-sessions?orderId=Order_001&referenceId=Ref_001' \
--header 'X-Payment-API-Key: <YOUR_PAYMENT_API_KEY>' \
--header 'X-Request-ID: 550e8400-e29b-41d4-a716-446655440000' \
--header 'client_id: YOUR_CLIENT_ID' \
--header 'client_secret: YOUR_CLIENT_SECRET'

Liên kết liên quan

Thanh toán tập trung (MiniApp) – Luồng và khái niệm Payment Session.
Xử lý kết quả thanh toán (IPN) – Webhook kết quả; cấu trúc breakdown: Breakdown trong IPN.
Khởi tạo thanh toán từ Backend – API initPayment (luồng chuẩn).

Use case​

Endpoint​

Authentication​

Headers​

Query Parameters​

Response​

Success (200 OK)​

Response field details​

Session status​

Error responses​

Routing qua Mule​

Liên kết liên quan​