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.
Mã lỗi á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 |
|---|---|---|---|
| 0 | Thành công. | Yes | |
| 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. |
| 8000 | Giao dịch đang ở trạng thái cần được người dùng xác nhận thanh toán lại. | 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. |
| 7000 | Giao dịch đang được xử lý. | No | Vui lòng chờ giao dịch được xử lý hoàn tất. |
| 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. |
| 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. |
| 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. |
| 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ợ. |
| 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. |
| 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. |
| 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. |
| 40 | RequestId bị trùng. | No | Vui lòng thử lại với một requestId khác. |
| 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. |
| 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. |
| 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. |
| 44 | Giao dịch bị từ chối vì mã thanh toán không hợp lệ. | No | Mã thanh toán không đúng định dạng. Vui lòng kiểm tra xem khách hàng có dùng đúng MoMo QR thanh toán, hay một số ký tự lạ đã bị thêm vào trong quá trình quét mã do lỗi từ máy POS. Mã thanh toán khả dụng là mã thanh toán đúng với một trong ba định dạng sau: "MM"" + "18 digit" => ví dụ: MM561918531775222861 "mm"" + "18 digit" => ví dụ: mm561918531775222861 "18 digit" => ví dụ: 561918531775222861 |
| 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 | |
| 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. |
| 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). |
| 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. |
| 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. |
| 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. |
| 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ợ. |
| 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. |
| 1030 | Đơn hàng thanh toán thất bại do thông tin không hợp lệ. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. |
| 1080 | Giao dịch hoàn tiền bị từ chối. Giao dịch thanh toán ban đầu không được tìm thấy hoặc xử lý tại thời điểm này. | 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 . |
| 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. |
| 2001 | Giao dịch thất bại do sai thông tin liên kết. | Yes | Token liên kết không tồn tại hoặc đã bị xóa, vui lòng cập nhật dữ liệu của bạn. |
| 2007 | Giao dịch thất bại do liên kết hiện đang bị tạm khóa. | Yes | Token liên kết hiện đang ở trạng thái không hoạt động, do người dùng đã chủ động tạm khóa liên kết. |
| 3001 | Liên kết thất bại do người dùng từ chối xác nhận. | Yes | |
| 3002 | Liên kết bị từ chối do không thỏa quy tắc liên kết. | Yes | Từ chối này thường xảy ra khi partnerClientId dùng trong yêu cầu đã được liên kết với một hoặc nhiều tài khoản MoMo trước đó. Vui lòng liên hệ MoMo để biết thêm chi tiết. |
| 3003 | Hủy liên kết bị từ chối do đã vượt quá số lần hủy. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. |
| 3004 | Liên kết này không thể hủy do có giao dịch đang chờ xử lý. | Yes | Vui lòng kiểm tra nếu có bất kỳ giao dịch chờ liên quan đén token này chưa được yêu cầu capture hoặc cancel (hủy). |
| 4001 | Giao dịch bị hạn chế do người dùng chưa hoàn tất xác thực tài khoản. | Yes | |
| 4010 | Quá trình xác minh OTP thất bại. | Yes | Quá trình xác minh người dùng thất bại. Vui lòng gửi một yêu cầu xác minh người dùng khác để thử lại. |
| 4011 | OTP chưa được gửi hoặc hết hạn. | Yes | Vui lòng yêu cầu gửi một mã OTP khác. |
| 4100 | Giao dịch thất bại do người dùng không đăng nhập thành công. | Yes | |
| 4015 | Quá trình xác minh 3DS thất bại. | Yes | Quá trình xác minh người dùng thất bại. Vui lòng gửi một yêu cầu xác minh người dùng khác để thử lại. |
| 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. |
| 90 | Lỗi kết nối. | No | Vui lòng thử lại sau. |
| 99 | Lỗi không xác định. | Yes | Vui lòng liên hệ MoMo để biết thêm chi tiết. |
| 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. |
| 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. |
| 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. |
| 1008 | Giao dịch thất bại vì số tiền vượt quá hạn mức nhận tiền cho phép của người dùng. | Yes | Vui lòng thử lại yêu cầu chi hộ với số tiền thấp hơn. |
| 1100 | Tài khoản Đối tác không đủ số dư thực hiện giao dịch. Vui lòng liên hệ MoMo để được hỗ trợ. | Yes | Vui lòng liên hệ MoMo top-up vào tài khoản Đối tác để tiếp tục thực hiện giao dịch. |
| 1507 | Không tìm thấy Thẻ Ngân hàng hoặc Tài khoản ngân hàng hoặc BankCode không tồn tại. Vui lòng kiểm tra thông tin Ngân hàng và thực hiện lại. | Yes | Vui lòng kiểm tra và thử lại thông tin Thẻ Ngân hàng hoặc Tài khoản ngân hàng khác hoặc danh sách BankCode được hỗ trợ. |
| 4003 | Chi hộ thất bại vì thông tin tài khoản người nhận không hợp lệ. | Yes | Vui lòng kiểm tra, đảm bảo thông tin tài khoản hợp lệ và thực hiện lại yêu cầu. |
| 8003 | Yêu cầu khởi tạo chi hộ theo lô đã được thực hiện thành công. | No | Vui lòng gửi yêu cầu thực hiện chi hộ theo lô để hoàn tất quy trình. |