# Báo cáo và thanh toán (/vi/platform-api/reporting) Các endpoint này cung cấp quyền truy cập bằng lập trình vào dữ liệu và cài đặt cũng có sẵn trong bảng điều khiển Tapaya Platform. Bạn có thể dùng chúng để xây dựng bảng điều khiển tùy chỉnh, tự động hóa quy trình hoặc lấy dữ liệu báo cáo, bất kể bạn nhúng Accept SDK hay điều khiển trực tiếp ứng dụng Tapaya Terminal. Chúng được xác thực theo cùng một cách, bằng Server Secret Token của bạn. ## Liệt kê merchant [#list-merchants] Liệt kê các merchant đã đăng ký thuộc tổ chức này. **Endpoint:** `GET /integrator/merchant` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \ -H 'Authorization: REPLACE_ME' ``` **Nội dung phản hồi:** ```json [ { "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantToken": "unique_merchant_id_from_your_db", "name": "Acme Corp", "email": "admin@acme.com", "businessType": 1, "city": "Prague", "country": 203, "onboarded": true, "isActive": true } ] ``` Trường `email` là email quản trị / liên hệ hiện được lưu trong bản ghi merchant. Đây là giá trị bạn có thể dùng để đối soát các bản ghi merchant trong hệ thống back-office mà không phải lấy từng merchant một. ## Truy xuất lịch sử thanh toán [#retrieve-payment-history] Lấy danh sách 50 khoản thanh toán gần nhất của tất cả merchant trong tổ chức của bạn. Điều này hữu ích để kiểm tra giao dịch hoặc xây dựng chế độ xem “Super Admin”. Endpoint này luôn trả về 50 khoản thanh toán gần nhất trên toàn tổ chức; hiện endpoint chưa chấp nhận tham số truy vấn cho merchant, trạng thái, khoảng thời gian hoặc phân trang. Dùng endpoint [Truy xuất chi tiết thanh toán](#retrieve-payment-details) để tra cứu một khoản thanh toán cụ thể theo ID. **Endpoint:** `GET /integrator/organization/payment` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \ -H 'Authorization: REPLACE_ME' ``` **Nội dung phản hồi:** ```json [ { "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f", "paymentToken": "pay_abc123", "paymentProcessorId": 1, "paymentMethodId": 1, "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a", "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "statusId": 2, "instrumentLabel": "VISA •••• 4242", "instrumentIdentifier": "4242", "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantName": "Acme Corp" } ] ``` ## Số liệu thống kê tổng hợp [#aggregated-statistics] Lấy số liệu thống kê thanh toán được tổng hợp cho tất cả merchant trong tổ chức của bạn. Endpoint này trả về tổng khối lượng theo từng loại tiền tệ. **Endpoint:** `GET /integrator/organization/payment/stats` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \ -H 'Authorization: REPLACE_ME' ``` **Nội dung phản hồi:** Một mảng với một phần tử cho mỗi loại tiền tệ mà tổ chức của bạn đã xử lý thanh toán. ```json [ { "currencyId": 1, "amount": 4582317 } ] ``` ## Truy xuất chi tiết thanh toán [#retrieve-payment-details] Lấy đầy đủ chi tiết của một khoản thanh toán, bao gồm các giao dịch bên dưới, các lần ghi nợ (charge) và mọi khoản hoàn tiền. Phạm vi giới hạn trong tổ chức của bạn; các khoản thanh toán thuộc tổ chức khác trả về `404`. Một **khoản thanh toán (payment)** là toàn bộ yêu cầu mua hàng: một số tiền cố định cho một phương thức thanh toán. Khoản thanh toán chứa một hoặc nhiều **giao dịch (transaction)**, mỗi giao dịch là một lần thử chuyển tiền qua đơn vị xử lý thanh toán. Một giao dịch chứa một hoặc nhiều **lần ghi nợ (charge)**, mỗi lần là một sự kiện quyết toán cụ thể trên một phương tiện thanh toán nhất định (thẻ, ví điện tử, tài khoản ngân hàng). Hầu hết các khoản thanh toán có đúng một giao dịch với một charge. Một khoản thanh toán có thể có nhiều giao dịch khi thao tác chạm thẻ vào máy thanh toán được thử lại (mỗi lần thử chạm được ghép vào như một giao dịch riêng). Một giao dịch có thể có nhiều charge đối với các phương thức thanh toán bất đồng bộ như tiền mã hóa hoặc chuyển khoản ngân hàng, khi đơn vị xử lý báo cáo các sự kiện quyết toán từng phần hoặc lặp lại theo thời gian (ví dụ: một hóa đơn tiền mã hóa trả thiếu được bù bằng một khoản thanh toán on-chain thứ hai). Các khoản hoàn tiền tham chiếu trực tiếp đến khoản thanh toán và charge; chúng không nằm bên trong giao dịch. `statusId` (`StatusEnum`) phản ánh trạng thái hiện tại của khoản thanh toán: | Giá trị | Tên | Mô tả | | ------- | -------------- | ------------------------------------------------------------- | | `1` | `Pending` | Giao dịch đã được tạo nhưng chưa hoàn tất. | | `2` | `Success` | Giao dịch đã hoàn tất thành công. | | `3` | `Cancelled` | Giao dịch đã bị hủy trước khi hoàn tất. | | `4` | `Refunded` | Giao dịch đã được hoàn tiền sau khi hoàn tất. | | `5` | `Failed` | Giao dịch không hoàn tất được. | | `6` | `ActionNeeded` | Giao dịch cần khách hàng thực hiện thêm thao tác để hoàn tất. | **Endpoint:** `GET /integrator/organization/payment/{paymentId}` cURL ```bash curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \ -H 'Authorization: REPLACE_ME' ``` **Phản hồi:** | Mã | Mô tả | | ----- | ---------------------------------------------------------------------------------- | | `200` | Đã tìm thấy khoản thanh toán | | `404` | Không tìm thấy khoản thanh toán, hoặc khoản thanh toán không thuộc tổ chức của bạn | **Nội dung phản hồi:** ```json { "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f", "paymentToken": "pay_abc123", "paymentProcessorId": 1, "paymentMethodId": 1, "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a", "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "referralFee": 30, "statusId": 2, "terminalName": "Front Counter", "locationName": "Acme Corp, Prague", "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantName": "Acme Corp", "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "transactions": [ { "transactionId": "018f8f2a-7f5c-7a6e-bd5b-6cae5fb0879c", "statusId": 2, "referenceInfo": null, "fxRate": 1.0, "createdAt": "2026-07-15T12:00:00Z", "processedAt": "2026-07-15T12:00:03Z", "cancelledAt": null, "charges": [ { "chargeId": "018f8f2a-8a6d-7b7f-ce6c-7dbf6ac1980d", "chargeToken": "charge_abc123", "statusId": 2, "instrumentLabel": "VISA •••• 4242", "instrumentIdentifier": "4242", "authorizationReference": "123456", "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "fxRate": 1.0, "createdAt": "2026-07-15T12:00:03Z" } ] } ], "refunds": [] } ``` ## Hoàn tiền một khoản thanh toán [#refund-a-payment] Hoàn tiền một khoản thanh toán, toàn bộ hoặc một phần. Bỏ qua `amount` để hoàn toàn bộ số tiền đã quyết toán còn lại. **Endpoint:** `POST /integrator/organization/payment/{paymentId}/refund` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/refund' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "amount": 1999, "refundReasonId": 1 }' ``` **Tham số:** | Trường | Kiểu | Bắt buộc | Mô tả | | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `amount` | `long` | | Số tiền cần hoàn, tính theo đơn vị nhỏ nhất của loại tiền tệ. Bỏ qua để hoàn toàn bộ số tiền đã quyết toán còn lại. | | `refundReasonId` | `int` | ✓ | Lý do hoàn tiền (`RefundReasonEnum`). | **Phản hồi:** | Mã | Mô tả | | ----- | ----------------------------------------------------------------------------------------------------------------- | | `200` | Đã khởi tạo hoàn tiền | | `400` | Lỗi kiểm tra tính hợp lệ của yêu cầu | | `404` | Không tìm thấy khoản thanh toán, hoặc khoản thanh toán không thuộc tổ chức của bạn | | `409` | Không thể hoàn tiền khoản thanh toán ở trạng thái hiện tại, hoặc số tiền yêu cầu vượt quá số tiền còn có thể hoàn | **Nội dung phản hồi:** ```json { "refundId": "018f8f2a-9b7e-7c8a-df7d-8ecf7bd2a91e", "refundToken": "refund_abc123", "statusId": 1, "refundReasonId": 1, "requestedAmount": 1999, "requestedCurrencyId": 1, "settlementAmount": 1999, "settlementCurrencyId": 1, "fxRate": 1.0, "authorizationReference": null, "referralFeeRefund": null, "createdAt": "2026-07-15T12:05:00Z", "processedAt": null } ``` `referralFeeRefund` và `processedAt` được điền bất đồng bộ sau khi đơn vị xử lý thanh toán xác nhận khoản hoàn tiền. Chúng luôn là `null` trong phản hồi tức thì; hãy gọi định kỳ [Truy xuất chi tiết thanh toán](#retrieve-payment-details) để theo dõi trạng thái cuối cùng. Lịch sử thanh toán chỉ trả về các khoản thanh toán gần nhất, nên một khoản thanh toán đã hoàn tiền cũ hơn có thể không còn xuất hiện trong đó.