Danh Sách Result Codes
Sau khi gửi API request, bạn sẽ nhận được thông tin phản hồi rằng request của bạn đã được nhận và đã xử lý. Phụ thuộc vào HTTP status code của kết quả phản hồi, thực hiện những xử lý phù hợp:
2xx: request đã được nhận và đã xử lý.4xx: có sai sót trong request.5xx: lỗi từ phía server hoặc lỗi kết nối.
Ngoài HTTP status code, bạn cũng có thể nhận được result code của MoMo và nội dung mô tả (theo EN hoặc VI) trong phản hồi. Mỗi result code mang ý nghĩa khác nhau về kết quả request của bạn, vậy nên dựa vào kết quả đó đưa ra hướng xử lý phù hợp.
Để giảm bớt các tác dụng phụ không mong muốn khi những requests bị trùng lặp, bạn có thể làm theo các chỉ dẫn sau ở phía hệ thống của bạn:
- Triển khai server-to-server notification receiver bất đồng bộ, sử dụng service IPN (Instant Push Notification) của MoMo, thông qua các thuộc tính của ipnUrl trong request.
- Cho phép idempotency trong các API requests: API của MoMo hỗ trợ idempotency trên các requests POST (các phương thức HTTP khác như
GET,DELETE, vàPUTtheo định nghĩa là idempotent).
Hệ thống cổng thanh toán API của MoMo từ phiên bản 2.1 hỗ trợ idempotency, cho phép bạn thử lại 1 request nhiều lần và yên tâm là request đó chỉ được xử lý 1 lần duy nhất. Điều này giúp tránh các hành động lặp lại ngoài ý muốn trong trường hợp thất bại và thử lại. Tất các các result code nếu mang hàm ý "Final status" trong danh sách dưới đây là idempotent, vì vậy các result code khác sẽ trả về kết quả "duplicated requestId" (bị lặp lại) nếu request đó được gửi nhiều lần.
Result codes áp dụng cho tất cả các API của cổng thanh toán, dùng để xác định lỗi thanh toán hoặc hệ thống và lỗi trong quá trình tích hợp.
| Result code | Description | Final Status | Recommended actions | Type |
|---|---|---|---|---|
| 0 | Thành công. | Yes | ||
| 10 | Hệ thống đang được bảo trì. | No | Vui lòng quay lại sau khi bảo trì được hoàn tất. | System error |
| 11 | Truy cập bị từ chối. | No | Cấu hình tài khoản doanh nghiệp không cho phép truy cập. Vui lòng xem lại các thông tin đăng ký và cấu hình trên M4B, hoặc liên hệ trực tiếp với MoMo để được điều chỉnh. | System error |
| 12 | Phiên bản API không được hỗ trợ cho yêu cầu này. | No | Vui lòng nâng cấp lên phiên bản mới nhất của cổng thanh vì, vì phiên bản bạn đang truy cấp hiện không còn được hỗ trợ. | System error |
| 13 | Xác thực doanh nghiệp thất bại. | No | Vui lòng kiểm tra thông tin kết nối, bao gồm cả chữ ký mà bạn đang sử dụng, và đối chiếu với các thông tin được cung cấp từ M4B. | Merchant error |
| 20 | Yêu cầu sai định dạng. | No | Vui lòng kiểm tra định dạng của yêu cầu, các biến thể, hoặc tham số còn thiếu. | Merchant error |
| 21 | Yêu cầu bị từ chối vì số tiền giao dịch không hợp lệ. | No | Vui lòng kiểm tra số tiền hợp lệ và thực hiện lại yêu cầu. | Merchant error |
| 22 | Số tiền giao dịch không hợp lệ. | No | Vui lòng kiểm tra nếu số tiền thanh toán nằm trong giới hạn quy định của yêu cầu thanh toán này. Đối với yêu cầu dạng capture, hãy kiểm tra số tiền capture có bằng với số tiền đã được xác nhận trước đó hay không. | Merchant error |
| 40 | RequestId bị trùng. | No | Vui lòng thử lại với một requestId khác. | Merchant error |
| 41 | OrderId bị trùng. | No | Vui lòng truy vấn trạng thái của orderId này, hoặc thử lại với một orderId khác. | Merchant error |
| 42 | OrderId không hợp lệ hoặc không được tìm thấy. | No | Vui lòng thử lại với một orderId khác. | Merchant error |
| 43 | Yêu cầu bị từ chối vì xung đột trong quá trình xử lý giao dịch. | No | Trước khi thử lại, vui lòng kiểm tra nếu có một giao dịch khác đang được xử lý có thể hạn chế yêu cầu này được tiếp nhận, hoặc orderId được sử dụng không phù hợp với yêu cầu này. | Merchant error |
| 45 | Trùng ItemId | No | Vui lòng kiểm tra và thử lại yêu cầu với ItemId duy nhất. | Merchant error |
| 47 | Yêu cầu bị từ chối vì thông tin không hợp lệ trong danh sách dữ liệu khả dụng | No | Vui lòng kiểm tra và thử lại với yêu cầu khác. | System error |
| 98 | QR Code tạo không thành công. Vui lòng thử lại sau. | Yes | Vui lòng thử lại với yêu cầu khác. | System error |
| 99 | Lỗi không xác định. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. | System error |
| 1000 | Giao dịch đã được khởi tạo, chờ người dùng xác nhận thanh toán. | No | Giao vẫn đang chờ người dùng xác nhận thanh toán; trạng thái của giao dịch sẽ được tự động thay đổi ngay sau khi người dùng xác nhận hoặc hủy thanh toán. | |
| 1001 | Giao dịch thanh toán thất bại do tài khoản người dùng không đủ tiền. | Yes | Merchant error | |
| 1002 | Giao dịch bị từ chối do nhà phát hành tài khoản thanh toán. | Yes | Sự từ chối xảy ra khi thẻ được dùng để thanh toán hiện không còn khả dụng, hoặc kết nối đến hệ thống của nhà phát hành thẻ bị gián đoạn. Vui lòng tạm thời sử dụng phương thức thanh toán khác. | User error |
| 1003 | Giao dịch bị đã bị hủy. | Yes | Giao dịch bị hủy bởi doanh nghiệp hoặc bởi trình xử lý timeout của MoMo. Vui lòng đánh dấu giao dịch này đã bị hủy (giao dịch thất bại). | Merchant error |
| 1004 | Giao dịch thất bại do số tiền thanh toán vượt quá hạn mức thanh toán của người dùng. | Yes | Vui lòng đánh dấu giao dịch này thất bại, và thử lại vào một khoảng thời gian khác. | User error |
| 1005 | Giao dịch thất bại do url hoặc QR code đã hết hạn. | Yes | Vui lòng gửi lại một yêu cầu thanh toán khác. | System error |
| 1006 | Giao dịch thất bại do người dùng đã từ chối xác nhận thanh toán. | Yes | Please send another payment request. | User error |
| 1007 | Giao dịch bị từ chối vì tài khoản không tồn tại hoặc đang ở trạng thái ngưng hoạt động. | Yes | Vui lòng đảm bảo trạng thái tài khoản phải được kích hoạt/ đã xác thực trước khi thực hiện lại hoặc liên hệ MoMo để được hỗ trợ. | System error |
| 1017 | Giao dịch bị hủy bởi đối tác. | Yes | Merchant error | |
| 1026 | Giao dịch bị hạn chế theo thể lệ chương trình khuyến mãi. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. | System error |
| 1080 | Giao dịch hoàn tiền thất bại trong quá trình xử lý. Vui lòng thử lại trong khoảng thời gian ngắn, tốt hơn là sau một giờ. | Yes | Vui lòng kiểm tra nếu orderId hoặc transId được dùng trong yêu cầu này là chính xác, sau đó thử lại yêu cầu hoàn tiền (khuyến khích thử lại sau một giờ đối với giao dịch thanh toán được thực hiện hơn một tháng trước) | Merchant error |
| 1081 | Giao dịch hoàn tiền bị từ chối. Giao dịch thanh toán ban đầu có thể đã được hoàn. | Yes | Vui lòng kiểm tra nếu giao dịch thanh toán ban đầu đã được hoàn thành công, hoặc số tiền hoàn vượt quá số tiền cho phép hoàn của giao dịch thanh toán ban đầu. | Merchant error |
| 1088 | Giao dịch hoàn tiền bị từ chối. Giao dịch thanh toán ban đầu không được hỗ trợ hoàn tiền. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. | Merchant error |
| 2019 | Yêu cầu bị từ chối vì orderGroupId không hợp lệ. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. | Merchant error |
| 4001 | Giao dịch bị từ chối do tài khoản người dùng đang bị hạn chế. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. | User error |
| 4002 | Giao dịch bị từ chối do tài khoản người dùng chưa được xác thực với C06. | Yes | Người dùng cần cập nhật sinh trắc học qua NFC để được phép giao dịch. | User error |
| 4100 | Giao dịch thất bại do người dùng không đăng nhập thành công. | Yes | User error | |
| 7000 | Giao dịch đang được xử lý. | No | Vui lòng chờ giao dịch được xử lý hoàn tất. | Pending |
| 7002 | Giao dịch đang được xử lý bởi nhà cung cấp loại hình thanh toán. | No | Vui lòng chờ giao dịch được xử lý. Kết quả giao dịch sẽ được thông báo ngay khi được xử lý hoàn tất. | Pending |
| 9000 | Giao dịch đã được xác nhận thành công. | No | Đối với thanh toán 1 bước (autoCapture=1), đây có thể xem như giao dịch thanh toán đã thành công. Đối với thanh toán 2 bước (autoCapture=0), vui lòng thực hiện tiếp yêu cầu capture hoặc cancel. Đối với liên kết, vui lòng tiến hành yêu cầu lấy recurring token. | Pending |