Trang chủ/Tích hợp & Nhà phát triển/Yêu cầu thanh toán

Trusted Records · Tích hợp & Nhà phát triển

Yêu cầu thanh toán

Thiết kế yêu cầu thanh toán từ nghiệm thu; không sinh QR thanh toán thật.

Playground dịch vụ — theo tác vụ OpenAPI và Swagger Tham chiếu

Request schema từ OpenAPI

Trường	Kiểu	Bắt buộc	Ràng buộc	Định nghĩa kỹ thuật
`acceptanceRef`	string	Có	`{"minLength": 1, "maxLength": 128}`	Proposed acceptanceRef field. Synthetic identifiers must not contain personal data.
`billingVersion`	integer	Có	`{"minimum": 1}`	Proposed billingVersion field. Synthetic identifiers must not contain personal data.
`amountMinor`	integer	Có	`{"minimum": 1}`	Amount in minor units; synthetic VND uses whole dong and implies no approved price.
`currency`	string	Có	`{"enum": ["VND"], "minLength": 1}`	Proposed currency field. Synthetic identifiers must not contain personal data.
`channel`	string	Có	`{"enum": ["NAPAS_QR_PROPOSED"], "minLength": 1}`	Proposed channel field. Synthetic identifiers must not contain personal data.

Đọc operation và bước xử lý tiếp

Swagger · payment-request

Lỗi và bước xử lý tiếp

Một lỗi envelope thống nhất giúp định tuyến khôi phục mà không lộ dữ liệu nhạy cảm.

Xem chi tiết

Độ tin cậy, concurrency và khôi phục

Thiết kế thử lại phải theo loại tác động, không lặp mọi yêu cầu một cách mù quáng.

Xem chi tiết

API Explorer — mô phỏng cục bộ

Thử yêu cầu/phản hồi và tình huống lỗi bằng dữ liệu tổng hợp; không kết nối backend.

Xem chi tiết

Ranh giới contract

Thiết kế yêu cầu thanh toán từ nghiệm thu; không sinh QR thanh toán thật.

Ngoại lệ và đối soát

Timeout cần query trạng thái; không tạo giao dịch/lệnh mới khi kết quả cũ chưa rõ. Lưu correlation, phiên bản và bằng chứng; không gửi hồ sơ hoặc credential trong nhật ký.

Ví dụ HTTP — contract đề xuất

Request

POST https://records.example.invalid/v1/payment-requests HTTP/1.1
Authorization: Bearer <example-token>
X-Tenant-Id: synthetic-tenant-001
X-Project-Id: synthetic-project-001
X-Correlation-Id: synthetic-correlation-001
Idempotency-Key: synthetic-key-001
Content-Type: application/json

{
  "acceptanceRef": "synthetic-acceptance-001",
  "billingVersion": 1,
  "amountMinor": 125000,
  "currency": "VND",
  "channel": "NAPAS_QR_PROPOSED"
}

Response · 202

{
  "paymentRequestId": "synthetic-payment-001",
  "state": "PENDING",
  "payableQr": null
}

Trường bắt buộc và kiểm soát chung

Mục	Quy tắc đề xuất
scope	billing:write
required	acceptanceRef, billingVersion, amountMinor, currency, channel
tenant / project	Token và context phải khớp; không chỉ tin header.
idempotency	POST/PATCH: cùng key + body trả kết quả cũ; body khác trả 409; window cần chốt.
error	code, message, requestId, correlationId, retryable, details; không chứa dữ liệu nhạy cảm.

Nghiệp vụ tiếp theo

Hai hành trình, một vòng đời hồ sơ

Kết nối hồ sơ giấy và hồ sơ sinh ra ở dạng số bằng định danh, chính sách và bằng chứng xuyên suốt.

Xem chi tiết

Bắt đầu tích hợp

Chạy luồng nhận gói → theo dõi job → đăng ký → xác minh bằng dữ liệu tổng hợp.

Xem chi tiết

Toàn vẹn, nguồn gốc và bằng chứng

Mỗi loại bằng chứng trả lời một câu hỏi; hash, timestamp và phê duyệt không thay thế nhau.

Xem chi tiết

Bắt đầu bằng một phạm vi kiểm tra được.

Chốt loại hồ sơ, tiêu chí chất lượng, quyền và bộ bằng chứng trước khi mở rộng.

Đăng ký khảo sát